inite-ai Ingest 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 Ingest 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: 'Writing memory: the declared-fact path (scope `brain:write`). Every write goes through bitemporal conflict resolution, so the response reports a decision, not an acknowledgement.'
  name: Ingest
paths:
  /v1/ingest/fact:
    post:
      description: 'The headline write. Resolves the entity, embeds the claim and runs bitemporal conflict resolution against the standing timeline: the response `outcome` says what the resolver decided (INSERTED / INSERTED_HISTORICAL / CORROBORATED / SUPERSEDED / COMPETING / REJECTED), never just "ok". `userId` stamps a per-user memory scope (migration 0055) — scope-local conflict resolution, invisible to every other user of the tenant and to requests that don''t assert one. `explain: true` adds the deterministic conflict narrative on a SUPERSEDED / COMPETING outcome. Source: src/ingest/ingest.controller.ts.


        Required scope: `brain:write`.'
      operationId: ingestFact
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestFactRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestFactResponse'
          description: The resolver's decision.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Record a declared structured fact
      tags:
      - Ingest
  /v1/ingest/mention:
    post:
      description: 'The simplest write, and the one to reach for when the caller has prose rather than a structured claim: a chat turn, a meeting note, an email body. The text is captured as an episode, an LLM extracts entities, facts and edges from it, and each extracted fact goes through the same bitemporal resolver as `POST /v1/ingest/fact` — so extraction is noisy by design and conflict resolution cleans up at read time. Only `text` is required: `contextRef` defaults to the `chat` vertical and `emittedAt` to the moment the request arrives. `userId` stamps the per-user memory scope on the episode and every extracted fact and edge. `skipped: true` means nothing new was recorded — `reason` says why: `empty` text, `no_entities` (the extractor found nothing worth recording), or `duplicate` (this user already sent this exact text; the document store keys on the content hash and a replay commits nothing new) — a normal outcome, not an error. Prefer `POST /v1/ingest/document` for anything long enough to need chunking. Source: src/ingest/ingest.controller.ts.


        Required scope: `brain:write`.'
      operationId: ingestMention
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestMentionRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestMentionResponse'
          description: What the extractor wrote.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Record free text and let brain extract the facts
      tags:
      - Ingest
components:
  schemas:
    SourceEvidence:
      additionalProperties: false
      properties:
        kind:
          enum:
          - event
          - message
          - conversation
          - url
          - document
          - commit
          - other
          type: string
        note:
          type: string
        ref:
          type: string
      required:
      - kind
      - ref
      type: object
    IngestMentionResponse:
      additionalProperties: false
      properties:
        episodeId:
          type: string
        extractedEdgeIds:
          items:
            type: string
          type: array
        extractedEntityIds:
          items:
            type: string
          type: array
        extractedFactIds:
          items:
            type: string
          type: array
        reason:
          type: string
        skipped:
          type: boolean
      required:
      - skipped
      - extractedEntityIds
      - extractedFactIds
      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
    ConflictExplanation:
      additionalProperties: {}
      propertyNames:
        type: string
      type: object
    IngestMentionRequest:
      additionalProperties: false
      properties:
        contextRef:
          $ref: '#/components/schemas/MentionContextRef'
        emittedAt:
          type: string
        knownEntities:
          items:
            $ref: '#/components/schemas/KnownEntity'
          type: array
        text:
          maxLength: 16000
          type: string
        timezone:
          maxLength: 64
          type: string
        userId:
          maxLength: 200
          type: string
      required:
      - text
      type: object
    MentionContextRef:
      additionalProperties: {}
      properties:
        conversationId:
          type: string
        eventId:
          type: string
        messageId:
          type: string
        recorder:
          type: string
        vertical:
          type: string
      required:
      - vertical
      type: object
    KnownEntity:
      additionalProperties: {}
      properties:
        id:
          type: string
        name:
          type: string
        role:
          type: string
        vertical:
          type: string
      required:
      - vertical
      - id
      type: object
    FactSource:
      additionalProperties: {}
      properties:
        conversationId:
          type: string
        episodeIds:
          items:
            type: string
          type: array
        eventId:
          type: string
        evidence:
          items:
            $ref: '#/components/schemas/SourceEvidence'
          type: array
        messageId:
          type: string
        recorder:
          type: string
        vertical:
          type: string
      required:
      - vertical
      type: object
    IngestFactResponse:
      additionalProperties: false
      properties:
        competingFactIds:
          items:
            type: string
          type: array
        conflictExplanation:
          $ref: '#/components/schemas/ConflictExplanation'
        corroboratedFactId:
          type: string
        factId:
          type:
          - string
          - 'null'
        outcome:
          enum:
          - INSERTED
          - INSERTED_HISTORICAL
          - CORROBORATED
          - SUPERSEDED
          - COMPETING
          - REJECTED
          type: string
        reason:
          type: string
        supersededByFactId:
          type: string
        supersededFactIds:
          items:
            type: string
          type: array
      required:
      - factId
      - outcome
      type: object
    IngestFactRequest:
      additionalProperties: false
      properties:
        confidence:
          maximum: 1
          minimum: 0
          type: number
        entityRef:
          $ref: '#/components/schemas/EntityRef'
        expectedUntil:
          type: string
        explain:
          type: boolean
        metadata:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        object:
          maxLength: 2000
          type: string
        predicate:
          maxLength: 256
          type: string
        source:
          $ref: '#/components/schemas/FactSource'
        userId:
          maxLength: 200
          type: string
        validFrom:
          type: string
        validUntil:
          type: string
      required:
      - entityRef
      - predicate
      - object
      - validFrom
      - source
      type: object
    EntityRef:
      additionalProperties: {}
      properties:
        entityId:
          type: string
        id:
          type: string
        vertical:
          type: string
      type: object
  responses:
    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.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Validation failed.
  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