inite-ai Users 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 Users 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: 'Per-user surfaces: the rolling user profile assembled from user-scoped memory. Flag: USER_PROFILE_API_ENABLED (off → 404).'
  name: Users
paths:
  /v1/users/{userId}/profile:
    get:
      description: 'Query-time assembly of what the platform knows about a user: active user-scoped facts grouped by aspect (persona-first), plus `profileText` shaped for direct prompt injection. Deterministic — no model calls. A user-bound token may only fetch its own profile (mismatch 403); M2M tokens any. 404 until USER_PROFILE_API_ENABLED=1. Source: src/users/user-profile.controller.ts.


        Required scope: `brain:read`.'
      operationId: getUserProfile
      parameters:
      - description: The user whose profile to assemble.
        in: path
        name: userId
        required: true
        schema:
          type: string
      - description: Global fact budget (default 60, max 200).
        in: query
        name: maxFacts
        required: false
        schema:
          type: integer
      - description: Soft locale filter (facts in this language or unmarked).
        in: query
        name: lang
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileResponse'
          description: The assembled profile.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Rolling user profile (deterministic v1)
      tags:
      - Users
components:
  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.
  schemas:
    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
    UserProfileResponse:
      additionalProperties: false
      properties:
        factCount:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        generatedAt:
          type: string
        identity:
          additionalProperties: false
          properties:
            entityId:
              type:
              - string
              - 'null'
            name:
              type:
              - string
              - 'null'
          required:
          - entityId
          - name
          type: object
        profileText:
          type: string
        sections:
          items:
            $ref: '#/components/schemas/ProfileSection'
          type: array
        userId:
          type: string
      required:
      - userId
      - identity
      - generatedAt
      - factCount
      - sections
      - profileText
      type: object
    ProfileSection:
      additionalProperties: false
      properties:
        aspect:
          type: string
        facts:
          items:
            $ref: '#/components/schemas/ProfileFact'
          type: array
      required:
      - aspect
      - facts
      type: object
    ProfileFact:
      additionalProperties: false
      properties:
        confidence:
          type: number
        expectedUntil:
          type: string
        factId:
          type: string
        kind:
          type: string
        lastSeenAt:
          type: string
        statement:
          type: string
        validFrom:
          type: string
      required:
      - factId
      - statement
      - validFrom
      - confidence
      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