inite-ai Documents API

openapi: 3.2.0
info:
  description: 'Generated from the zod wire contracts (`pnpm openapi:build` — scripts/build-openapi.ts); do not edit by hand. Excluded on purpose: the operator/ops surface (jobs, leases, policy, stats, maintenance, GDPR cascades), which is indexed in docs/api.md, and the MCP transport `ALL /mcp/{companyId}`, which is JSON-RPC over Streamable HTTP rather than REST — MCP clients discover it through `tools/list` (docs/mcp.md). Scopes are plain bearer-key grants, not OAuth flows — each operation states its required scope.'
  license:
    identifier: AGPL-3.0-or-later
    name: AGPL-3.0-or-later
  summary: 'The community-facing platform surface: the memory core (fact ingest, search, multi-hop, synthesize, entity and fact reads), the Domain Pack registry and tenant pack admin, the document pipeline, the external-indexer work protocol, the raw-substrate driver, the evidence substrate, and source reputation reads.'
  title: INITE Brain — Platform Documents API
  version: 2.6.0
servers:
- description: Hosted instance (placeholder — self-hosted deployments serve the same paths on their own origin).
  url: https://brain.inite.ai
security:
- bearerAuth: []
tags:
- description: 'The document pipeline: Source → Indexer → Candidates → Brain. Dark behind DOCUMENT_INGEST_ENABLED (default off).'
  name: Documents
paths:
  /v1/documents/{id}:
    get:
      description: 'Part of the document pipeline — answers `503 feature_disabled` until `DOCUMENT_INGEST_ENABLED=1`. Source: src/documents/documents.controller.ts.


        Required scope: `brain:read`.'
      operationId: getDocument
      parameters:
      - description: The document id.
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Pass `1` to include the stored chunks. The raw text can carry any PII, so this additionally requires the `brain:read_pii` scope (403 otherwise).
        in: query
        name: includeText
        required: false
        schema:
          enum:
          - '1'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
          description: The document.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/FeatureDisabled'
      summary: Read a document header and its indexer runs
      tags:
      - Documents
  /v1/documents/{id}/candidates:
    get:
      description: 'Every extraction candidate staged against the document, over all runs. `object`/`clause` of fact candidates whose predicate requires a scope the caller lacks are redacted; the row stays visible for the audit trail. Part of the document pipeline — answers `503 feature_disabled` until `DOCUMENT_INGEST_ENABLED=1`.


        Required scope: `brain:read`.'
      operationId: listDocumentCandidates
      parameters:
      - description: The document id.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentCandidatesResponse'
          description: The candidates.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/FeatureDisabled'
      summary: The document's staged candidates (audit view)
      tags:
      - Documents
  /v1/ingest/document:
    post:
      description: 'Source → Indexer → Candidates → Brain: stores + chunks the text, runs the selected indexers, commits grounded candidates as facts. `mode: "async"` fans out per-indexer queue jobs instead (requires DOCUMENT_MULTI_INDEXER_ENABLED). Throttled to 10 requests/min per credential. Part of the document pipeline — answers `503 feature_disabled` until `DOCUMENT_INGEST_ENABLED=1`. Source: src/documents/documents-ingest.controller.ts.


        Required scope: `brain:write`.'
      operationId: ingestDocument
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestDocumentRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/IngestDocumentSyncResponse'
                - $ref: '#/components/schemas/IngestDocumentAsyncResponse'
          description: Ingest outcome — shape follows the requested `mode`.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/FeatureDisabled'
      summary: Ingest a normalized document
      tags:
      - Documents
