inite-ai Domain Packs 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 Domain Packs 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: 'Tenant-level pack management: install, list, eval, uninstall (scope `brain:admin`).'
  name: Domain Packs
paths:
  /v1/admin/packs:
    get:
      description: 'Builtin packs are globally available and cannot be installed or uninstalled here. Source: src/admin/admin-packs.controller.ts.


        Required scope: `brain:admin`.'
      operationId: listDomainPacks
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PacksListResponse'
          description: Available and installed packs.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: List available + installed packs for this tenant
      tags:
      - Domain Packs
    post:
      description: 'Validates and installs a community / custom manifest, seeding its predicates. `expectedChecksum` pins the exact content.


        Required scope: `brain:admin`.'
      operationId: installDomainPack
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallPackRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallPackResponse'
          description: Installed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Install a pack manifest into this tenant
      tags:
      - Domain Packs
  /v1/admin/packs/from-registry:
    post:
      description: 'Resolves the manifest (latest non-yanked, or a pinned version) and installs it with the registry checksum pinned — the installed content is exactly what the registry served. A PAID pack without an active `domain_pack:` entitlement answers 402 with a self-describing hint (the checkout route to call, then retry); while the billing service is unreachable, paid installs fail CLOSED with 503.


        Required scope: `brain:admin`.'
      operationId: installDomainPackFromRegistry
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallFromRegistryRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallPackResponse'
          description: Installed.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredHint'
          description: Paid pack, no entitlement — purchase via the checkout route in the hint, then retry.
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/BillingUnavailable'
      summary: Install a pack from the global registry
      tags:
      - Domain Packs
  /v1/admin/packs/{packId}:
    delete:
      description: 'Deprecates the pack''s predicates; facts extracted with them survive.


        Required scope: `brain:admin`.'
      operationId: uninstallDomainPack
      parameters:
      - description: The installed pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UninstallPackResponse'
          description: Uninstalled.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Uninstall a pack from this tenant
      tags:
      - Domain Packs
  /v1/admin/packs/{packId}/eval:
    post:
      description: 'Scores whether extraction (with the pack''s predicates + extractionProfile active) still meets the pack’s own expectations. Runs up to MAX_EVAL_FIXTURES live LLM calls — throttled to 3 requests/min per credential.


        Required scope: `brain:admin`.'
      operationId: evalDomainPack
      parameters:
      - description: The installed pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      - description: '''union'' (default) scores the shared union prompt; ''dedicated'' runs the pack-scoped dedicated prompt instead.'
        in: query
        name: mode
        required: false
        schema:
          enum:
          - union
          - dedicated
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackEvalReport'
          description: The eval report.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Run a pack's eval fixtures against the live extractor
      tags:
      - Domain Packs
components:
  schemas:
    InstallPackRequest:
      additionalProperties: false
      properties:
        acceptMcpTools:
          type: boolean
        acceptModalities:
          type: boolean
        acceptSources:
          type: boolean
        expectedChecksum:
          type: string
        manifest:
          $ref: '#/components/schemas/DomainPackManifest'
      required:
      - manifest
      type: object
    DisplayPrice:
      additionalProperties: false
      properties:
        amount:
          description: Minor units (e.g. cents).
          exclusiveMinimum: 0
          maximum: 9007199254740991
          type: integer
        currency:
          description: 3-letter ISO 4217 currency code.
          pattern: ^[A-Za-z]{3}$
          type: string
      required:
      - amount
      - currency
      type: object
    PacksListResponse:
      additionalProperties: false
      properties:
        available:
          items:
            $ref: '#/components/schemas/AvailablePack'
          type: array
        installed:
          items:
            $ref: '#/components/schemas/InstalledPack'
          type: array
      required:
      - available
      - installed
      type: object
    PaymentRequiredHint:
      additionalProperties: false
      properties:
        checkout:
          additionalProperties: false
          properties:
            method:
              const: POST
              type: string
            path:
              type: string
          required:
          - method
          - path
          type: object
        displayPrice:
          $ref: '#/components/schemas/DisplayPrice'
        error:
          const: Payment Required
          type: string
        message:
          type: string
        packId:
          type: string
        priceCode:
          type: string
        statusCode:
          const: 402
          type: number
      required:
      - statusCode
      - error
      - message
      - packId
      - checkout
      type: object
    DomainPackManifest:
      additionalProperties: {}
      properties:
        description:
          type: string
        evalFixtures:
          items:
            additionalProperties: {}
            propertyNames:
              type: string
            type: object
          type: array
        extractionProfile:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        id:
          description: snake_case pack id, no `__`.
          type: string
        indexer:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        mcpTools:
          items:
            additionalProperties: {}
            propertyNames:
              type: string
            type: object
          type: array
        memoryModel:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        predicates:
          items:
            additionalProperties: {}
            propertyNames:
              type: string
            type: object
          type: array
        publisher:
          type: string
        seedDocuments:
          items:
            additionalProperties: {}
            propertyNames:
              type: string
            type: object
          type: array
        signature:
          description: ed25519 signature (base64) over the canonical manifest sans this field.
          type: string
        version:
          description: semver MAJOR.MINOR.PATCH.
          type: string
      required:
      - id
      - version
      - description
      - predicates
      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
    AvailablePack:
      additionalProperties: false
      properties:
        builtin:
          type: boolean
        description:
          type: string
        id:
          type: string
        predicateCount:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        version:
          type: string
      required:
      - id
      - version
      - description
      - predicateCount
      - builtin
      type: object
    UninstallPackResponse:
      additionalProperties: false
      properties:
        packId:
          type: string
        predicatesDeprecated:
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
      - packId
      - predicatesDeprecated
      type: object
    InstallPackResponse:
      additionalProperties: false
      properties:
        checksum:
          type: string
        packId:
          type: string
        predicatesSeeded:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        seedDocuments:
          additionalProperties: false
          description: Present iff the manifest ships seedDocuments — whether their document-pipeline ingest was enqueued. Install never fails because of seeds.
          properties:
            count:
              maximum: 9007199254740991
              minimum: 0
              type: integer
            status:
              enum:
              - enqueued
              - enqueue_failed
              - skipped_flag_disabled
              - skipped_ingest_disabled
              - skipped_no_queue
              type: string
          required:
          - count
          - status
          type: object
        version:
          type: string
        webhookSecret:
          type: string
      required:
      - packId
      - version
      - predicatesSeeded
      - checksum
      type: object
    InstallFromRegistryRequest:
      additionalProperties: false
      properties:
        acceptMcpTools:
          type: boolean
        acceptModalities:
          type: boolean
        acceptSources:
          type: boolean
        packId:
          type: string
        version:
          type: string
      required:
      - packId
      type: object
    InstalledPack:
      additionalProperties: false
      properties:
        checksum:
          type:
          - string
          - 'null'
        installedAt:
          type: string
        memoryModel:
          anyOf:
          - additionalProperties: {}
            propertyNames:
              type: string
            type: object
          - type: 'null'
        packId:
          type: string
        predicateCount:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        version:
          type: string
      required:
      - packId
      - version
      - installedAt
      - predicateCount
      - checksum
      - memoryModel
      type: object
    PackEvalReport:
      additionalProperties: false
      properties:
        packId:
          type: string
        passed:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        results:
          items:
            $ref: '#/components/schemas/PackEvalFixtureResult'
          type: array
        total:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        version:
          type: string
      required:
      - packId
      - version
      - total
      - passed
      - results
      type: object
    PackEvalFixtureResult:
      additionalProperties: false
      properties:
        failures:
          description: Human-readable reasons the fixture failed (empty when passed).
          items:
            type: string
          type: array
        id:
          type: string
        passed:
          type: boolean
      required:
      - id
      - passed
      - failures
      type: object
  responses:
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Per-credential throttle exceeded.
    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.
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or unknown bearer key.
    BadGateway:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The billing service rejected the request.
    BillingUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The billing service is unreachable — paid-pack entitlements cannot be verified (fail-closed). Retry shortly.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The key lacks the required scope.
  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