> ## 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.

# Ingest

> Ingest source records as messages.

Honcho maps each record to a session and peers from its source context and
deduplicates it on its source identity (`source_id`, or a hash of its
content), so resending a batch is always safe. The response has one outcome
per record, in request order: `created`, `duplicate`, or `rejected` with a
reason. The workspace must be an auto workspace (created with `auto: true`).
Only workspace and admin keys may ingest: one batch can create sessions and
peers anywhere in the workspace.

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
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:
    post:
      tags:
        - ingest
      summary: Ingest
      description: >-
        Ingest source records as messages.


        Honcho maps each record to a session and peers from its source context
        and

        deduplicates it on its source identity (`source_id`, or a hash of its

        content), so resending a batch is always safe. The response has one
        outcome

        per record, in request order: `created`, `duplicate`, or `rejected` with
        a

        reason. The workspace must be an auto workspace (created with `auto:
        true`).

        Only workspace and admin keys may ingest: one batch can create sessions
        and

        peers anywhere in the workspace.


        Experimental: ingest may change or stop working without notice.
      operationId: ingest_v3_workspaces__workspace_id__ingest_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/IngestBatch'
              description: The records to ingest
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '404':
          description: Workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The workspace isn't an auto workspace
          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 was written. Resending the
            same batch is safe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    IngestBatch:
      properties:
        derive:
          type: string
          enum:
            - now
            - later
          title: Derive
          description: >-
            `later` stores the records without queuing derivation; POST
            /ingest/derive queues them
          default: now
        records:
          items:
            $ref: '#/components/schemas/IngestRecordCreate'
          type: array
          maxItems: 100
          minItems: 1
          title: Records
      type: object
      required:
        - records
      title: IngestBatch
      description: A batch of source records for one workspace.
    IngestResponse:
      properties:
        records:
          items:
            $ref: '#/components/schemas/IngestRecordResult'
          type: array
          title: Records
        receipt:
          anyOf:
            - type: string
            - type: 'null'
          title: Receipt
          description: Reserved for a consistency token
      type: object
      required:
        - records
      title: IngestResponse
      description: One outcome per record, in request order.
    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
    IngestRecordCreate:
      properties:
        source:
          type: string
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
          title: Source
          description: The source type, e.g. `discord`
        source_instance:
          type: string
          maxLength: 128
          pattern: ^[a-zA-Z0-9_-]+$
          title: Source Instance
          description: The server, team or account inside the source
        source_id:
          anyOf:
            - type: string
              maxLength: 512
              minLength: 1
            - type: 'null'
          title: Source Id
          description: >-
            The record's ID in that instance. Without it, the record is
            identified by a hash of its content, so only identical content
            dedups; sources whose records can change must send it.
        revised_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Revised At
          description: When the source last changed this record
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The source's timestamp
        container:
          anyOf:
            - $ref: '#/components/schemas/IngestContainer'
            - type: 'null'
          description: Where the record lives; omit for a standalone record
        author:
          anyOf:
            - $ref: '#/components/schemas/IngestParticipant'
            - type: 'null'
          description: Who wrote it; omit when there is no single author
        participants:
          items:
            $ref: '#/components/schemas/IngestParticipant'
          type: array
          maxItems: 100
          title: Participants
        content:
          type: string
          maxLength: 25000
          title: Content
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        configuration:
          anyOf:
            - $ref: '#/components/schemas/MessageConfiguration'
            - type: 'null'
        session_id:
          anyOf:
            - type: string
              maxLength: 512
              minLength: 1
            - type: 'null'
          title: Session Id
          description: An explicit session, used instead of mapping the container
        peer_id:
          anyOf:
            - type: string
              maxLength: 512
              minLength: 1
            - type: 'null'
          title: Peer Id
          description: An explicit author peer, used instead of mapping the author
      type: object
      required:
        - source
        - source_instance
        - created_at
        - content
      title: IngestRecordCreate
      description: One source record to ingest.
    IngestRecordResult:
      properties:
        index:
          type: integer
          title: Index
          description: The record's position in the request
        outcome:
          type: string
          enum:
            - created
            - duplicate
            - rejected
          title: Outcome
        reason:
          anyOf:
            - type: string
              enum:
                - stale_revision
                - edit_not_supported
                - content_conflict
                - session_inactive
                - observers_limit
                - name_conflict
            - type: 'null'
          title: Reason
          description: Why a record was rejected
        record_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Record Id
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
        peer_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Peer Id
        derivation:
          anyOf:
            - type: string
              enum:
                - pending
                - queued
                - deferred
            - type: 'null'
          title: Derivation
      type: object
      required:
        - index
        - outcome
      title: IngestRecordResult
      description: What happened to one record of the batch.
    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
    IngestContainer:
      properties:
        id:
          type: string
          maxLength: 512
          minLength: 1
          title: Id
          description: The container's ID in the source
        name:
          anyOf:
            - type: string
              maxLength: 512
              minLength: 1
            - type: 'null'
          title: Name
          description: The container's display name
        parent_id:
          anyOf:
            - type: string
              maxLength: 512
              minLength: 1
            - type: 'null'
          title: Parent Id
          description: The parent container's ID, e.g. a thread's channel
      type: object
      required:
        - id
      title: IngestContainer
      description: 'Where a record lives in its source: a channel, a thread, a repository.'
    IngestParticipant:
      properties:
        id:
          anyOf:
            - type: string
              maxLength: 512
              minLength: 1
            - type: 'null'
          title: Id
          description: The person's ID in the source, if it has one
        name:
          type: string
          maxLength: 512
          minLength: 1
          title: Name
          description: The person's display name
        bot:
          type: boolean
          title: Bot
          description: >-
            The source marks this account as a bot or an integration. Ingest
            creates its peer with `observe_me` off, so nothing is derived about
            it; its messages are still stored and read as context.
          default: false
      type: object
      required:
        - name
      title: IngestParticipant
      description: A person on a record. The `id` is what connects them across records.
    MessageConfiguration:
      properties:
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ReasoningConfiguration'
            - type: 'null'
          description: Configuration for reasoning functionality.
      type: object
      title: MessageConfiguration
      description: >-
        The set of options that can be in a message DB-level configuration
        dictionary.


        All fields are optional. Message-level configuration overrides all other
        configurations.
    ReasoningConfiguration:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
          description: Whether to enable reasoning functionality.
        custom_instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Instructions
          description: >-
            Custom instructions for the deriver. Overrides the top-level
            custom_instructions at the same level. Set to an empty string to
            explicitly use none.
      type: object
      title: ReasoningConfiguration
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

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