inite-ai Facts 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 Facts 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: 'Fact-level reads: one fact by id and its grounding episodes — provenance-first memory ("show me why I remember this"). Flag: FACTS_API_ENABLED (off → 404); fact retraction stays flag-independent.'
  name: Facts
paths:
  /v1/facts/{id}:
    get:
      description: 'The fact itself — what is remembered, where it came from (vertical/recorder/conversation), its validity instant and user scope. Every visibility fence (tenant, user scope, row policy) answers 404 — existence never leaks. 404 until FACTS_API_ENABLED=1. Source: src/facts/facts.controller.ts.


        Required scope: `brain:read`.'
      operationId: getFact
      parameters:
      - description: Fact record id (`knowledge_fact:…`).
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactReadResponse'
          description: The fact.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Read one fact by id
      tags:
      - Facts
  /v1/facts/{id}/provenance:
    get:
      description: 'The verbatim source turns (`source.episodeIds`) the fact was derived or ingested from, chronological, text capped server-side. Callers without `brain:read_pii` never receive PII-classed episode text. Same 404 fences as GET /v1/facts/{id}. 404 until FACTS_API_ENABLED=1.


        Required scope: `brain:read`.'
      operationId: getFactProvenance
      parameters:
      - description: Fact record id (`knowledge_fact:…`).
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactProvenanceResponse'
          description: The grounding episodes.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Read the grounding episodes behind a fact
      tags:
      - Facts
  /v1/facts/{id}/retract:
    post:
      description: 'Marks the fact retracted and writes the audit trail. Two cascades follow: facts DERIVED from it are retracted too (`cascadedFactIds`), and facts this one had SUPERSEDED come back to active (`revivedFactIds`) unless they were separately retracted on their own merits. Deliberately NOT gated by FACTS_API_ENABLED — the read routes above are, but a tenant must always be able to remove a fact. `brain:write` is the floor; FactsService elevates the requirement to `brain:admin` for billing_event / human_declared / legal-source facts once it has read the row (403 from there, not from the guard). For erasure rather than retraction, see the GDPR cascade on the admin surface (docs/api.md).


        Required scope: `brain:write`.'
      operationId: retractFact
      parameters:
      - description: Fact record id (`knowledge_fact:…`).
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetractFactRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetractFactResponse'
          description: What the retraction changed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Retract a fact
      tags:
      - Facts
components:
  schemas:
    RetractFactRequest:
      additionalProperties: false
      properties:
        reason:
          type: string
        retractedBy:
          $ref: '#/components/schemas/RetractedBy'
      required:
      - reason
      - retractedBy
      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
    FactProvenanceResponse:
      additionalProperties: false
      properties:
        closure:
          additionalProperties: false
          properties:
            depth:
              type: number
            factCount:
              type: number
            filtered:
              type: boolean
            truncated:
              type: boolean
          required:
          - depth
          - factCount
          - truncated
          - filtered
          type: object
        derivedFacts:
          items:
            additionalProperties: false
            properties:
              depth:
                type: number
              factId:
                type: string
              predicate:
                type: string
              status:
                type: string
            required:
            - factId
            - predicate
            - depth
            - status
            type: object
          type: array
        episodes:
          items:
            $ref: '#/components/schemas/FactProvenanceEpisode'
          type: array
        factId:
          type: string
        supportEdges:
          items:
            additionalProperties: false
            properties:
              from:
                type: string
              kind:
                enum:
                - supported_by
                - contradicted_by
                - derived_from
                - reconstructed_from
                type: string
              to:
                type: string
            required:
            - kind
            - from
            - to
            type: object
          type: array
      required:
      - factId
      - episodes
      type: object
    FactProvenanceEpisode:
      additionalProperties: false
      properties:
        conversationId:
          type: string
        episodeId:
          type: string
        occurredAt:
          type: string
        relation:
          const: neighbour
          type: string
        span:
          additionalProperties: false
          properties:
            end:
              type: number
            exact:
              type: string
            start:
              type: number
          required:
          - start
          - end
          - exact
          type: object
        speaker:
          type: string
        text:
          type: string
        textTruncated:
          type: boolean
      required:
      - episodeId
      - occurredAt
      - text
      type: object
    RetractedBy:
      additionalProperties: {}
      properties:
        source:
          enum:
          - human
          - system
          type: string
        userId:
          type: string
      required:
      - source
      type: object
    FactReadResponse:
      additionalProperties: false
      properties:
        aspect:
          type: string
        confidence:
          type: number
        conversationId:
          type: string
        derivedVersion:
          type: string
        factId:
          type: string
        groundingStatus:
          enum:
          - grounded
          - ungrounded
          type: string
        kind:
          type: string
        recorder:
          type: string
        retracted:
          type: boolean
        statement:
          type: string
        userId:
          type: string
        validFrom:
          type: string
        vertical:
          type: string
      required:
      - factId
      - aspect
      - statement
      - confidence
      - validFrom
      - retracted
      type: object
    RetractFactResponse:
      additionalProperties: false
      properties:
        cascadedFactIds:
          items:
            type: string
          type: array
        factId:
          type: string
        retractedAt:
          type: string
        revivedFactIds:
          items:
            type: string
          type: array
      required:
      - factId
      - retractedAt
      - cascadedFactIds
      - revivedFactIds
      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.
    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.
  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