inite-ai Sources 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 Sources 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: 'Read-only trust inputs (scope `brain:read`): declared source identity ⋈ learned reputation. Public projection — operator annotations (owner/note) stay on the admin surface.'
  name: Sources
paths:
  /v1/sources:
    get:
      description: 'Catalogue of everything brain knows ABOUT its fact sources: the operator-declared identity (type, authLevel) joined with the learned agreement rates, one row per sourceKey. Public projection — operator annotations (owner/note) are served only on the brain:admin surface. `domain` additionally captures that domain''s learned rate into `domainTrust` and makes `minSamples` judge it (falling back to the global row). Source: src/sources/public-sources.controller.ts.


        Required scope: `brain:read`.'
      operationId: listSources
      parameters:
      - description: Capture this domain’s learned rate per source (`domainTrust`).
        in: query
        name: domain
        required: false
        schema:
          type: string
      - description: Only sources declared with this type.
        in: query
        name: type
        required: false
        schema:
          enum:
          - human
          - website
          - document
          - api
          - agent
          - sensor
          - system
          type: string
      - description: Only sources whose learned rate rests on at least this many samples (domain-scoped row when `domain` is given, global row otherwise).
        in: query
        name: minSamples
        required: false
        schema:
          type: integer
      - description: Page size (default 50, max 200).
        in: query
        name: limit
        required: false
        schema:
          type: integer
      - description: Page offset.
        in: query
        name: offset
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSourcesListResponse'
          description: The reputation catalogue page.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: List source reputations (trust inputs)
      tags:
      - Sources
  /v1/sources/{sourceKey}:
    get:
      description: 'Declared type/authLevel, every learned scope (global first, then domains alphabetically), and the reputation-over-time trail (newest first, capped at 50 rows). Public projection — owner/note are excluded. Same data the `get_source_reputation` MCP tool serves.


        Required scope: `brain:read`.'
      operationId: getSourceReputation
      parameters:
      - description: Source key, `vertical:recorder` (e.g. `rent:tenant_bot`).
        in: path
        name: sourceKey
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSourceDetailResponse'
          description: The source reputation detail.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: One source’s declared identity, trust scopes, and history
      tags:
      - Sources
components:
  schemas:
    SourceHistoryRow:
      additionalProperties: false
      properties:
        agreementRate:
          type: number
        domain:
          type:
          - string
          - 'null'
        recordedAt:
          type: string
        sampleCount:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
      required:
      - domain
      - agreementRate
      - sampleCount
      - recordedAt
      type: object
    PublicSourcesListResponse:
      additionalProperties: false
      properties:
        limit:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        offset:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        sources:
          items:
            $ref: '#/components/schemas/PublicSourceSummary'
          type: array
        total:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
      required:
      - sources
      - total
      - limit
      - offset
      type: object
    PublicDeclaredSource:
      additionalProperties: false
      properties:
        authLevel:
          maximum: 1
          minimum: 0
          type: number
        type:
          enum:
          - human
          - website
          - document
          - api
          - agent
          - sensor
          - system
          type: string
      required:
      - type
      - authLevel
      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
    TrustScopeRow:
      additionalProperties: false
      properties:
        agreementRate:
          type: number
        domain:
          type:
          - string
          - 'null'
        lastSeenAt:
          type:
          - string
          - 'null'
        lossCount:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        sampleCount:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        winCount:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
      required:
      - domain
      - agreementRate
      - sampleCount
      - winCount
      - lossCount
      - lastSeenAt
      type: object
    PublicSourceSummary:
      additionalProperties: false
      properties:
        declared:
          anyOf:
          - $ref: '#/components/schemas/PublicDeclaredSource'
          - type: 'null'
        domainTrust:
          anyOf:
          - $ref: '#/components/schemas/TrustScopeRow'
          - type: 'null'
        globalTrust:
          anyOf:
          - $ref: '#/components/schemas/TrustScopeRow'
          - type: 'null'
        scopedDomains:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        sourceKey:
          type: string
      required:
      - sourceKey
      - declared
      - globalTrust
      - scopedDomains
      type: object
    PublicSourceDetailResponse:
      additionalProperties: false
      properties:
        declared:
          anyOf:
          - $ref: '#/components/schemas/PublicDeclaredSource'
          - type: 'null'
        history:
          items:
            $ref: '#/components/schemas/SourceHistoryRow'
          type: array
        sourceKey:
          type: string
        trust:
          items:
            $ref: '#/components/schemas/TrustScopeRow'
          type: array
      required:
      - sourceKey
      - declared
      - trust
      - history
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or unknown bearer key.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: The key lacks the required scope.
    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