inite-ai Marketplace 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 Marketplace 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: Featured curation (scope `registry:curate`), pack pricing + publisher profiles (scope `registry:publish`) and the paid-pack checkout (scope `brain:admin`). State is instance-local — never part of the signed manifest, never mirrored.
  name: Marketplace
paths:
  /v1/admin/registry/packs/{packId}/checkout:
    post:
      description: 'Creates a billing checkout session for the BUYING tenant (the caller''s company is the billing userId). Open `checkoutUrl`, pay, then retry POST /v1/admin/packs/from-registry — the 402 hint on that route points here. Answers 400 for a free pack or while the billing integration is disabled. An `idempotency-key` header is forwarded to billing so client retries collapse into one order. Throttled to 10 requests/min per credential.


        Required scope: `brain:admin`.'
      operationId: createRegistryPackCheckout
      parameters:
      - description: The paid pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
          description: The checkout session.
        '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'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/BillingUnavailable'
      summary: Start a hosted checkout for a paid pack
      tags:
      - Marketplace
  /v1/admin/registry/packs/{packId}/feature:
    post:
      description: 'Surfaces the pack in the featured section on top of the catalogue listing and /registry/ui. Instance-local; never mirrored.


        Required scope: `registry:curate`.'
      operationId: featureRegistryPack
      parameters:
      - description: The pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
          description: The curation state.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Feature a pack (hosting-operator curation)
      tags:
      - Marketplace
  /v1/admin/registry/packs/{packId}/pricing:
    delete:
      description: 'Clears the paid flag — installs stop requiring an entitlement. Billing products/prices are immutable and stay.


        Required scope: `registry:publish`.'
      operationId: clearRegistryPackPricing
      parameters:
      - description: The pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackPricingResponse'
          description: The pricing state.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Make a pack free again (publisher-owned)
      tags:
      - Marketplace
    put:
      description: 'Marks the pack paid: ensures the billing product exists (entitlement key `domain_pack:`), mints a fresh immutable price, and stores the priceCode + display price in the instance-local registry meta. Only the company that published the pack may price it. Answers 400 while the billing integration is disabled. Source: src/registry/marketplace-admin.controller.ts.


        Required scope: `registry:publish`.'
      operationId: setRegistryPackPricing
      parameters:
      - description: The pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPricingRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackPricingResponse'
          description: The pricing state.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Price a pack (publisher-owned)
      tags:
      - Marketplace
  /v1/admin/registry/packs/{packId}/unfeature:
    post:
      description: 'Reverses a feature.


        Required scope: `registry:curate`.'
      operationId: unfeatureRegistryPack
      parameters:
      - description: The pack id.
        in: path
        name: packId
        required: true
        schema:
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureResponse'
          description: The curation state.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Remove a pack from the featured section
      tags:
      - Marketplace
  /v1/admin/registry/publishers/{publisher}:
    put:
      description: 'Full-replace upsert. Writable ONLY by a company that has published at least one VERIFIED pack under the publisher id — the ed25519 signature validated against the hosting instance''s trust store is what ties a company to the publisher name (403 otherwise).


        Required scope: `registry:publish`.'
      operationId: upsertRegistryPublisherProfile
      parameters:
      - description: The publisher id (trust-store key id).
        in: path
        name: publisher
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPublisherProfileRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublisherProfile'
          description: The stored profile.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      summary: Write a publisher's public profile
      tags:
      - Marketplace
components:
  schemas:
    UpsertPublisherProfileRequest:
      additionalProperties: false
      properties:
        bio:
          maxLength: 2000
          type: string
        contactEmail:
          type: string
        displayName:
          maxLength: 120
          minLength: 1
          type: string
        url:
          type: string
      required:
      - displayName
      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
    CheckoutRequest:
      additionalProperties: false
      properties:
        errorUrl:
          type: string
        successUrl:
          type: string
      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
    CheckoutResponse:
      additionalProperties: false
      properties:
        checkoutUrl:
          description: Hosted billing checkout URL to open.
          type: string
        sessionId:
          type: string
      required:
      - sessionId
      - checkoutUrl
      type: object
    PublisherProfile:
      additionalProperties: false
      properties:
        bio:
          type: string
        contactEmail:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        displayName:
          type: string
        publisher:
          type: string
        updatedAt:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
      required:
      - publisher
      - displayName
      - url
      - bio
      - contactEmail
      - createdAt
      - updatedAt
      type: object
    SetPricingRequest:
      additionalProperties: false
      properties:
        amount:
          description: Minor units (e.g. cents).
          exclusiveMinimum: 0
          maximum: 9007199254740991
          type: integer
        currency:
          pattern: ^[A-Za-z]{3}$
          type: string
      required:
      - amount
      - currency
      type: object
    FeatureResponse:
      additionalProperties: false
      properties:
        featured:
          type: boolean
        packId:
          type: string
      required:
      - packId
      - featured
      type: object
    PackPricingResponse:
      additionalProperties: false
      properties:
        displayPrice:
          $ref: '#/components/schemas/DisplayPrice'
        packId:
          type: string
        paid:
          type: boolean
        priceCode:
          type: string
      required:
      - packId
      - paid
      type: object
  responses:
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Per-credential throttle exceeded.
    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.
    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.
    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