PT
QuickstartMCPRESTIntegrationsGuidesApp
API

REST (generated)

Every path in the engine OpenAPI, regenerated at docs build. Do not edit.

Source: https://valorbrain-api.valor.digital/openapi.json (live, generated from routes[]). Public base: https://valorbrain-api.valor.digital. Admin and ops routes are listed because they exist; a tenant token will 403 them.

232 operations across 20 tags.

Admin

POST /api/v1/admin/tenants

Create a tenant (admin only)

  • Auth: bearer
  • Body: object( name* (string), metadata (object( )) )
  • operationId: adminCreateTenant
post:
  operationId: adminCreateTenant
  summary: Create a tenant (admin only)
  tags:
  - Admin
  security:
  - adminSecret: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - name
          properties:
            name:
              type: string
            metadata:
              type: object
              additionalProperties: true
  responses:
    '200':
      description: Tenant created
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              tenant_id:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

POST /api/v1/admin/tenants/{tenantId}/users

Create a user in a tenant (admin only)

  • Auth: bearer
  • Params: tenantId*
  • Body: object( email* (string), name (string), role (string) )
  • operationId: adminCreateUser
post:
  operationId: adminCreateUser
  summary: Create a user in a tenant (admin only)
  tags:
  - Admin
  security:
  - adminSecret: []
  parameters:
  - name: tenantId
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - email
          properties:
            email:
              type: string
              format: email
            name:
              type: string
            role:
              type: string
  responses:
    '200':
      description: User created
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

DELETE /api/v1/admin/tenants/{tenantId}

Delete a tenant (admin only)

  • Auth: bearer
  • Params: tenantId*
  • operationId: adminDeleteTenant
delete:
  operationId: adminDeleteTenant
  summary: Delete a tenant (admin only)
  tags:
  - Admin
  security:
  - adminSecret: []
  parameters:
  - name: tenantId
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Tenant deleted
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

GET /api/v1/admin/errors

List error log (admin only)

  • Auth: bearer
  • Params: limit, unresolved_only
  • operationId: adminListErrors
get:
  operationId: adminListErrors
  summary: List error log (admin only)
  tags:
  - Admin
  security:
  - adminSecret: []
  parameters:
  - name: limit
    in: query
    schema:
      type: integer
      default: 50
  - name: unresolved_only
    in: query
    schema:
      type: boolean
      default: true
  responses:
    '200':
      description: Error list
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

POST /api/v1/admin/errors/{errorId}/resolve

Resolve an error (admin only)

  • Auth: bearer
  • Params: errorId*
  • operationId: adminResolveError
post:
  operationId: adminResolveError
  summary: Resolve an error (admin only)
  tags:
  - Admin
  security:
  - adminSecret: []
  parameters:
  - name: errorId
    in: path
    required: true
    schema:
      type: integer
  responses:
    '200':
      description: Error resolved
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

GET /api/v1/admin/test-error

Trigger a test error (admin only)

  • Auth: bearer
  • operationId: adminTestError
get:
  operationId: adminTestError
  summary: Trigger a test error (admin only)
  tags:
  - Admin
  security:
  - adminSecret: []
  responses:
    '200':
      description: Test error triggered
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

POST /admin/l0-l1/run

Trigger L0/L1 generation

  • Auth: bearer
  • operationId: l0l1Run
post:
  operationId: l0l1Run
  summary: Trigger L0/L1 generation
  tags:
  - Admin
  responses:
    '200':
      description: L0/L1 generation initiated
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean

Agents

POST /api/v1/agents/signup

Register a new agent (public) — Public endpoint — no auth required. Creates a shadow tenant and returns an API key.

  • Auth: none
  • Body: object( agent_name* (string), capabilities (array[string]), metadata (object( )) )
  • operationId: agentSignup
post:
  operationId: agentSignup
  summary: Register a new agent (public)
  description: 'Public endpoint — no auth required. Creates a shadow tenant and returns
    an API key.

    '
  tags:
  - Agents
  security: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - agent_name
          properties:
            agent_name:
              type: string
            capabilities:
              type: array
              items:
                type: string
            metadata:
              type: object
              additionalProperties: true
  responses:
    '200':
      description: Agent registered with API key
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              tenant_id:
                type: string
              api_key:
                type: string
    '400':
      $ref: '#/components/responses/BadRequest'

POST /api/v1/agents/identify

Identify an agent by API key

  • Auth: none
  • Body: object( key* (string) )
  • operationId: agentIdentify
post:
  operationId: agentIdentify
  summary: Identify an agent by API key
  tags:
  - Agents
  security: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - key
          properties:
            key:
              type: string
  responses:
    '200':
      description: Agent identity
      content:
        application/json:
          schema:
            type: object
            properties:
              agent_name:
                type: string
              tenant_id:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/agents/claim

Request ownership claim for an agent

  • Auth: none
  • Body: object( agent_name* (string), email* (string) )
  • operationId: agentClaim
post:
  operationId: agentClaim
  summary: Request ownership claim for an agent
  tags:
  - Agents
  security: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - agent_name
          - email
          properties:
            agent_name:
              type: string
            email:
              type: string
              format: email
  responses:
    '200':
      description: Claim request initiated
      content:
        application/json:
          schema:
            type: object
    '400':
      $ref: '#/components/responses/BadRequest'

POST /api/v1/agents/claim/verify

Verify an agent ownership claim

  • Auth: none
  • Body: object( token* (string) )
  • operationId: agentClaimVerify
post:
  operationId: agentClaimVerify
  summary: Verify an agent ownership claim
  tags:
  - Agents
  security: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - token
          properties:
            token:
              type: string
  responses:
    '200':
      description: Claim verified
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              api_key:
                type: string
    '400':
      $ref: '#/components/responses/BadRequest'

Ask

POST /ask

RAG chat with LLM answer and source citations — Retrieve relevant context, run through LLM reasoning, and return a grounded answer with source citations. Supports streaming (SSE).

  • Auth: bearer
  • Params: None
  • Body: object( q* (string), collection (string), stream (boolean), language (enum(pt-BR, en)), limit (integer) )
  • operationId: ask
post:
  operationId: ask
  summary: RAG chat with LLM answer and source citations
  description: 'Retrieve relevant context, run through LLM reasoning, and return a
    grounded answer with source citations. Supports streaming (SSE).

    '
  tags:
  - Ask
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - q
          properties:
            q:
              type: string
              description: User question
            collection:
              type: string
            stream:
              type: boolean
              default: false
              description: Enable SSE streaming
            language:
              type: string
              enum:
              - pt-BR
              - en
              default: pt-BR
            limit:
              type: integer
              default: 5
              description: Max source documents to retrieve
  responses:
    '200':
      description: 'RAG answer. When stream=false, returns JSON with answer and sources.
        When stream=true, returns text/event-stream.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              answer:
                type: string
              sources:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'
              trace_id:
                type: string
        text/event-stream:
          schema:
            type: string
            description: SSE stream of answer chunks
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/traces

List recent ask traces

  • Auth: bearer
  • Params: limit, offset
  • operationId: listTraces
get:
  operationId: listTraces
  summary: List recent ask traces
  tags:
  - Ask
  parameters:
  - name: limit
    in: query
    schema:
      type: integer
      default: 50
  - name: offset
    in: query
    schema:
      type: integer
      default: 0
  responses:
    '200':
      description: Trace log entries
      content:
        application/json:
          schema:
            type: object
            properties:
              traces:
                type: array
                items:
                  type: object
              count:
                type: integer

Billing

GET /api/v1/credits/balance

Get credit balance

  • Auth: bearer
  • Params: None
  • operationId: getCreditsBalance
get:
  operationId: getCreditsBalance
  summary: Get credit balance
  tags:
  - Billing
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Credit balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreditBalance'
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/credits/transactions

Get credit transaction history

  • Auth: bearer
  • Params: None, limit
  • operationId: getCreditsTransactions
get:
  operationId: getCreditsTransactions
  summary: Get credit transaction history
  tags:
  - Billing
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: limit
    in: query
    schema:
      type: integer
      default: 50
  responses:
    '200':
      description: Transaction list
      content:
        application/json:
          schema:
            type: object
            properties:
              transactions:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    amount:
                      type: number
                    action:
                      type: string
                    created_at:
                      type: string
                      format: date-time
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/credits/grant

Grant credits to tenant — Repeatable manual operator adjustment; the required reason is recorded in the credit ledger.

  • Auth: bearer
  • Params: None
  • Body: object( amount* (number), reason* (string), metadata (object( )) )
  • operationId: grantCredits
post:
  operationId: grantCredits
  summary: Grant credits to tenant
  description: Repeatable manual operator adjustment; the required reason is recorded
    in the credit ledger.
  tags:
  - Billing
  security:
  - moneyAdminAuth: []
  parameters:
  - $ref: '#/components/parameters/MoneyTenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - amount
          - reason
          properties:
            amount:
              type: number
              exclusiveMinimum: 0
            reason:
              type: string
              minLength: 1
            metadata:
              type: object
              additionalProperties: true
  responses:
    '200':
      description: Credits granted
      content:
        application/json:
          schema:
            type: object
            required:
            - ok
            - balance_after
            properties:
              ok:
                type: boolean
              balance_after:
                type: number
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

GET /api/v1/pricing/actions

List pricing actions

  • Auth: bearer
  • Params: None
  • operationId: listPricingActions
get:
  operationId: listPricingActions
  summary: List pricing actions
  tags:
  - Billing
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Pricing action list
      content:
        application/json:
          schema:
            type: object
            properties:
              actions:
                type: array
                items:
                  type: object
                  properties:
                    action:
                      type: string
                    cost:
                      type: number
                    currency:
                      type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/pricing/actions/{action}

Set pricing for an action

  • Auth: bearer
  • Params: None, action*
  • Body: object( cost* (number) )
  • operationId: setPricingAction
