inite-ai Entities 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 Entities 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 entity read surface (scope `brain:read`): typeahead, profile, bitemporal timeline and typed connections. The GDPR cascade on the same controller is an operator action and lives on the admin surface (docs/api.md).'
  name: Entities
paths:
  /v1/entities/autocomplete:
    get:
      description: 'Word-start match over the edge-ngram `prefix` fulltext index, BM25-ranked via `search::score`. A query under 2 characters returns nothing (the tokenizer produces no grams). Live, tenant-global entities only — merged-away redirects and personal-scoped entities are excluded. Source: src/entities/entities.controller.ts.


        Required scope: `brain:read`.'
      operationId: autocompleteEntities
      parameters:
      - description: The prefix to complete (under 2 chars → empty result).
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: Page size, 1–25 (default 10).
        in: query
        name: limit
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityAutocompleteResponse'
          description: Ranked suggestions.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Entity-name typeahead
      tags:
      - Entities
  /v1/entities/{id}:
    get:
      description: 'The entity plus the facts currently held about it, filtered by the row policy (a fact whose predicate requires a scope the caller lacks never appears). `asOf` slices WORLD time (what was true at T); `recordedAt` slices TRANSACTION time (what the graph believed at T — a later retract or supersede is ignored). A merged entity answers with `mergedInto` set: treat it as a redirect.


        Required scope: `brain:read`.'
      operationId: getEntityProfile
      parameters:
      - description: Entity id — short (`cuid_abc`) or full (`knowledge_entity:cuid_abc`).
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: ISO-8601 world-time slice.
        in: query
        name: asOf
        required: false
        schema:
          type: string
      - description: ISO-8601 transaction-time slice.
        in: query
        name: recordedAt
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityProfileResponse'
          description: The profile.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Entity profile and its active facts
      tags:
      - Entities
  /v1/entities/{id}/connections:
    get:
      description: 'The entity’s 1-hop neighbourhood over `knowledge_edge`, in both directions (`direction` says which). `kind` filters to one edge type; `asOf` restricts to edges live at that instant. `neighbour` is absent when the far end could not be projected. Edges carry the per-user scope of the turn that wrote them (migration 0153): without `userId` the read is tenant-global only; with one it adds that user’s own edges and neighbours. Honoured while READ_SURFACE_USER_SCOPE is on; a user-bound token is pinned to its own end user, and a mismatch is 403.


        Required scope: `brain:read`.'
      operationId: getEntityConnections
      parameters:
      - description: Entity id — short or fully-qualified.
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Only edges of this kind.
        in: query
        name: kind
        required: false
        schema:
          type: string
      - description: ISO-8601 instant the edge must be live at.
        in: query
        name: asOf
        required: false
        schema:
          type: string
      - description: Per-user scope (READ_SURFACE_USER_SCOPE only).
        in: query
        name: userId
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityConnectionsResponse'
          description: The typed edges.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Typed edges and direct neighbours
      tags:
      - Entities
  /v1/entities/{id}/timeline:
    get:
      description: '`fact.recorded` / `fact.retracted` events on the TRANSACTION-time axis — when the graph learned and unlearned things, not when they were true; each recorded event also carries `validFrom`, the valid-time instant, for readers that want the world’s order. `since` / `until` page the window; `recordedAt` cuts to events known by T. `userId` is honoured only while READ_SURFACE_USER_SCOPE is on (this surface predates migration 0055 and otherwise pins `userId IS NONE`); a user-bound token is pinned to its own end user, and a mismatch is 403.


        Required scope: `brain:read`.'
      operationId: getEntityTimeline
      parameters:
      - description: Entity id — short or fully-qualified.
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: ISO-8601 lower bound on recordedAt.
        in: query
        name: since
        required: false
        schema:
          type: string
      - description: ISO-8601 upper bound on recordedAt.
        in: query
        name: until
        required: false
        schema:
          type: string
      - description: Only events known by this instant.
        in: query
        name: recordedAt
        required: false
        schema:
          type: string
      - description: Per-user scope (READ_SURFACE_USER_SCOPE only).
        in: query
        name: userId
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityTimelineResponse'
          description: The event sweep.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Bitemporal sweep over an entity’s memory
      tags:
      - Entities
components:
  schemas:
    EntityProfileResponse:
      additionalProperties: false
      properties:
        canonicalName:
          type: string
        entityId:
          type: string
        externalRefs:
          additionalProperties:
            type: string
          propertyNames:
            type: string
          type: object
        facts:
          items:
            $ref: '#/components/schemas/EntityProfileFact'
          type: array
        mergedAt:
          type: string
        mergedInto:
          type: string
        type:
          type: string
      required:
      - entityId
      - type
      - canonicalName
      - externalRefs
      - facts
      type: object
    EntityProfileFact:
      additionalProperties: false
      properties:
        confidence:
          type: number
        expectedUntil:
          type: string
        factId:
          type: string
        object:
          type: string
        predicate:
          type: string
        status:
          type: string
        validFrom:
          type: string
        validUntil:
          type: string
      required:
      - factId
      - predicate
      - object
      - confidence
      - validFrom
      - status
      type: object
    TimelineRetractedEvent:
      additionalProperties: false
      properties:
        at:
          type: string
        factId:
          type: string
        reason: {}
        retractedBy: {}
        supersededBy:
          type: string
        type:
          const: fact.retracted
          type: string
      required:
      - type
      - at
      - factId
      - retractedBy
      - reason
      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
    EntityConnectionsResponse:
      additionalProperties: false
      properties:
        edges:
          items:
            $ref: '#/components/schemas/ConnectionEdge'
          type: array
        entityId:
          type: string
      required:
      - entityId
      - edges
      type: object
    ConnectionNeighbour:
      additionalProperties: false
      properties:
        canonicalName:
          type: string
        id:
          type: string
        type:
          type: string
      required:
      - id
      - type
      - canonicalName
      type: object
    ConnectionEdge:
      additionalProperties: false
      properties:
        createdAt:
          type: string
        direction:
          enum:
          - outbound
          - inbound
          type: string
        edgeId:
          type: string
        from:
          type: string
        kind:
          type: string
        neighbour:
          $ref: '#/components/schemas/ConnectionNeighbour'
        source: {}
        to:
          type: string
        weight:
          type: number
      required:
      - edgeId
      - from
      - to
      - kind
      - weight
      - source
      - createdAt
      - direction
      type: object
    TimelineRecordedEvent:
      additionalProperties: false
      properties:
        at:
          type: string
        confidence:
          type: number
        factId:
          type: string
        object:
          type: string
        predicate:
          type: string
        source: {}
        type:
          const: fact.recorded
          type: string
        validFrom:
          type: string
      required:
      - type
      - at
      - validFrom
      - factId
      - predicate
      - object
      - source
      - confidence
      type: object
    EntityAutocompleteResponse:
      additionalProperties: false
      properties:
        suggestions:
          items:
            $ref: '#/components/schemas/EntityAutocompleteSuggestion'
          type: array
      required:
      - suggestions
      type: object
    EntityTimelineResponse:
      additionalProperties: false
      properties:
        entityId:
          type: string
        events:
          items:
            anyOf:
            - $ref: '#/components/schemas/TimelineRecordedEvent'
            - $ref: '#/components/schemas/TimelineRetractedEvent'
          type: array
      required:
      - entityId
      - events
      type: object
    EntityAutocompleteSuggestion:
      additionalProperties: false
      properties:
        canonicalName:
          type: string
        entityId:
          type: string
        score:
          type: number
        type:
          type: string
      required:
      - entityId
      - canonicalName
      - type
      - score
      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