> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Link

> Link imported people into one, from the next import on.

Every account of the other people maps to the first from now on, so the
next import puts their records on one person. Nothing already imported
moves: the people being merged must have no imported messages yet, so
reset the import (`POST /ingest/reset`), link, then import again. Only
workspace and admin keys may call it.

Experimental: ingest may change or stop working without notice.

> [!WARNING]
>
> Ingest is experimental: this endpoint may change or stop working without notice. See [Ingesting Source Records](https://honcho.dev/docs/v3/documentation/features/advanced/ingest.md).


## OpenAPI

````yaml post /v3/workspaces/{workspace_id}/ingest/link
openapi: 3.1.0
info:
  title: Honcho API
  summary: The Identity Layer for the Agentic World
  description: >-
    Honcho is a platform for giving agents user-centric memory and social
    cognition.
  contact:
    name: Plastic Labs
    url: https://honcho.dev/
    email: hello@plasticlabs.ai
  license:
    name: GNU Affero General Public License v3.0
    url: https://github.com/plastic-labs/honcho/blob/main/LICENSE
  version: 3.6.2
servers:
  - url: https://api.honcho.dev
    description: Production SaaS Platform
security: []
paths:
  /v3/workspaces/{workspace_id}/ingest/link:
    post:
      tags:
        - ingest
      summary: Link
      description: |-
        Link imported people into one, from the next import on.

        Every account of the other people maps to the first from now on, so the
        next import puts their records on one person. Nothing already imported
        moves: the people being merged must have no imported messages yet, so
        reset the import (`POST /ingest/reset`), link, then import again. Only
        workspace and admin keys may call it.

        Experimental: ingest may change or stop working without notice.
      operationId: link_v3_workspaces__workspace_id__ingest_link_post
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the workspace
            title: Workspace Id
          description: ID of the workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestLink'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestLinkResult'
        '404':
          description: Workspace or peer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            Not an auto workspace, or the people involved already have imported
            messages: reset the import first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '503':
          description: >-
            Contention outlasted the retries; nothing changed. Calling again is
            safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    IngestLink:
      properties:
        peers:
          items:
            type: string
            maxLength: 512
            minLength: 1
            pattern: ^[a-zA-Z0-9_-]+$
          type: array
          maxItems: 20
          minItems: 2
          title: Peers
          description: >-
            Peer IDs. Every account of the others maps to the first from the
            next import on
      type: object
      required:
        - peers
      title: IngestLink
      description: 'People to link into one: the first is kept.'
    IngestLinkResult:
      properties:
        peer_id:
          type: string
          title: Peer Id
        merged:
          items:
            type: string
          type: array
          title: Merged
          description: The people linked into it
        accounts:
          items:
            $ref: '#/components/schemas/IngestAccount'
          type: array
          title: Accounts
      type: object
      required:
        - peer_id
        - merged
        - accounts
      title: IngestLinkResult
      description: The kept person and every account that now maps to it.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: What went wrong
      type: object
      required:
        - detail
      title: ErrorResponse
      description: >-
        The body returned for every raised HonchoException.


        `HTTPValidationError` is FastAPI's own 422 shape, whose `detail` is an
        array

        of per-field errors. Honcho's handler returns a single message string

        instead (see `honcho_exception_handler` in `src/main.py`), so error
        codes

        raised from application code document this schema rather than that one.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IngestAccount:
      properties:
        source:
          type: string
          title: Source
        source_instance:
          type: string
          title: Source Instance
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: The account's ID in the source, when it has one
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
          description: The newest name the source gave for the account
      type: object
      required:
        - source
        - source_instance
      title: IngestAccount
      description: One source account mapped to a peer.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.