put:
  operationId: setPricingAction
  summary: Set pricing for an action
  tags:
  - Billing
  security:
  - moneyAdminAuth: []
  parameters:
  - $ref: '#/components/parameters/MoneyTenantIdHeader'
  - name: action
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - cost
          properties:
            cost:
              type: number
  responses:
    '200':
      description: Pricing updated
      content:
        application/json:
          schema:
            type: object
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

GET /api/v1/plans

List available subscription plans

  • Auth: bearer
  • operationId: listPlans
get:
  operationId: listPlans
  summary: List available subscription plans
  tags:
  - Billing
  responses:
    '200':
      description: Plan list
      content:
        application/json:
          schema:
            type: object
            properties:
              plans:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    credits:
                      type: number
                    price:
                      type: number

GET /api/v1/subscription

Get current subscription

  • Auth: bearer
  • Params: None
  • operationId: getSubscription
get:
  operationId: getSubscription
  summary: Get current subscription
  tags:
  - Billing
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Subscription details
      content:
        application/json:
          schema:
            type: object
            properties:
              plan_id:
                type: string
              status:
                type: string
              current_period_end:
                type: string
                format: date-time
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/subscription

Update subscription plan

  • Auth: bearer
  • Params: None
  • Body: object( plan_id (string) )
  • operationId: updateSubscription
put:
  operationId: updateSubscription
  summary: Update subscription plan
  tags:
  - Billing
  security:
  - moneyAdminAuth: []
  parameters:
  - $ref: '#/components/parameters/MoneyTenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            plan_id:
              type: string
  responses:
    '200':
      description: Subscription updated
      content:
        application/json:
          schema:
            type: object
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

POST /api/v1/subscription/grant

Grant legacy Stripe invoice credits idempotently — Compatibility endpoint for older Stripe contracts with monthly credits. Writes a credit_grant event with source stripe:invoice and source_id equal to invoice_id. It does not activate or change the subscription itself.

  • Auth: bearer
  • Params: None
  • Body: SubscriptionCreditGrantRequest
  • operationId: grantSubscriptionCredits
post:
  operationId: grantSubscriptionCredits
  summary: Grant legacy Stripe invoice credits idempotently
  description: 'Compatibility endpoint for older Stripe contracts with monthly credits.
    Writes a credit_grant event with source stripe:invoice and source_id equal to
    invoice_id. It does not activate or change the subscription itself.

    '
  tags:
  - Billing
  security:
  - moneyAdminAuth: []
  parameters:
  - $ref: '#/components/parameters/MoneyTenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SubscriptionCreditGrantRequest'
  responses:
    '200':
      description: Credits granted once, or an identical invoice replay skipped
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubscriptionCreditGrantResponse'
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'
    '404':
      $ref: '#/components/responses/NotFound'
    '409':
      $ref: '#/components/responses/BillingConflict'
    '422':
      $ref: '#/components/responses/BillingUnprocessable'

POST /api/v1/billing/events/apply

Apply a verified billing event idempotently — Applies an externally verified billing effect in one tenant-scoped transaction. The tenant row is locked before replay lookup and before any subscription lock. Subscription events update entitlement/quota; credit_grant updates only balance and ledger and returns subscription null. Older periods are journaled as immutable stale no-ops. The final non-null result is inserted once with the event after all effects are built; a global source-key or settlement-proof conflict rolls back every effect. Payment verification and private signing material stay outside this API.

  • Auth: bearer
  • Params: None
  • Body: BillingEventApplyRequest
  • operationId: applyBillingEvent
post:
  operationId: applyBillingEvent
  summary: Apply a verified billing event idempotently
  description: 'Applies an externally verified billing effect in one tenant-scoped
    transaction. The tenant row is locked before replay lookup and before any subscription
    lock. Subscription events update entitlement/quota; credit_grant updates only
    balance and ledger and returns subscription null. Older periods are journaled
    as immutable stale no-ops. The final non-null result is inserted once with the
    event after all effects are built; a global source-key or settlement-proof conflict
    rolls back every effect. Payment verification and private signing material stay
    outside this API.

    '
  tags:
  - Billing
  security:
  - moneyAdminAuth: []
  parameters:
  - $ref: '#/components/parameters/MoneyTenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/BillingEventApplyRequest'
  responses:
    '200':
      description: Event applied once or returned as an identical replay
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingEventApplyResult'
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'
    '404':
      $ref: '#/components/responses/NotFound'
    '409':
      $ref: '#/components/responses/BillingConflict'
    '422':
      $ref: '#/components/responses/BillingUnprocessable'

GET /api/v1/billing/events

Find tenant billing events for reconciliation — Admin-only, tenant-scoped journal lookup. Supply event_id, the complete source/source_id pair, or provider_subscription_id. Combined selectors use AND. Results are ordered by created_at descending and never expose another tenant's event.

  • Auth: bearer
  • Params: None, event_id, source, source_id, provider_subscription_id, limit
  • operationId: findBillingEvents
get:
  operationId: findBillingEvents
  summary: Find tenant billing events for reconciliation
  description: 'Admin-only, tenant-scoped journal lookup. Supply event_id, the complete
    source/source_id pair, or provider_subscription_id. Combined selectors use AND.
    Results are ordered by created_at descending and never expose another tenant''s
    event.

    '
  tags:
  - Billing
  security:
  - moneyAdminAuth: []
  parameters:
  - $ref: '#/components/parameters/MoneyTenantIdHeader'
  - name: event_id
    in: query
    schema:
      type: string
      format: uuid
  - name: source
    in: query
    description: Must be supplied together with source_id.
    schema:
      type: string
      maxLength: 128
  - name: source_id
    in: query
    description: Must be supplied together with source.
    schema:
      type: string
      maxLength: 512
  - name: provider_subscription_id
    in: query
    schema:
      type: string
      maxLength: 512
  - name: limit
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 50
      default: 20
  responses:
    '200':
      description: Matching tenant billing events
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BillingEventsResponse'
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '403':
      $ref: '#/components/responses/Forbidden'

Canonical

POST /api/v1/documents/{id}/canonical

Mark a document as canonical

  • Auth: bearer
  • Params: None, id*
  • Body: object( canonical (boolean) )
  • operationId: setCanonical
post:
  operationId: setCanonical
  summary: Mark a document as canonical
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            canonical:
              type: boolean
  responses:
    '200':
      description: Canonical status set
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/documents/{id}/suggest-filters

Suggest retrieval filters for a document

  • Auth: bearer
  • Params: None, id*
  • operationId: suggestFilters
post:
  operationId: suggestFilters
  summary: Suggest retrieval filters for a document
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Suggested filters
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/documents/{id}/probes

Register a validation probe for a document

  • Auth: bearer
  • Params: None, id*
  • operationId: registerProbe
post:
  operationId: registerProbe
  summary: Register a validation probe for a document
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Probe registered
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/conflicts

List canonical conflicts

  • Auth: bearer
  • Params: None
  • operationId: listConflicts
get:
  operationId: listConflicts
  summary: List canonical conflicts
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Conflict list
      content:
        application/json:
          schema:
            type: object
            properties:
              conflicts:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/proposals

List update proposals

  • Auth: bearer
  • Params: None
  • operationId: listProposals
get:
  operationId: listProposals
  summary: List update proposals
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Proposal list
      content:
        application/json:
          schema:
            type: object
            properties:
              proposals:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/proposals/{id}/pick

Pick a proposal variant

  • Auth: bearer
  • Params: None, id*
  • Body: object( variant (string) )
  • operationId: pickProposal
post:
  operationId: pickProposal
  summary: Pick a proposal variant
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            variant:
              type: string
  responses:
    '200':
      description: Proposal picked
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/proposals/{id}/resolve

Resolve a proposal

  • Auth: bearer
  • Params: None, id*
  • Body: object( status (string) )
  • operationId: resolveProposal
post:
  operationId: resolveProposal
  summary: Resolve a proposal
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            status:
              type: string
  responses:
    '200':
      description: Proposal resolved
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/probes

List validation probes

  • Auth: bearer
  • Params: None
  • operationId: listProbes
get:
  operationId: listProbes
  summary: List validation probes
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Probe list
      content:
        application/json:
          schema:
            type: object
            properties:
              probes:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/canonical/run

Trigger canonical detection run

  • Auth: bearer
  • Params: None
  • operationId: canonicalRun
post:
  operationId: canonicalRun
  summary: Trigger canonical detection run
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Canonical run initiated
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/canonical/sources

List canonical sources

  • Auth: bearer
  • Params: None
  • operationId: listCanonicalSources
get:
  operationId: listCanonicalSources
  summary: List canonical sources
  tags:
  - Canonical
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Source list
      content:
        application/json:
          schema:
            type: object
            properties:
              sources:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

Documents

POST /documents

Ingest a document — Create or update a document in a collection. Supports quality gate evaluation, schema packs, auto-linking, and temporal metadata. Requires X-Tenant-ID.

  • Auth: bearer
  • Params: None
  • Body: object( collection* (string), path* (string), title (string), content* (string), content_type (string), confidence (number), quality_score (number), metadata (object( )), user_id (string), run_id (string), event_at (string), event_type (string) )
  • operationId: ingestDocument
post:
  operationId: ingestDocument
  summary: Ingest a document
  description: 'Create or update a document in a collection. Supports quality gate
    evaluation, schema packs, auto-linking, and temporal metadata. Requires X-Tenant-ID.

    '
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - collection
          - path
          - content
          properties:
            collection:
              type: string
              description: Collection name
            path:
              type: string
              description: Unique document path within the collection
            title:
              type: string
            content:
              type: string
              maxLength: 1000000
              description: Document body (max 1MB)
            content_type:
              type: string
              default: note
            confidence:
              type: number
              minimum: 0
              maximum: 1
              default: 0.5
            quality_score:
              type: number
              minimum: 0
              maximum: 1
              default: 0.5
            metadata:
              type: object
              additionalProperties: true
            user_id:
              type: string
            run_id:
              type: string
            event_at:
              type: string
              format: date-time
            event_type:
              type: string
  responses:
    '200':
      description: Document ingested
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              id:
                type: integer
              path:
                type: string
              hash:
                type: string
              embed_state:
                type: string
              gate_verdict:
                type: object
                properties:
                  shouldIndex:
                    type: boolean
                  reason:
                    type: string
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /documents