components:
  responses:
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Per-credential throttle exceeded.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The key lacks the required scope.
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or unknown bearer key.
    FeatureDisabled:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FeatureDisabledResponse'
      description: The document pipeline is dark (DOCUMENT_INGEST_ENABLED off).
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: No such resource in this tenant.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Validation failed.
  schemas:
    Candidate:
      additionalProperties: false
      properties:
        chunkSeq:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        commitRef:
          type: string
        confidence:
          type: number
        id:
          type: string
        kind:
          enum:
          - entity
          - fact
          - relation
          - scene
          - state_delta
          type: string
        payload:
          additionalProperties: {}
          description: 'Extraction payload. `object`/`clause` of scope-gated fact candidates are redacted for callers without the required predicate scope. scene/state_delta payloads (0110) are default-deny: content fields open only under brain:read_pii; other callers see structural fields plus `redacted: true`.'
          propertyNames:
            type: string
          type: object
        runId:
          type: string
        status:
          type: string
        statusReason:
          type: string
      required:
      - id
      - runId
      - chunkSeq
      - kind
      - confidence
      - status
      - payload
      type: object
    ErrorResponse:
      description: Standard NestJS error envelope.
      properties:
        error:
          type: string
        message:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
        statusCode:
          type: integer
      required:
      - statusCode
      - message
      type: object
    FeatureDisabledResponse:
      description: Answered by every document-pipeline route while DOCUMENT_INGEST_ENABLED is off.
      properties:
        error:
          const: feature_disabled
          type: string
        message:
          type: string
      required:
      - error
      - message
      type: object
    DocumentCandidatesResponse:
      additionalProperties: false
      properties:
        candidates:
          items:
            $ref: '#/components/schemas/Candidate'
          type: array
        documentId:
          type: string
      required:
      - documentId
      - candidates
      type: object
    IngestDocumentSyncResponse:
      additionalProperties: false
      properties:
        chunkCount:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        committed:
          additionalProperties: false
          properties:
            edgeIds:
              items:
                type: string
              type: array
            entityIds:
              items:
                type: string
              type: array
            factIds:
              items:
                type: string
              type: array
          required:
          - entityIds
          - factIds
          - edgeIds
          type: object
        counts:
          $ref: '#/components/schemas/CommitCounts'
        deduplicated:
          type: boolean
        documentId:
          type: string
        mode:
          const: sync
          type: string
        runs:
          items:
            additionalProperties: false
            properties:
              packId:
                type: string
              runId:
                type: string
              status:
                type: string
            required:
            - runId
            - packId
            - status
            type: object
          type: array
      required:
      - documentId
      - deduplicated
      - chunkCount
      - mode
      - runs
      - committed
      - counts
      type: object
    CommitCounts:
      additionalProperties: false
      properties:
        committed:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        merged:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        pending:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        rejected:
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
      - pending
      - committed
      - merged
      - rejected
      type: object
    IngestDocumentRequest:
      additionalProperties: false
      properties:
        contextRef:
          $ref: '#/components/schemas/DocumentContextRef'
        indexers:
          anyOf:
          - const: general
            type: string
          - const: auto
            type: string
          - items:
              type: string
            type: array
          description: '''general'' (union pass), ''auto'' (router-selected), or explicit pack ids.'
        kind:
          description: Container kind the connector normalized from (pdf/markdown/email/…). Open string — provenance metadata only.
          maxLength: 64
          type: string
        meta:
          additionalProperties: {}
          description: Operator-supplied metadata, projected onto derived facts' source.meta.
          propertyNames:
            type: string
          type: object
        mode:
          description: '''async'' requires DOCUMENT_MULTI_INDEXER_ENABLED and storeContent.'
          enum:
          - sync
          - async
          type: string
        occurredAt:
          description: ISO 8601 — becomes the derived facts' validFrom.
          format: date-time
          type: string
        originUri:
          description: Pointer back to the raw container (URL, path, message id…).
          maxLength: 512
          type: string
        storeContent:
          description: Store the normalized chunks server-side. false keeps only contentHash + metadata (no re-index, no span re-validation).
          type: boolean
        text:
          description: Normalized document text (DOC_MAX_CHARS may lower the cap).
          maxLength: 512000
          type: string
        title:
          maxLength: 512
          type: string
        toolObservationRef:
          description: Provenance hop to the tool result this document derives from (tool_observation:<id>, migration 0111). Honored only under TOOL_OBSERVATIONS_ENABLED; folded into committed facts' source.evidence[].
          maxLength: 160
          type: string
        userId:
          description: 'Per-user memory scope (0128): stamps the stored document, every committed fact and any projected scenes with this end-user; dedupe is scope-local. M2M-asserted; a user-bound token pins it to its own user (mismatch = 403).'
          maxLength: 200
          type: string
      required:
      - kind
      - text
      - occurredAt
      - contextRef
      type: object
    DocumentResponse:
      additionalProperties: false
      properties:
        charLen:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        chunkCount:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        chunks:
          items:
            $ref: '#/components/schemas/DocumentChunk'
          type: array
        contentHash:
          type: string
        hasContent:
          type: boolean
        id:
          type: string
        kind:
          type: string
        meta:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        occurredAt:
          format: date-time
          type: string
        recorder:
          type: string
        runs:
          items:
            additionalProperties: false
            properties:
              packId:
                type: string
              packVersion:
                type: string
              runId:
                type: string
              status:
                type: string
            required:
            - runId
            - packId
            - packVersion
            - status
            type: object
          type: array
        status:
          type: string
        userId:
          description: Per-user memory scope (0128); absent = tenant-global.
          type: string
        vertical:
          type: string
      required:
      - id
      - kind
      - contentHash
      - charLen
      - chunkCount
      - hasContent
      - vertical
      - occurredAt
      - status
      - runs
      type: object
    DocumentContextRef:
      additionalProperties: false
      properties:
        recorder:
          type: string
        vertical:
          type: string
      required:
      - vertical
      type: object
    DocumentChunk:
      additionalProperties: false
      properties:
        charEnd:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        charStart:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        seq:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        text:
          type: string
      required:
      - seq
      - text
      - charStart
      - charEnd
      type: object
    IngestDocumentAsyncResponse:
      additionalProperties: false
      properties:
        chunkCount:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        deduplicated:
          type: boolean
        documentId:
          type: string
        mode:
          const: async
          type: string
        runs:
          items:
            additionalProperties: false
            properties:
              packId:
                type: string
              status:
                enum:
                - enqueued
                - already_processed
                - planned
                type: string
            required:
            - packId
            - status
            type: object
          type: array
      required:
      - documentId
      - deduplicated
      - chunkCount
      - mode
      - runs
      type: object
  securitySchemes:
    bearerAuth:
      description: 'API key (`Authorization: Bearer <key>`); its SHA-256 must be registered in BRAIN_API_KEYS. Keys carry scopes (`brain:read`, `brain:write`, `brain:admin`, `brain:read_pii`, `registry:publish`, `registry:curate`, `indexer:write`) — each operation states the scope it requires. Not an OAuth flow.'
      scheme: bearer
      type: http