Anchord AI Entities API

openapi: 3.2.0
info:
  title: AnchorID Entities API
  version: 1.0.0
  description: 'Anchord''s multi-tenant identity resolution + safe-write gate (v1). Read-only — never writes back to external systems. Guard/write endpoints are evaluation-only: they return a decision, the caller executes.'
servers:
- url: https://api.anchord.ai/api
  description: Production
- url: https://staging.api.anchord.ai/api
  description: Staging (testing environment)
security:
- bearerAuth: []
tags:
- name: Entities
paths:
  /v1/entities/{entity_id}:
    get:
      tags:
      - Entities
      summary: Get an entity by id
      description: 'If the requested entity has been merged (tombstoned), the response transparently returns the canonical entity payload with redirected: true. Use ?include_tombstone=true to also receive the original tombstone entity for audit/debug.'
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - name: include
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated include list (links, source_records).
      - name: include_tombstone
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Entity response.
          content:
            application/json:
              schema:
                type: object
                required:
                - entity
                - requested_entity_id
                - canonical_entity_id
                - redirected
                - request_id
                properties:
                  entity:
                    $ref: '#/components/schemas/Entity'
                  requested_entity_id:
                    type: string
                    format: uuid
                  canonical_entity_id:
                    type: string
                    format: uuid
                  redirected:
                    type: boolean
                  tombstone:
                    $ref: '#/components/schemas/Entity'
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/Link'
                  source_records:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  request_id:
                    type: string
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getV1EntitiesByEntityId
      x-operation-id-source: derived
  /v1/entities/{entity_id}/export:
    get:
      tags:
      - Entities
      summary: Export an entity as a golden record bundle
      description: Returns the entity with all linked source records and provenance metadata. Defaults to including both links and source_records if include is omitted.
      parameters:
      - $ref: '#/components/parameters/EntityId'
      - name: include
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated include list (links, source_records). Defaults to all.
      - name: include_payload
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include raw source record payloads.
      - name: include_tombstone
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Golden record export bundle.
          content:
            application/json:
              schema:
                type: object
                required:
                - entity
                - requested_entity_id
                - canonical_entity_id
                - redirected
                - request_id
                properties:
                  entity:
                    $ref: '#/components/schemas/Entity'
                  requested_entity_id:
                    type: string
                    format: uuid
                  canonical_entity_id:
                    type: string
                    format: uuid
                  redirected:
                    type: boolean
                  tombstone:
                    $ref: '#/components/schemas/Entity'
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/Link'
                  source_records:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  identifiers:
                    type: object
                    additionalProperties: true
                  provenance:
                    type: object
                    properties:
                      generated_at:
                        type: string
                        format: date-time
                      request_id:
                        type: string
                      tenant_id:
                        type: string
                        format: uuid
                      entity_id:
                        type: string
                        format: uuid
                  request_id:
                    type: string
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getV1EntitiesByEntityIdExport
      x-operation-id-source: derived
  /v1/entities/{entity_id}/targets:
    get:
      tags:
      - Entities
      summary: Get per-system target IDs for an entity
      description: Returns all linked source records grouped by system so an agent can determine where to act. Includes integration-level provenance (integration_id, label, external_id) for multi-instance disambiguation.
      parameters:
      - $ref: '#/components/parameters/EntityId'
      responses:
        '200':
          description: Target map returned.
          content:
            application/json:
              schema:
                type: object
                required:
                - entity
                - targets
                - request_id
                properties:
                  entity:
                    type: object
                    required:
                    - id
                    - kind
                    properties:
                      id:
                        type: string
                        format: uuid
                      kind:
                        $ref: '#/components/schemas/EntityKind'
                      name:
                        type: string
                        nullable: true
                  targets:
                    $ref: '#/components/schemas/TargetMap'
                  request_id:
                    type: string
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getV1EntitiesByEntityIdTargets
      x-operation-id-source: derived
  /v1/entities/{entity_id}/merge:
    post:
      tags:
      - Entities
      summary: Merge this entity with another
      description: 'Merge two entities. If into_entity_id is provided, merge {entity_id} into that target (target becomes canonical). If omitted, provide other_entity_id and the system picks the recommended winner via MergeRecommendationService. Set dry_run: true to preview without writing.'
      parameters:
      - $ref: '#/components/parameters/EntityId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reason
              properties:
                into_entity_id:
                  type: string
                  format: uuid
                  description: Target canonical entity. Mutually exclusive with other_entity_id.
                other_entity_id:
                  type: string
                  format: uuid
                  description: Other entity to compare. System recommends the winner.
                reason:
                  type: string
                  maxLength: 255
                dry_run:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Merge result (or dry-run preview).
          content:
            application/json:
              schema:
                type: object
                properties:
                  dry_run:
                    type: boolean
                  requested_entity_id:
                    type: string
                    format: uuid
                  merged_entity_id:
                    type: string
                    format: uuid
                  canonical_entity_id:
                    type: string
                    format: uuid
                  already_merged:
                    type: boolean
                  links_moved:
                    type: integer
                  links_deduped:
                    type: integer
                  resolution_attempts_moved:
                    type: integer
                  guard_audits_moved:
                    type: integer
                  collisions:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        winner_value: {}
                        loser_value: {}
                  preview:
                    type: object
                    description: Present only on dry_run responses.
                    properties:
                      links_to_move:
                        type: integer
                      links_to_dedupe:
                        type: integer
                      resolution_attempts_to_move:
                        type: integer
                      guard_audits_to_move:
                        type: integer
                      collisions:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                            winner_value: {}
                            loser_value: {}
                  recommendation:
                    type: object
                    properties:
                      recommended_canonical_entity_id:
                        type: string
                        format: uuid
                      scores_by_entity_id:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            score:
                              type: number
                            components:
                              type: object
                              additionalProperties: true
                      explanations:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                            code:
                              type: string
                      recommendation_confidence:
                        type: string
                        enum:
                        - high
                        - medium
                        - low
                  request_id:
                    type: string
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Entity not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Invalid merge (self-merge
          cycle: null
          or cross-tenant).: null
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postV1EntitiesByEntityIdMerge
      x-operation-id-source: derived