List documents — List documents with optional filtering by collection.

  • Auth: bearer
  • Params: None, collection, limit, offset
  • operationId: listDocuments
get:
  operationId: listDocuments
  summary: List documents
  description: List documents with optional filtering by collection.
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: collection
    in: query
    schema:
      type: string
  - name: limit
    in: query
    schema:
      type: integer
      default: 50
  - name: offset
    in: query
    schema:
      type: integer
      default: 0
  responses:
    '200':
      description: List of documents
      content:
        application/json:
          schema:
            type: object
            properties:
              documents:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
              total:
                type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /documents/{id}

Get a document by ID or hash

  • Auth: bearer
  • Params: None, id*
  • operationId: getDocument
get:
  operationId: getDocument
  summary: Get a document by ID or hash
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
    description: Document ID or hash
  responses:
    '200':
      description: Document details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Document'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

PATCH /documents/{id}/visibility

Update document visibility

  • Auth: bearer
  • Params: None, id*
  • Body: object( visibility* (string) )
  • operationId: patchDocumentVisibility
patch:
  operationId: patchDocumentVisibility
  summary: Update document visibility
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - visibility
          properties:
            visibility:
              type: string
  responses:
    '200':
      description: Visibility updated
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

POST /documents/{id}/pin

Pin a document for permanent prioritization

  • Auth: bearer
  • Params: None, id*
  • operationId: pinDocument
post:
  operationId: pinDocument
  summary: Pin a document for permanent prioritization
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Document pinned
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /documents/{id}/snooze

Temporarily hide a document from context

  • Auth: bearer
  • Params: None, id*
  • Body: object( until (string) )
  • operationId: snoozeDocument
post:
  operationId: snoozeDocument
  summary: Temporarily hide a document from context
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            until:
              type: string
              format: date-time
  responses:
    '200':
      description: Document snoozed
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /documents/{id}/forget

Permanently deactivate a document

  • Auth: bearer
  • Params: None, id*
  • operationId: forgetDocument
post:
  operationId: forgetDocument
  summary: Permanently deactivate a document
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Document forgotten
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /documents/{id}/feedback

Submit relevance feedback for a document

  • Auth: bearer
  • Params: None, id*
  • Body: object( relevance* (enum(positive, negative)) )
  • operationId: documentFeedback
post:
  operationId: documentFeedback
  summary: Submit relevance feedback for a document
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - relevance
          properties:
            relevance:
              type: string
              enum:
              - positive
              - negative
  responses:
    '200':
      description: Feedback recorded
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

DELETE /documents/purge

Purge documents by collection — Delete all documents in a collection (exact or prefix match). Cleans up vectors, triples, and orphan records. Requires X-Tenant-ID.

  • Auth: bearer
  • Params: None, collection, collection_prefix
  • operationId: purgeDocuments
delete:
  operationId: purgeDocuments
  summary: Purge documents by collection
  description: 'Delete all documents in a collection (exact or prefix match). Cleans
    up vectors, triples, and orphan records. Requires X-Tenant-ID.

    '
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: collection
    in: query
    schema:
      type: string
    description: Exact collection name
  - name: collection_prefix
    in: query
    schema:
      type: string
    description: Collection name prefix (LIKE match)
  responses:
    '200':
      description: Purge result
      content:
        application/json:
          schema:
            type: object
            properties:
              purged:
                type: integer
              orphan_vectors_cleaned:
                type: integer
              orphan_triples_cleaned:
                type: integer
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /timeline/{id}

Temporal neighborhood around a document

  • Auth: bearer
  • Params: None, id*, before, after
  • operationId: timeline
get:
  operationId: timeline
  summary: Temporal neighborhood around a document
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  - name: before
    in: query
    schema:
      type: integer
      default: 5
  - name: after
    in: query
    schema:
      type: integer
      default: 5
  responses:
    '200':
      description: Timeline context
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /sessions

List recent sessions

  • Auth: bearer
  • Params: None
  • operationId: listSessions
get:
  operationId: listSessions
  summary: List recent sessions
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Session list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /collections

List all collections

  • Auth: bearer
  • Params: None
  • operationId: listCollections
get:
  operationId: listCollections
  summary: List all collections
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Collection list
      content:
        application/json:
          schema:
            type: object
            properties:
              collections:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    count:
                      type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /profile

Get current tenant/user profile

  • Auth: bearer
  • Params: None
  • operationId: getProfile
get:
  operationId: getProfile
  summary: Get current tenant/user profile
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Profile data
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /export

Export documents

  • Auth: bearer
  • Params: None, collection, format
  • operationId: exportData
get:
  operationId: exportData
  summary: Export documents
  tags:
  - Documents
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: collection
    in: query
    schema:
      type: string
  - name: format
    in: query
    schema:
      type: string
      enum:
      - json
      - markdown
      default: json
  responses:
    '200':
      description: Exported data
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

Entity

GET /api/v1/entities/{name}/card

Get entity card by name

  • Auth: bearer
  • Params: None, name*
  • operationId: getEntityCard
get:
  operationId: getEntityCard
  summary: Get entity card by name
  tags:
  - Entity
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: name
    in: path
    required: true
    schema:
      type: string
    description: Entity name
  responses:
    '200':
      description: Entity card
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

POST /api/v1/entities/{name}/card

Create or update an entity card

  • Auth: bearer
  • Params: None, name*
  • Body: object( summary (string), aliases (array[string]), metadata (object( )) )
  • operationId: upsertEntityCard
post:
  operationId: upsertEntityCard
  summary: Create or update an entity card
  tags:
  - Entity
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: name
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            summary:
              type: string
            aliases:
              type: array
              items:
                type: string
            metadata:
              type: object
              additionalProperties: true
  responses:
    '200':
      description: Entity card upserted
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/triples

Create an SPO triple — Create a subject-predicate-object triple. Resolves entity names to IDs.

  • Auth: bearer
  • Params: None
  • Body: object( subject* (string), predicate* (string), object* (string), confidence (number) )
  • operationId: createTriple
post:
  operationId: createTriple
  summary: Create an SPO triple
  description: Create a subject-predicate-object triple. Resolves entity names to
    IDs.
  tags:
  - Entity
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - subject
          - predicate
          - object
          properties:
            subject:
              type: string
            predicate:
              type: string
            object:
              type: string
            confidence:
              type: number
              default: 0.8
  responses:
    '200':
      description: Triple created
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              triple:
                type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

Foundations

GET /foundations

Get Tier-0 foundation context

  • Auth: bearer
  • Params: None
  • operationId: getFoundations
get:
  operationId: getFoundations
  summary: Get Tier-0 foundation context
  tags:
  - Foundations
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Foundation documents
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/state

Get structured engine state

  • Auth: bearer
  • Params: None
  • operationId: getState
get:
  operationId: getState
  summary: Get structured engine state
  tags:
  - Foundations
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Structured state
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/foundations

Create a foundation document

  • Auth: bearer
  • Params: None
  • Body: object( path* (string), content* (string), title (string), layer (string) )
  • operationId: createFoundation
post:
  operationId: createFoundation
  summary: Create a foundation document
  tags:
  - Foundations
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - path
          - content
          properties:
            path:
              type: string
            content:
              type: string
            title:
              type: string
            layer:
              type: string
  responses:
    '200':
      description: Foundation created
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/foundations/{id}

Update a foundation document

  • Auth: bearer
  • Params: None, id*
  • Body: object( content (string), title (string) )
  • operationId: updateFoundation
put:
  operationId: updateFoundation
  summary: Update a foundation document
  tags:
  - Foundations
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            content:
              type: string
            title:
              type: string
  responses:
    '200':
      description: Foundation updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

DELETE /api/v1/foundations/{id}

Delete a foundation document

  • Auth: bearer
  • Params: None, id*
  • operationId: deleteFoundation
delete:
  operationId: deleteFoundation
  summary: Delete a foundation document
  tags:
  - Foundations
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Foundation deleted
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

POST /api/v1/foundations/{id}/promote

Promote a foundation to a higher layer

  • Auth: bearer
  • Params: None, id*
  • operationId: promoteFoundation
post:
  operationId: promoteFoundation
  summary: Promote a foundation to a higher layer
  tags:
  - Foundations
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Foundation promoted
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

Graph

GET /graph/causal/{id}

Get causal links for a document

  • Auth: bearer
  • Params: None, id*, direction, depth
  • operationId: getCausalLinks
get:
  operationId: getCausalLinks
  summary: Get causal links for a document
  tags:
  - Graph
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  - name: direction
    in: query
    schema:
      type: string
      enum:
      - causes
      - caused_by
      - both
      default: both
  - name: depth
    in: query
    schema:
      type: integer
      default: 5
      minimum: 1
      maximum: 10
  responses:
    '200':
      description: Causal link graph
      content:
        application/json:
          schema:
            type: object
            properties:
              links:
                type: array
                items:
                  type: object
                  properties:
                    docid:
                      type: string
                    direction:
                      type: string
                    depth:
                      type: integer
                    reasoning:
                      type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /graph/similar/{id}

Find semantically similar documents

  • Auth: bearer
  • Params: None, id*, limit
  • operationId: getSimilar
get:
  operationId: getSimilar
  summary: Find semantically similar documents
  tags:
  - Graph
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  - name: limit
    in: query
    schema:
      type: integer
      default: 5
  responses:
    '200':
      description: Similar documents
      content:
        application/json:
          schema:
            type: object
            properties:
              similar:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /graph/evolution/{id}

Get memory evolution timeline for a document

  • Auth: bearer
  • Params: None, id*, limit
  • operationId: getEvolution
get:
  operationId: getEvolution
  summary: Get memory evolution timeline for a document
  tags:
  - Graph
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  - name: limit
    in: query
    schema:
      type: integer
      default: 10
  responses:
    '200':
      description: Evolution timeline
      content:
        application/json:
          schema:
            type: object
            properties:
              evolution:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

Health

GET /healthz

Public liveness probe — Returns 200 if the process is up. No auth, no store dependency.

  • Auth: none
  • operationId: healthz
get:
  operationId: healthz
  summary: Public liveness probe
  description: Returns 200 if the process is up. No auth, no store dependency.
  tags:
  - Health
  security: []
  responses:
    '200':
      description: Process is alive
      content:
        application/json:
          schema:
            type: object
            required:
            - status
            - service
            - timestamp
            properties:
              status:
                type: string
                enum:
                - ok
              service:
                type: string
              timestamp:
                type: string
                format: date-time

GET /health

Health check with database status — Returns service status, document counts, vector index state, and request context.

  • Auth: none
  • operationId: health
get:
  operationId: health
  summary: Health check with database status
  description: Returns service status, document counts, vector index state, and request
    context.
  tags:
  - Health
  security: []
  responses:
    '200':
      description: Service health
      content:
        application/json:
          schema:
            type: object
            required:
            - status
            - service
            properties:
              status:
                type: string
              service:
                type: string
              version:
                type: string
              database:
                type: string
              documents:
                type: integer
              needsEmbedding:
                type: integer
              hasVectors:
                type: boolean
              request:
                $ref: '#/components/schemas/RequestContext'

GET /health/deep

Deep health check with per-component probes — Probes database, documents, LLM config, and embed worker. Used by uptime monitors.

  • Auth: none
  • operationId: healthDeep
get:
  operationId: healthDeep
  summary: Deep health check with per-component probes
  description: Probes database, documents, LLM config, and embed worker. Used by uptime
    monitors.
  tags:
  - Health
  security: []
  responses:
    '200':
      description: Component-level health
      content:
        application/json:
          schema:
            type: object
            required:
            - checks
            properties:
              checks:
                type: object
                additionalProperties:
                  type: object
                  required:
                  - ok
                  properties:
                    ok:
                      type: boolean
                    latency_ms:
                      type: integer
                    detail:
                      type: string
                    error:
                      type: string
              latency_ms:
                type: integer

GET /state

Engine state summary

  • Auth: bearer
  • operationId: state
get:
  operationId: state
  summary: Engine state summary
  tags:
  - Health
  responses:
    '200':
      description: State object
      content:
        application/json:
          schema:
            type: object

GET /stats

Index statistics and health

  • Auth: bearer
  • operationId: stats
get:
  operationId: stats
  summary: Index statistics and health
  tags:
  - Health
  responses:
    '200':
      description: Stats including document counts, collections, and health
      content:
        application/json:
          schema:
            type: object
            properties:
              documents:
                type: integer
              totalDocuments:
                type: integer
              needsEmbedding:
                type: integer
              collections:
                type: array
                items:
                  type: object
              health:
                type: object

GET /reports/memory

Memory usage report — Tenant-scoped memory report. Requires X-Tenant-ID.

  • Auth: bearer
  • Params: None
  • operationId: reportsMemory
get:
  operationId: reportsMemory
  summary: Memory usage report
  description: Tenant-scoped memory report. Requires X-Tenant-ID.
  tags:
  - Health
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Memory report
      content:
        application/json:
          schema:
            type: object
    '400':
      $ref: '#/components/responses/BadRequest'

GET /openapi.json

OpenAPI 3.1 specification (JSON) — Returns the full API specification as JSON.

  • Auth: none
  • operationId: openapiSpec
get:
  operationId: openapiSpec
  summary: OpenAPI 3.1 specification (JSON)
  description: Returns the full API specification as JSON.
  tags:
  - Health
  security: []
  responses:
    '200':
      description: OpenAPI specification
      content:
        application/json:
          schema:
            type: object

Identity

GET /api/v1/identity

Get current identity

  • Auth: bearer
  • Params: None
  • operationId: getIdentity
get:
  operationId: getIdentity
  summary: Get current identity
  tags:
  - Identity
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Identity profile
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              email:
                type: string
              tenant_id:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/identity

Update current identity

  • Auth: bearer
  • Params: None
  • Body: object( name (string), email (string), preferences (object( )) )
  • operationId: updateIdentity
put:
  operationId: updateIdentity
  summary: Update current identity
  tags:
  - Identity
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            preferences:
              type: object
  responses:
    '200':
      description: Identity updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

Lifecycle

GET /lifecycle/status

Document lifecycle status

  • Auth: bearer
  • Params: None
  • operationId: lifecycleStatus
get:
  operationId: lifecycleStatus
  summary: Document lifecycle status
  tags:
  - Lifecycle
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Lifecycle statistics
      content:
        application/json:
          schema:
            type: object
            properties:
              active:
                type: integer
              archived:
                type: integer
              forgotten:
                type: integer
              pinned:
                type: integer
              snoozed:
                type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /lifecycle/sweep

Run lifecycle sweep — Archive stale docs, optionally purge old archives. Defaults to dry run.

  • Auth: bearer
  • Params: None
  • Body: object( dry_run (boolean) )
  • operationId: lifecycleSweep
post:
  operationId: lifecycleSweep
  summary: Run lifecycle sweep
  description: Archive stale docs, optionally purge old archives. Defaults to dry
    run.
  tags:
  - Lifecycle
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            dry_run:
              type: boolean
              default: true
  responses:
    '200':
      description: Sweep result
      content:
        application/json:
          schema:
            type: object
            properties:
              dry_run:
                type: boolean
              to_archive:
                type: integer
              to_purge:
                type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /lifecycle/restore

Restore archived documents

  • Auth: bearer
  • Params: None
  • Body: object( query (string), collection (string), all (boolean) )
  • operationId: lifecycleRestore
post:
  operationId: lifecycleRestore
  summary: Restore archived documents
  tags:
  - Lifecycle
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            query:
              type: string
            collection:
              type: string
            all:
              type: boolean
              default: false
  responses:
    '200':
      description: Restore result
      content:
        application/json:
          schema:
            type: object
            properties:
              restored:
                type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

MCP Tokens

GET /api/v1/mcp/tokens

List MCP API tokens

  • Auth: bearer
  • Params: None
  • operationId: listMcpTokens
get:
  operationId: listMcpTokens
  summary: List MCP API tokens
  tags:
  - MCP Tokens
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Token list
      content:
        application/json:
          schema:
            type: object
            properties:
              tokens:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    prefix:
                      type: string
                    is_active:
                      type: boolean
                    created_at:
                      type: string
                      format: date-time
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/mcp/tokens

Create an MCP API token

  • Auth: bearer
  • Params: None
  • Body: object( name* (string), expires_at (string) )
  • operationId: createMcpToken
post:
  operationId: createMcpToken
  summary: Create an MCP API token
  tags:
  - MCP Tokens
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - name
          properties:
            name:
              type: string
            expires_at:
              type: string
              format: date-time
  responses:
    '200':
      description: Token created (full key returned only once)
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              id:
                type: string
              key:
                type: string
                description: Full API key (shown only at creation)
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/mcp/tokens/{tokenId}

Get MCP token details

  • Auth: bearer
  • Params: None, tokenId*
  • operationId: getMcpToken
get:
  operationId: getMcpToken
  summary: Get MCP token details
  tags:
  - MCP Tokens
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: tokenId
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Token details
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

PUT /api/v1/mcp/tokens/{tokenId}

Update MCP token

  • Auth: bearer
  • Params: None, tokenId*
  • Body: object( name (string), is_active (boolean) )
  • operationId: updateMcpToken
put:
  operationId: updateMcpToken
  summary: Update MCP token
  tags:
  - MCP Tokens
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: tokenId
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            name:
              type: string
            is_active:
              type: boolean
  responses:
    '200':
      description: Token updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

DELETE /api/v1/mcp/tokens/{tokenId}

Delete MCP token

  • Auth: bearer
  • Params: None, tokenId*
  • operationId: deleteMcpToken
delete:
  operationId: deleteMcpToken
  summary: Delete MCP token
  tags:
  - MCP Tokens
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: tokenId
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Token deleted
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

Maintenance

POST /reindex

Trigger full reindex — Re-scan all collections, detect new/changed/deleted documents.

  • Auth: bearer
  • Params: None
  • operationId: reindex
post:
  operationId: reindex
  summary: Trigger full reindex
  description: Re-scan all collections, detect new/changed/deleted documents.
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Reindex initiated
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /graphs/build

Build temporal and semantic graphs

  • Auth: bearer
  • Params: None
  • Body: object( graph_types (array[enum(temporal, semantic, all)]) )
  • operationId: buildGraphs
post:
  operationId: buildGraphs
  summary: Build temporal and semantic graphs
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            graph_types:
              type: array
              items:
                type: string
                enum:
                - temporal
                - semantic
                - all
              semantic_threshold:
                type: number
                default: 0.7
  responses:
    '200':
      description: Graph build initiated
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/collection-settings

List all collection settings

  • Auth: bearer
  • Params: None
  • operationId: listCollectionSettings
get:
  operationId: listCollectionSettings
  summary: List all collection settings
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Settings list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/collection-settings/reindex

Re-evaluate documents against quality gate rules

  • Auth: bearer
  • Params: None
  • operationId: reindexCollectionSettings
get:
  operationId: reindexCollectionSettings
  summary: Re-evaluate documents against quality gate rules
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Reindex result
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              collection:
                type: string
              dry_run:
                type: boolean
              total_docs:
                type: integer
              to_skip:
                type: integer
              to_index:
                type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/collection-settings/reindex

Re-evaluate documents against quality gate rules (POST)

  • Auth: bearer
  • Params: None
  • Body: object( collection* (string), dry_run (boolean) )
  • operationId: reindexCollectionSettingsPost
post:
  operationId: reindexCollectionSettingsPost
  summary: Re-evaluate documents against quality gate rules (POST)
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - collection
          properties:
            collection:
              type: string
            dry_run:
              type: boolean
              default: false
  responses:
    '200':
      description: Reindex result
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/collection-settings/{collection}

Get settings for a collection

  • Auth: bearer
  • Params: None, collection*
  • operationId: getCollectionSettings
get:
  operationId: getCollectionSettings
  summary: Get settings for a collection
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: collection
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Collection settings
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

PUT /api/v1/collection-settings/{collection}

Set settings for a collection

  • Auth: bearer
  • Params: None, collection*
  • Body: object( max_doc_size (integer), skip_patterns (array[string]), min_quality_score (number) )
  • operationId: setCollectionSettings
put:
  operationId: setCollectionSettings
  summary: Set settings for a collection
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: collection
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            max_doc_size:
              type: integer
            skip_patterns:
              type: array
              items:
                type: string
            min_quality_score:
              type: number
  responses:
    '200':
      description: Settings updated
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

DELETE /api/v1/collection-settings/{collection}

Delete settings for a collection

  • Auth: bearer
  • Params: None, collection*
  • operationId: deleteCollectionSettings
delete:
  operationId: deleteCollectionSettings
  summary: Delete settings for a collection
  tags:
  - Maintenance
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: collection
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Settings deleted
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /generate

LLM text generation (benchmark only) — Exposes the engine's local LLM as a simple text generation API. Benchmark tooling only.

  • Auth: bearer
  • Body: object( prompt* (string), maxTokens (integer), temperature (number) )
  • operationId: generate
post:
  operationId: generate
  summary: LLM text generation (benchmark only)
  description: Exposes the engine's local LLM as a simple text generation API. Benchmark
    tooling only.
  tags:
  - Maintenance
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - prompt
          properties:
            prompt:
              type: string
            maxTokens:
              type: integer
              default: 512
              maximum: 2048
            temperature:
              type: number
              minimum: 0
              maximum: 2
  responses:
    '200':
      description: Generated text
      content:
        application/json:
          schema:
            type: object
            properties:
              text:
                type: string
              model:
                type: string
              tokens:
                type: integer
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /skills

List registered skills

  • Auth: bearer
  • operationId: listSkills
get:
  operationId: listSkills
  summary: List registered skills
  tags:
  - Maintenance
  responses:
    '200':
      description: Skill list
      content:
        application/json:
          schema:
            type: object
            properties:
              skills:
                type: array
                items:
                  type: object

POST /skills

Register a new skill

  • Auth: bearer
  • Body: object( name* (string), description (string), handler (string) )
  • operationId: addSkill
post:
  operationId: addSkill
  summary: Register a new skill
  tags:
  - Maintenance
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - name
          properties:
            name:
              type: string
            description:
              type: string
            handler:
              type: string
  responses:
    '200':
      description: Skill registered
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean

GET /skills/{skillId}

Get skill details

  • Auth: bearer
  • Params: skillId*
  • operationId: getSkill
get:
  operationId: getSkill
  summary: Get skill details
  tags:
  - Maintenance
  parameters:
  - name: skillId
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Skill details
      content:
        application/json:
          schema:
            type: object
    '404':
      $ref: '#/components/responses/NotFound'

GET /setup/instructions

Get setup instructions (public)

  • Auth: none
  • operationId: setupInstructions
get:
  operationId: setupInstructions
  summary: Get setup instructions (public)
  tags:
  - Maintenance
  security: []
  responses:
    '200':
      description: Setup instructions
      content:
        application/json:
          schema:
            type: object

OAuth

GET /.well-known/oauth-authorization-server

OAuth authorization server metadata — Public discovery endpoint per RFC 9414.

  • Auth: none
  • operationId: oauthAsMetadata
get:
  operationId: oauthAsMetadata
  summary: OAuth authorization server metadata
  description: Public discovery endpoint per RFC 9414.
  tags:
  - OAuth
  security: []
  responses:
    '200':
      description: Authorization server metadata
      content:
        application/json:
          schema:
            type: object

GET /.well-known/oauth-protected-resource

OAuth protected resource metadata — Public discovery endpoint per RFC 9728.

  • Auth: none
  • operationId: oauthRsMetadata
get:
  operationId: oauthRsMetadata
  summary: OAuth protected resource metadata
  description: Public discovery endpoint per RFC 9728.
  tags:
  - OAuth
  security: []
  responses:
    '200':
      description: Protected resource metadata
      content:
        application/json:
          schema:
            type: object

POST /oauth/register

Dynamic client registration

  • Auth: none
  • Body: object( client_name (string), redirect_uris (array[string]), grant_types (array[string]) )
  • operationId: oauthRegister
post:
  operationId: oauthRegister
  summary: Dynamic client registration
  tags:
  - OAuth
  security: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            client_name:
              type: string
            redirect_uris:
              type: array
              items:
                type: string
            grant_types:
              type: array
              items:
                type: string
  responses:
    '201':
      description: Client registered
      content:
        application/json:
          schema:
            type: object
            properties:
              client_id:
                type: string
              client_secret:
                type: string
    '400':
      $ref: '#/components/responses/BadRequest'

GET /oauth/authorize

OAuth authorization endpoint — Redirects to consent page.

  • Auth: none
  • Params: response_type, client_id, redirect_uri, scope, state
  • operationId: oauthAuthorize
get:
  operationId: oauthAuthorize
  summary: OAuth authorization endpoint
  description: Redirects to consent page.
  tags:
  - OAuth
  security: []
  parameters:
  - name: response_type
    in: query
    required: true
    schema:
      type: string
  - name: client_id
    in: query
    required: true
    schema:
      type: string
  - name: redirect_uri
    in: query
    schema:
      type: string
  - name: scope
    in: query
    schema:
      type: string
  - name: state
    in: query
    schema:
      type: string
  responses:
    '302':
      description: Redirect to consent page
    '400':
      $ref: '#/components/responses/BadRequest'

GET /oauth/consent

OAuth consent page

  • Auth: none
  • operationId: oauthConsentPage
get:
  operationId: oauthConsentPage
  summary: OAuth consent page
  tags:
  - OAuth
  security: []
  responses:
    '200':
      description: HTML consent form

POST /oauth/consent

Submit OAuth consent

  • Auth: none
  • operationId: oauthConsentSubmit
post:
  operationId: oauthConsentSubmit
  summary: Submit OAuth consent
  tags:
  - OAuth
  security: []
  requestBody:
    required: true
    content:
      application/x-www-form-urlencoded:
        schema:
          type: object
  responses:
    '302':
      description: Redirect back to client

POST /oauth/token

OAuth token exchange

  • Auth: none
  • operationId: oauthToken
post:
  operationId: oauthToken
  summary: OAuth token exchange
  tags:
  - OAuth
  security: []
  requestBody:
    required: true
    content:
      application/x-www-form-urlencoded:
        schema:
          type: object
          required:
          - grant_type
          properties:
            grant_type:
              type: string
            code:
              type: string
            client_id:
              type: string
            client_secret:
              type: string
            redirect_uri:
              type: string
  responses:
    '200':
      description: Token response
      content:
        application/json:
          schema:
            type: object
            properties:
              access_token:
                type: string
              token_type:
                type: string
              expires_in:
                type: integer
              refresh_token:
                type: string
    '400':
      $ref: '#/components/responses/BadRequest'

POST /oauth/revoke

Revoke an OAuth token

  • Auth: none
  • operationId: oauthRevoke
post:
  operationId: oauthRevoke
  summary: Revoke an OAuth token
  tags:
  - OAuth
  security: []
  requestBody:
    required: true
    content:
      application/x-www-form-urlencoded:
        schema:
          type: object
          required:
          - token
          properties:
            token:
              type: string
  responses:
    '200':
      description: Token revoked

Observability

GET /metrics

Prometheus metrics — Public endpoint for Prometheus scraping. Low cardinality.

  • Auth: none
  • operationId: metrics
get:
  operationId: metrics
  summary: Prometheus metrics
  description: Public endpoint for Prometheus scraping. Low cardinality.
  tags:
  - Observability
  security: []
  responses:
    '200':
      description: Prometheus text format metrics
      content:
        text/plain:
          schema:
            type: string

GET /api/v1/trajectories

List retrieval trajectories

  • Auth: bearer
  • Params: None
  • operationId: listTrajectories
get:
  operationId: listTrajectories
  summary: List retrieval trajectories
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Trajectory list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/roi

Get ROI metrics

  • Auth: bearer
  • Params: None
  • operationId: getROI
get:
  operationId: getROI
  summary: Get ROI metrics
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: ROI data
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/digest/send

Send email digest

  • Auth: bearer
  • Params: None
  • operationId: sendDigest
post:
  operationId: sendDigest
  summary: Send email digest
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Digest sent
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/features

List feature flags

  • Auth: bearer
  • Params: None
  • operationId: listFeatures
get:
  operationId: listFeatures
  summary: List feature flags
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Feature flags
      content:
        application/json:
          schema:
            type: object
            properties:
              features:
                type: object
                additionalProperties:
                  type: boolean
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/features

Set a feature flag

  • Auth: bearer
  • Params: None
  • Body: object( name* (string), enabled* (boolean) )
  • operationId: setFeature
post:
  operationId: setFeature
  summary: Set a feature flag
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - name
          - enabled
          properties:
            name:
              type: string
            enabled:
              type: boolean
  responses:
    '200':
      description: Feature flag updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/config

Get tenant configuration

  • Auth: bearer
  • Params: None
  • operationId: getTenantConfig
get:
  operationId: getTenantConfig
  summary: Get tenant configuration
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Tenant config
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/config/{key}

Set a tenant configuration key

  • Auth: bearer
  • Params: None, key*
  • Body: object( )
  • operationId: setTenantConfigKey
put:
  operationId: setTenantConfigKey
  summary: Set a tenant configuration key
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: key
    in: path
    required: true
    schema:
      type: string
      pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
  responses:
    '200':
      description: Config key updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/criteria

Get retrieval criteria

  • Auth: bearer
  • Params: None
  • operationId: getCriteria
get:
  operationId: getCriteria
  summary: Get retrieval criteria
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Criteria list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/criteria

Set retrieval criteria

  • Auth: bearer
  • Params: None
  • Body: object( )
  • operationId: setCriteria
put:
  operationId: setCriteria
  summary: Set retrieval criteria
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
  responses:
    '200':
      description: Criteria updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/benchmark/run

Run a benchmark

  • Auth: bearer
  • Params: None
  • Body: object( queries (array[string]), expected (array[object( )]) )
  • operationId: benchmarkRun
post:
  operationId: benchmarkRun
  summary: Run a benchmark
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            queries:
              type: array
              items:
                type: string
            expected:
              type: array
              items:
                type: object
  responses:
    '200':
      description: Benchmark results
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/benchmark/runs

List benchmark runs

  • Auth: bearer
  • Params: None
  • operationId: benchmarkListRuns
get:
  operationId: benchmarkListRuns
  summary: List benchmark runs
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Benchmark run list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/benchmark/compare

Compare benchmark runs

  • Auth: bearer
  • Params: None, run_a, run_b
  • operationId: benchmarkCompare
get:
  operationId: benchmarkCompare
  summary: Compare benchmark runs
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: run_a
    in: query
    schema:
      type: string
  - name: run_b
    in: query
    schema:
      type: string
  responses:
    '200':
      description: Comparison results
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/memory/recall

Token-budgeted memory recall — Pull category-ranked memory in a fixed token budget (mem0-style).

  • Auth: bearer
  • Params: None
  • Body: object( query (string), budget (integer), format (enum(json, markdown)) )
  • operationId: memoryRecall
post:
  operationId: memoryRecall
  summary: Token-budgeted memory recall
  description: Pull category-ranked memory in a fixed token budget (mem0-style).
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            query:
              type: string
            budget:
              type: integer
              default: 1500
            format:
              type: string
              enum:
              - json
              - markdown
              default: markdown
  responses:
    '200':
      description: Budgeted memory recall
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/memory/used

Declare which memories an answer actually used (quality loop) — REST mirror of the MCP memory_used tool. The agent declares the docids ('#ab12cd' hex prefixes) or paths of the memories it relied on; optionally a verdict ("confirmed"/"corrected") when the user reacted to what the memory said. Feeds usage coverage, ranking signals and the trust loop. Infra agents excluded downstream.

  • Auth: bearer
  • Params: None
  • Body: object( docids* (array[string]), verdict (enum(confirmed, corrected)), note (string) )
  • operationId: memoryUsed
post:
  operationId: memoryUsed
  summary: Declare which memories an answer actually used (quality loop)
  description: 'REST mirror of the MCP `memory_used` tool. The agent declares the
    docids (''#ab12cd'' hex prefixes) or paths of the memories it relied on; optionally
    a verdict ("confirmed"/"corrected") when the user reacted to what the memory said.
    Feeds usage coverage, ranking signals and the trust loop. Infra agents excluded
    downstream.

    '
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - docids
          properties:
            docids:
              type: array
              items:
                type: string
              minItems: 1
              description: Docids ('#ab12cd') or document paths
            verdict:
              type: string
              enum:
              - confirmed
              - corrected
              description: User confirmed or corrected what the memory said (V5)
            note:
              type: string
              description: Why the memories were useful
  responses:
    '200':
      description: Declaration recorded
      content:
        application/json:
          schema:
            type: object
            properties:
              declared:
                type: integer
              marked:
                type: integer
              unresolved:
                type: array
                items:
                  type: string
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

GET /api/v1/tenant/value-summary

Counted value by usage family for the Impact home and digest — Hero numbers (searches served, contexts delivered, memories recorded), usage families, quality coverage (sessions with declared memory_used over sessions with delivered context), active agents, knowledge timeline and per-operation breakdown. Completed days are served from the pre-computed value_daily table; the current day aggregates live; days the nightly job missed fall back to live aggregation and are reported in stale_days. Infra agents excluded from every family.

  • Auth: bearer
  • Params: None, period
  • operationId: tenantValueSummary
get:
  operationId: tenantValueSummary
  summary: Counted value by usage family for the Impact home and digest
  description: 'Hero numbers (searches served, contexts delivered, memories recorded),
    usage families, quality coverage (sessions with declared memory_used over sessions
    with delivered context), active agents, knowledge timeline and per-operation breakdown.
    Completed days are served from the pre-computed value_daily table; the current
    day aggregates live; days the nightly job missed fall back to live aggregation
    and are reported in stale_days. Infra agents excluded from every family.

    '
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: period
    in: query
    schema:
      type: string
      enum:
      - today
      - yesterday
      - 7d
      - 30d
      default: 7d
    description: Window (UTC days); yesterday is the closed digest day
  responses:
    '200':
      description: Value summary
      content:
        application/json:
          schema:
            type: object
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/memory/health

Memory health diagnostics

  • Auth: bearer
  • Params: None
  • operationId: memoryHealth
get:
  operationId: memoryHealth
  summary: Memory health diagnostics
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Health diagnostics
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/privacy/preview

Preview privacy extraction

  • Auth: bearer
  • Params: None
  • Body: object( content* (string) )
  • operationId: privacyPreview
post:
  operationId: privacyPreview
  summary: Preview privacy extraction
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - content
          properties:
            content:
              type: string
  responses:
    '200':
      description: Privacy preview
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/privacy/sanitize

Sanitize PII from content

  • Auth: bearer
  • Params: None
  • Body: object( content* (string) )
  • operationId: privacySanitize
post:
  operationId: privacySanitize
  summary: Sanitize PII from content
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - content
          properties:
            content:
              type: string
  responses:
    '200':
      description: Sanitized content
      content:
        application/json:
          schema:
            type: object
            properties:
              sanitized:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/privacy/restore

Restore sanitized content

  • Auth: bearer
  • Params: None
  • Body: object( content* (string), tokens* (array[object( )]) )
  • operationId: privacyRestore
post:
  operationId: privacyRestore
  summary: Restore sanitized content
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - content
          - tokens
          properties:
            content:
              type: string
            tokens:
              type: array
              items:
                type: object
  responses:
    '200':
      description: Restored content
      content:
        application/json:
          schema:
            type: object
            properties:
              restored:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/foresights

List foresight predictions

  • Auth: bearer
  • Params: None
  • operationId: listForesights
get:
  operationId: listForesights
  summary: List foresight predictions
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Foresight list
      content:
        application/json:
          schema:
            type: object
            properties:
              foresights:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/foresights/sweep

Trigger foresight sweep

  • Auth: bearer
  • Params: None
  • operationId: sweepForesights
post:
  operationId: sweepForesights
  summary: Trigger foresight sweep
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Sweep initiated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/foresights/{id}

Get a specific foresight

  • Auth: bearer
  • Params: None, id*
  • operationId: getForesight
get:
  operationId: getForesight
  summary: Get a specific foresight
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Foresight details
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

PATCH /api/v1/foresights/{id}

Update a foresight

  • Auth: bearer
  • Params: None, id*
  • Body: object( )
  • operationId: patchForesight
patch:
  operationId: patchForesight
  summary: Update a foresight
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
  responses:
    '200':
      description: Foresight updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

DELETE /api/v1/foresights/{id}

Delete a foresight

  • Auth: bearer
  • Params: None, id*
  • operationId: deleteForesight
delete:
  operationId: deleteForesight
  summary: Delete a foresight
  tags:
  - Observability
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: id
    in: path
    required: true
    schema:
      type: string
  responses:
    '200':
      description: Foresight deleted
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

Runtime

PATCH /api/v1/entities/{name}/card

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PATCH__api_v1_entities_name_card
patch:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PATCH__api_v1_entities_name_card
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

DELETE /api/v1/entities/{name}/card

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_DELETE__api_v1_entities_name_card
delete:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_DELETE__api_v1_entities_name_card
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /openapi.yaml

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__openapi_yaml
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__openapi_yaml
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /health/admin

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__health_admin
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__health_admin
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /reports/usage

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__reports_usage
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__reports_usage
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/memory/team-activity

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_memory_team_activity
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_memory_team_activity
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /dashboard

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__dashboard
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__dashboard
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /memory-map

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__memory_map
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__memory_map
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/knowledge-gaps

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_knowledge_gaps
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_knowledge_gaps
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/knowledge-gaps/{id}/resolve

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_knowledge_gaps_id_resolve
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_knowledge_gaps_id_resolve
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /conversations

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__conversations
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__conversations
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /contradictions

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__contradictions
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__contradictions
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /documents/changes

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__documents_changes
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__documents_changes
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /documents/{id}/chain

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__documents_id_chain
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__documents_id_chain
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PATCH /documents/{id}/veracity

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PATCH__documents_id_veracity
patch:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PATCH__documents_id_veracity
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PATCH /api/v1/documents/{id}/veracity

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PATCH__api_v1_documents_id_veracity
patch:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PATCH__api_v1_documents_id_veracity
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PATCH /documents/veracity/bulk

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PATCH__documents_veracity_bulk
patch:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PATCH__documents_veracity_bulk
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PATCH /api/v1/documents/veracity/bulk

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PATCH__api_v1_documents_veracity_bulk
patch:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PATCH__api_v1_documents_veracity_bulk
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /collections/health

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__collections_health
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__collections_health
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /collections/{id}/lifecycle

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__collections_id_lifecycle
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__collections_id_lifecycle
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/memory/working-context

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_memory_working_context
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_memory_working_context
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /memory/working-context

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__memory_working_context
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__memory_working_context
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_scratchpad
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PUT /api/v1/scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PUT__api_v1_scratchpad
put:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PUT__api_v1_scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_scratchpad
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

DELETE /api/v1/scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_DELETE__api_v1_scratchpad
delete:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_DELETE__api_v1_scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__scratchpad
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PUT /scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PUT__scratchpad
put:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PUT__scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__scratchpad
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

DELETE /scratchpad

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_DELETE__scratchpad
delete:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_DELETE__scratchpad
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /setup/artifacts

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__setup_artifacts
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__setup_artifacts
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/entity-cards

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_entity_cards
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_entity_cards
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/pins

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_pins
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_pins
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/pins

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_pins
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_pins
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/pins/{id}

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_pins_id_
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_pins_id_
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

PATCH /api/v1/pins/{id}

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_PATCH__api_v1_pins_id_
patch:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_PATCH__api_v1_pins_id_
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

DELETE /api/v1/pins/{id}

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_DELETE__api_v1_pins_id_
delete:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_DELETE__api_v1_pins_id_
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/session-handoffs

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_session_handoffs
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_session_handoffs
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/session-handoffs

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_session_handoffs
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_session_handoffs
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/team/members

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_team_members
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_team_members
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/team/messages

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_team_messages
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_team_messages
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/team/inbox

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_team_inbox
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_team_inbox
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/team/handoffs

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_team_handoffs
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_team_handoffs
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/team/handoffs

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_team_handoffs
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_team_handoffs
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/team/briefing

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_team_briefing
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_team_briefing
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/team/stream

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_team_stream
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_team_stream
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/memory/episodes

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_memory_episodes
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_memory_episodes
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/memory/episodes/{id}

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_memory_episodes_id_
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_memory_episodes_id_
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /admin/queues

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__admin_queues
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__admin_queues
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /admin/queues

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__admin_queues
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__admin_queues
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/admin/tenants/{id}/api-tokens

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_admin_tenants_id_api_tokens
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_admin_tenants_id_api_tokens
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/admin/tenants/{id}/api-tokens

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_admin_tenants_id_api_tokens
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_admin_tenants_id_api_tokens
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

DELETE /api/v1/admin/tenants/{id}/api-tokens/{id2}

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_DELETE__api_v1_admin_tenants_id_api_tokens_id2_
delete:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_DELETE__api_v1_admin_tenants_id_api_tokens_id2_
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/memory/refine

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_memory_refine
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_memory_refine
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/runtimes/register

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_runtimes_register
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_runtimes_register
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/runtimes/heartbeat

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_runtimes_heartbeat
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_runtimes_heartbeat
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/runtimes

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_runtimes
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_runtimes
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/kg/explore

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_kg_explore
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_kg_explore
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/kg/entity-documents

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_kg_entity_documents
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_kg_entity_documents
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/memory/store

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_memory_store
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_memory_store
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/memory/confirm-sample

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_memory_confirm_sample
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_memory_confirm_sample
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/tenant/trust-summary

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_tenant_trust_summary
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_tenant_trust_summary
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/tenant/perf-summary

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_tenant_perf_summary
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_tenant_perf_summary
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/tenant/impact

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_tenant_impact
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_tenant_impact
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/users/resolve-caller

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_users_resolve_caller
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_users_resolve_caller
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/users/channel-identities

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_users_channel_identities
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_users_channel_identities
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/users/channel-identities

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_users_channel_identities
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_users_channel_identities
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/lessons

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_lessons
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_lessons
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/lessons/record

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_lessons_record
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_lessons_record
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/lessons/feedback

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_lessons_feedback
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_lessons_feedback
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/arcs

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_arcs
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_arcs
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/arcs

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_arcs
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_arcs
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/keyed-facts/as-of

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_keyed_facts_as_of
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_keyed_facts_as_of
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/keyed-facts

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_keyed_facts
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_keyed_facts
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/keyed-facts/correct

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_keyed_facts_correct
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_keyed_facts_correct
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/memory/prepare

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_memory_prepare
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_memory_prepare
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/kg/quarantine

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_kg_quarantine
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_kg_quarantine
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/kg/entity-resolve/report

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_kg_entity_resolve_report
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_kg_entity_resolve_report
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/kg/rag-retrieve

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_kg_rag_retrieve
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_kg_rag_retrieve
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/usage/answers

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_usage_answers
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_usage_answers
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/credits/summary

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_credits_summary
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_credits_summary
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/session-bootstrap

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_session_bootstrap
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_session_bootstrap
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/decisions

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_decisions
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_decisions
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/decisions

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_decisions
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_decisions
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/decisions/relations

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_decisions_relations
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_decisions_relations
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/decisions/chain

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_decisions_chain
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_decisions_chain
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/decisions/similar

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_decisions_similar
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_decisions_similar
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/decisions/impact

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_decisions_impact
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_decisions_impact
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/provenance

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_provenance
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_provenance
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/provenance/lineage

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_provenance_lineage
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_provenance_lineage
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/provenance/export

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_provenance_export
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_provenance_export
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/provenance/verify

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_provenance_verify
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_provenance_verify
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/conflicts/detect

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_conflicts_detect
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_conflicts_detect
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/fact-conflicts

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_fact_conflicts
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_fact_conflicts
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/conflicts/resolve

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_conflicts_resolve
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_conflicts_resolve
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

GET /api/v1/contradictions

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_GET__api_v1_contradictions
get:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_GET__api_v1_contradictions
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /api/v1/contradictions/{n}/resolve

Registered on this process; not yet in docs/reference/openapi.yaml

  • Auth: bearer
  • operationId: live_POST__api_v1_contradictions_n_resolve
post:
  tags:
  - Runtime
  summary: Registered on this process; not yet in docs/reference/openapi.yaml
  operationId: live_POST__api_v1_contradictions_n_resolve
  x-valorbrain-live: true
  responses:
    '200':
      description: See the running handler

POST /search

Hybrid search (BM25 + vector + rerank) — Full hybrid search with optional HyDE expansion, self-correct retrieval, MMR diversity, and personalized graph ranking.

  • Auth: bearer
  • Params: None
  • Body: object( q* (string), collection (string), limit (integer), offset (integer), expand (boolean), mode (enum(auto, keyword, semantic, causal, hybrid)), diverse (boolean) )
  • operationId: search
post:
  operationId: search
  summary: Hybrid search (BM25 + vector + rerank)
  description: 'Full hybrid search with optional HyDE expansion, self-correct retrieval,
    MMR diversity, and personalized graph ranking.

    '
  tags:
  - Search
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - q
          properties:
            q:
              type: string
              description: Search query
            collection:
              type: string
              description: Filter to collection
            limit:
              type: integer
              default: 10
            offset:
              type: integer
              default: 0
            expand:
              type: boolean
              description: Force HyDE expansion on/off
            mode:
              type: string
              enum:
              - auto
              - keyword
              - semantic
              - causal
              - hybrid
            diverse:
              type: boolean
              default: true
              description: Apply MMR diversity filter
  responses:
    '200':
      description: Search results
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'
              query:
                type: string
              mode:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /search/temporal

Temporal search with time-aware filtering

  • Auth: bearer
  • Params: None
  • Body: object( q* (string), collection (string), limit (integer), from (string), to (string) )
  • operationId: temporalSearch
post:
  operationId: temporalSearch
  summary: Temporal search with time-aware filtering
  tags:
  - Search
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - q
          properties:
            q:
              type: string
            collection:
              type: string
            limit:
              type: integer
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
  responses:
    '200':
      description: Temporally filtered results
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /search/hierarchical

Hierarchical search across memory layers

  • Auth: bearer
  • Params: None
  • Body: object( q* (string), limit (integer) )
  • operationId: hierarchicalSearch
post:
  operationId: hierarchicalSearch
  summary: Hierarchical search across memory layers
  tags:
  - Search
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - q
          properties:
            q:
              type: string
            limit:
              type: integer
  responses:
    '200':
      description: Hierarchical results
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /retrieve

Unified retrieval with auto-routing — Auto-classifies query intent and routes to optimal search backend.

  • Auth: bearer
  • Params: None
  • Body: object( q* (string), mode (enum(auto, keyword, semantic, causal, timeline, discovery, complex, hybrid)), limit (integer), collection (string) )
  • operationId: retrieve
post:
  operationId: retrieve
  summary: Unified retrieval with auto-routing
  description: Auto-classifies query intent and routes to optimal search backend.
  tags:
  - Search
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - q
          properties:
            q:
              type: string
            mode:
              type: string
              enum:
              - auto
              - keyword
              - semantic
              - causal
              - timeline
              - discovery
              - complex
              - hybrid
            limit:
              type: integer
            collection:
              type: string
  responses:
    '200':
      description: Retrieved results
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/components/schemas/SearchResult'
              mode:
                type: string
    '401':
      $ref: '#/components/responses/Unauthorized'

Users

GET /api/v1/users

List users in tenant

  • Auth: bearer
  • Params: None
  • operationId: listUsers
get:
  operationId: listUsers
  summary: List users in tenant
  tags:
  - Users
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: User list
      content:
        application/json:
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/users

Create a user

  • Auth: bearer
  • Params: None
  • Body: object( email* (string), name (string), role (string) )
  • operationId: createUser
post:
  operationId: createUser
  summary: Create a user
  tags:
  - Users
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
          - email
          properties:
            email:
              type: string
              format: email
            name:
              type: string
            role:
              type: string
  responses:
    '200':
      description: User created
      content:
        application/json:
          schema:
            type: object
    '400':
      $ref: '#/components/responses/BadRequest'
    '401':
      $ref: '#/components/responses/Unauthorized'

PUT /api/v1/users/{userId}

Update a user

  • Auth: bearer
  • Params: None, userId*
  • Body: object( name (string), role (string), metadata (object( )) )
  • operationId: updateUser
put:
  operationId: updateUser
  summary: Update a user
  tags:
  - Users
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  - name: userId
    in: path
    required: true
    schema:
      type: string
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            name:
              type: string
            role:
              type: string
            metadata:
              type: object
  responses:
    '200':
      description: User updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'
    '404':
      $ref: '#/components/responses/NotFound'

Workspace

GET /api/v1/workspace/focus

List current workspace focus items

  • Auth: bearer
  • Params: None
  • operationId: listFocus
get:
  operationId: listFocus
  summary: List current workspace focus items
  tags:
  - Workspace
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Focus items
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

POST /api/v1/workspace/focus

Set workspace focus

  • Auth: bearer
  • Params: None
  • Body: object( items (array[object( )]) )
  • operationId: setFocus
post:
  operationId: setFocus
  summary: Set workspace focus
  tags:
  - Workspace
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            items:
              type: array
              items:
                type: object
  responses:
    '200':
      description: Focus updated
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/workspace/sessions

List workspace sessions

  • Auth: bearer
  • Params: None
  • operationId: listWorkspaceSessions
get:
  operationId: listWorkspaceSessions
  summary: List workspace sessions
  tags:
  - Workspace
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Session list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/workspace/handoffs

List workspace handoffs

  • Auth: bearer
  • Params: None
  • operationId: listHandoffs
get:
  operationId: listHandoffs
  summary: List workspace handoffs
  tags:
  - Workspace
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Handoff list
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

GET /api/v1/workspace/state

Get workspace state document

  • Auth: bearer
  • Params: None
  • operationId: getWorkspaceState
get:
  operationId: getWorkspaceState
  summary: Get workspace state document
  tags:
  - Workspace
  parameters:
  - $ref: '#/components/parameters/TenantIdHeader'
  responses:
    '200':
      description: Workspace state
      content:
        application/json:
          schema:
            type: object
    '401':
      $ref: '#/components/responses/Unauthorized'

MCP tool schemas (generated)

registerTool() metadata from src/mcp-tools.ts, rebuilt with the docs.

Guides

Short walks that match commands the published CLI actually runs.

On this page

AdminPOST /api/v1/admin/tenantsPOST /api/v1/admin/tenants/{tenantId}/usersDELETE /api/v1/admin/tenants/{tenantId}GET /api/v1/admin/errorsPOST /api/v1/admin/errors/{errorId}/resolveGET /api/v1/admin/test-errorPOST /admin/l0-l1/runAgentsPOST /api/v1/agents/signupPOST /api/v1/agents/identifyPOST /api/v1/agents/claimPOST /api/v1/agents/claim/verifyAskPOST /askGET /api/v1/tracesBillingGET /api/v1/credits/balanceGET /api/v1/credits/transactionsPOST /api/v1/credits/grantGET /api/v1/pricing/actionsPUT /api/v1/pricing/actions/{action}GET /api/v1/plansGET /api/v1/subscriptionPUT /api/v1/subscriptionPOST /api/v1/subscription/grantPOST /api/v1/billing/events/applyGET /api/v1/billing/eventsCanonicalPOST /api/v1/documents/{id}/canonicalPOST /api/v1/documents/{id}/suggest-filtersPOST /api/v1/documents/{id}/probesGET /api/v1/conflictsGET /api/v1/proposalsPOST /api/v1/proposals/{id}/pickPOST /api/v1/proposals/{id}/resolveGET /api/v1/probesPOST /api/v1/canonical/runGET /api/v1/canonical/sourcesDocumentsPOST /documentsGET /documentsGET /documents/{id}PATCH /documents/{id}/visibilityPOST /documents/{id}/pinPOST /documents/{id}/snoozePOST /documents/{id}/forgetPOST /documents/{id}/feedbackDELETE /documents/purgeGET /timeline/{id}GET /sessionsGET /collectionsGET /profileGET /exportEntityGET /api/v1/entities/{name}/cardPOST /api/v1/entities/{name}/cardPOST /api/v1/triplesFoundationsGET /foundationsGET /api/v1/statePOST /api/v1/foundationsPUT /api/v1/foundations/{id}DELETE /api/v1/foundations/{id}POST /api/v1/foundations/{id}/promoteGraphGET /graph/causal/{id}GET /graph/similar/{id}GET /graph/evolution/{id}HealthGET /healthzGET /healthGET /health/deepGET /stateGET /statsGET /reports/memoryGET /openapi.jsonIdentityGET /api/v1/identityPUT /api/v1/identityLifecycleGET /lifecycle/statusPOST /lifecycle/sweepPOST /lifecycle/restoreMCP TokensGET /api/v1/mcp/tokensPOST /api/v1/mcp/tokensGET /api/v1/mcp/tokens/{tokenId}PUT /api/v1/mcp/tokens/{tokenId}DELETE /api/v1/mcp/tokens/{tokenId}MaintenancePOST /reindexPOST /graphs/buildGET /api/v1/collection-settingsGET /api/v1/collection-settings/reindexPOST /api/v1/collection-settings/reindexGET /api/v1/collection-settings/{collection}PUT /api/v1/collection-settings/{collection}DELETE /api/v1/collection-settings/{collection}POST /generateGET /skillsPOST /skillsGET /skills/{skillId}GET /setup/instructionsOAuthGET /.well-known/oauth-authorization-serverGET /.well-known/oauth-protected-resourcePOST /oauth/registerGET /oauth/authorizeGET /oauth/consentPOST /oauth/consentPOST /oauth/tokenPOST /oauth/revokeObservabilityGET /metricsGET /api/v1/trajectoriesGET /api/v1/roiPOST /api/v1/digest/sendGET /api/v1/featuresPOST /api/v1/featuresGET /api/v1/configPUT /api/v1/config/{key}GET /api/v1/criteriaPUT /api/v1/criteriaPOST /api/v1/benchmark/runGET /api/v1/benchmark/runsGET /api/v1/benchmark/comparePOST /api/v1/memory/recallPOST /api/v1/memory/usedGET /api/v1/tenant/value-summaryGET /api/v1/memory/healthPOST /api/v1/privacy/previewPOST /api/v1/privacy/sanitizePOST /api/v1/privacy/restoreGET /api/v1/foresightsPOST /api/v1/foresights/sweepGET /api/v1/foresights/{id}PATCH /api/v1/foresights/{id}DELETE /api/v1/foresights/{id}RuntimePATCH /api/v1/entities/{name}/cardDELETE /api/v1/entities/{name}/cardGET /openapi.yamlGET /health/adminGET /reports/usageGET /api/v1/memory/team-activityGET /dashboardGET /memory-mapGET /api/v1/knowledge-gapsPOST /api/v1/knowledge-gaps/{id}/resolvePOST /conversationsGET /contradictionsGET /documents/changesGET /documents/{id}/chainPATCH /documents/{id}/veracityPATCH /api/v1/documents/{id}/veracityPATCH /documents/veracity/bulkPATCH /api/v1/documents/veracity/bulkGET /collections/healthPOST /collections/{id}/lifecycleGET /api/v1/memory/working-contextGET /memory/working-contextGET /api/v1/scratchpadPUT /api/v1/scratchpadPOST /api/v1/scratchpadDELETE /api/v1/scratchpadGET /scratchpadPUT /scratchpadPOST /scratchpadDELETE /scratchpadGET /setup/artifactsGET /api/v1/entity-cardsGET /api/v1/pinsPOST /api/v1/pinsGET /api/v1/pins/{id}PATCH /api/v1/pins/{id}DELETE /api/v1/pins/{id}POST /api/v1/session-handoffsGET /api/v1/session-handoffsGET /api/v1/team/membersPOST /api/v1/team/messagesGET /api/v1/team/inboxPOST /api/v1/team/handoffsGET /api/v1/team/handoffsGET /api/v1/team/briefingGET /api/v1/team/streamGET /api/v1/memory/episodesGET /api/v1/memory/episodes/{id}GET /admin/queuesPOST /admin/queuesPOST /api/v1/admin/tenants/{id}/api-tokensGET /api/v1/admin/tenants/{id}/api-tokensDELETE /api/v1/admin/tenants/{id}/api-tokens/{id2}POST /api/v1/memory/refinePOST /api/v1/runtimes/registerPOST /api/v1/runtimes/heartbeatGET /api/v1/runtimesGET /api/v1/kg/exploreGET /api/v1/kg/entity-documentsPOST /api/v1/memory/storeGET /api/v1/memory/confirm-sampleGET /api/v1/tenant/trust-summaryGET /api/v1/tenant/perf-summaryGET /api/v1/tenant/impactPOST /api/v1/users/resolve-callerGET /api/v1/users/channel-identitiesPOST /api/v1/users/channel-identitiesGET /api/v1/lessonsPOST /api/v1/lessons/recordPOST /api/v1/lessons/feedbackGET /api/v1/arcsPOST /api/v1/arcsGET /api/v1/keyed-facts/as-ofPOST /api/v1/keyed-factsPOST /api/v1/keyed-facts/correctPOST /api/v1/memory/prepareGET /api/v1/kg/quarantineGET /api/v1/kg/entity-resolve/reportPOST /api/v1/kg/rag-retrieveGET /api/v1/usage/answersGET /api/v1/credits/summaryPOST /api/v1/session-bootstrapPOST /api/v1/decisionsGET /api/v1/decisionsPOST /api/v1/decisions/relationsGET /api/v1/decisions/chainGET /api/v1/decisions/similarGET /api/v1/decisions/impactPOST /api/v1/provenanceGET /api/v1/provenance/lineageGET /api/v1/provenance/exportGET /api/v1/provenance/verifyPOST /api/v1/conflicts/detectGET /api/v1/fact-conflictsPOST /api/v1/conflicts/resolveGET /api/v1/contradictionsPOST /api/v1/contradictions/{n}/resolveSearchPOST /searchPOST /search/temporalPOST /search/hierarchicalPOST /retrieveUsersGET /api/v1/usersPOST /api/v1/usersPUT /api/v1/users/{userId}WorkspaceGET /api/v1/workspace/focusPOST /api/v1/workspace/focusGET /api/v1/workspace/sessionsGET /api/v1/workspace/handoffsGET /api/v1/workspace/state