components:
  schemas:
    LinkSource:
      type: string
      enum:
      - resolution
      - auto_resolve
      - reconcile
      - manual
      - merge
      - api
      - manual_review
      description: 'How a source record was linked to an entity (provenance). resolution = query-time resolve, auto_resolve = post-ingest exact match, reconcile = deferred fuzzy reconciliation, manual = user action, merge = entity merge/dedup, api = public link API, manual_review = review confirm.

        '
    TargetMap:
      type: object
      description: 'Keys are system names (hubspot, salesforce, stripe, etc.). Values are arrays of target records from that system.

        '
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/TargetEntry'
    EntityKind:
      type: string
      enum:
      - company
      - person
    Entity:
      type: object
      required:
      - id
      - kind
      - merge_state
      properties:
        id:
          type: string
          format: uuid
        kind:
          $ref: '#/components/schemas/EntityKind'
        name:
          type: string
          nullable: true
        domain:
          type: string
          nullable: true
          description: Primary canonical domain (company entities).
        identifiers:
          type: object
          additionalProperties: true
          description: 'Contains both flat primary identifier keys and structured multi-value arrays. Flat keys (e.g. email, stripe_customer_id) are the primary/canonical values used for highest-confidence matching. Structured arrays (emails, domains, external_ids) accumulate all known values from linked source records over time.

            '
          properties:
            email:
              type: string
              description: Primary canonical email (person entities).
            emails:
              type: array
              description: All known emails accumulated from linked source records.
              items:
                type: object
                properties:
                  value:
                    type: string
                  source:
                    type: string
                    description: System that provided this email.
                  source_record_id:
                    type: string
                    format: uuid
            domains:
              type: array
              description: All known domains accumulated from linked source records.
              items:
                type: object
                properties:
                  value:
                    type: string
                  source:
                    type: string
                    description: System that provided this domain.
                  source_record_id:
                    type: string
                    format: uuid
            external_ids:
              type: array
              description: External system identifiers with integration-level provenance.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Identifier type (e.g. stripe_customer_id, salesforce_account_id).
                  value:
                    type: string
                  source:
                    type: string
                  integration_id:
                    type: string
                    format: uuid
                    description: Which integration instance provided this ID.
                  integration_label:
                    type: string
                    description: Human-friendly label for the integration instance.
                  source_record_id:
                    type: string
                    format: uuid
        metadata:
          type: object
          additionalProperties: true
        merge_state:
          $ref: '#/components/schemas/MergeState'
        canonical_entity_id:
          type: string
          format: uuid
          nullable: true
          description: Points to the canonical entity when this entity has been merged.
        merged_at:
          type: string
          format: date-time
          nullable: true
        merge_reason:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    MergeState:
      type: string
      enum:
      - canonical
      - merged
    ErrorResponse:
      type: object
      required:
      - error
      - request_id
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        request_id:
          type: string
    Link:
      type: object
      properties:
        id:
          type: string
          format: uuid
        entity_id:
          type: string
          format: uuid
        source_record_id:
          type: string
          format: uuid
        confidence:
          type: number
          nullable: true
        linked_by:
          $ref: '#/components/schemas/LinkSource'
        linked_at:
          type: string
          format: date-time
          nullable: true
        unlinked_at:
          type: string
          format: date-time
          nullable: true
    TargetEntry:
      type: object
      required:
      - object_type
      - object_id
      - source_record_id
      properties:
        object_type:
          type: string
        object_id:
          type: string
        source_record_id:
          type: string
          format: uuid
        linked_by:
          $ref: '#/components/schemas/LinkSource'
        confidence:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
        integration_id:
          type: string
          format: uuid
          nullable: true
        integration_label:
          type: string
          nullable: true
        integration_external_id:
          type: string
          nullable: true
  parameters:
    EntityId:
      name: entity_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Canonical entity id (UUID).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer