ContextDB Decisions API

openapi: 3.2.0
info:
  title: ContextDB Cloud data-plane Decisions API
  version: 1.0.0-alpha.1
  description: 'The ContextDB Cloud data plane (hosted alpha). Managed, decision-safe

    agent memory: remember with provenance, recall for grounding, and

    recall_for_action before consequential actions.


    Authentication: `Authorization: Bearer cdb_…` is a project-wide server

    credential. The key determines org and project; requests supply only

    `user_id`, which is a partition key, not end-user authentication.


    This surface is the complete alpha allowlist. Shipped `/v1/forget`

    supports scoped deletion of one memory, one stable entity-and-attribute

    slot, or one verified user partition. Partition erasure requires

    `erase_partition=true`, typed `confirmation` equal to `user_id`, and an

    `Idempotency-Key`. Scoped ID checks make a foreign memory ID

    indistinguishable from a missing one.


    `/mcp` is a Hosted Alpha stateless JSON-RPC 2.0 endpoint over Streamable

    HTTP. Trusted backends may use a project key. Marketplace clients use

    OAuth 2.1 authorization code with S256 PKCE, refresh-token rotation, and a

    server-bound user partition. It exposes tools only, with no sessions, SSE,

    resumability, or server-initiated messages.


    Not production-ready. No SLA.'
  contact:
    name: Atoms AI
    email: gaurav@saaslabs.co
  license:
    name: Proprietary, hosted alpha
    identifier: LicenseRef-Proprietary
servers:
- url: https://api.contextdb.ai
  description: Hosted alpha
security:
- ProjectKey: []
tags:
- name: decisions
  description: Check trusted memories and resolve explicit confirmations
paths:
  /v1/recall_for_action:
    post:
      tags:
      - decisions
      summary: Trusted, action-relevant memory only
      description: 'An advisory pre-action evaluation. Records and returns a durable

        `decision_id`, explicit `act` / `ask` / `abstain` outcome, trusted

        memories, and pending confirmation IDs. The host uses the decision ID

        to report its terminal outcome through `/v1/receipts`, and must enforce

        the result itself. Confirmation is one policy signal, not the only path

        to `act`, and it does not prove objective truth.'
      operationId: recallForAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecallForActionRequest'
      responses:
        '200':
          description: Durable action decision and its receipt target
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallForActionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NotEntitled'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/StoreUnavailable'
  /v1/confirm:
    post:
      tags:
      - decisions
      summary: Graduate a pending memory via explicit confirmation
      description: 'Records the authenticated caller''s project-credential context against

        one scoped pending memory and updates its confirmation state. API and

        MCP authentication identify the project credential, not the end user

        named by `user_id`; the customer host authenticates that person and

        retains any end-user attestation. Call `recall_for_action` again after

        confirmation because policy still determines `act`, `ask`, or

        `abstain`. Confirmation does not prove objective truth. Partition

        ownership is enforced at the store layer: a memory ID outside the

        caller''s org/project/user scope returns 404, indistinguishable from a

        missing one.'
      operationId: confirm
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmRequest'
      responses:
        '200':
          description: The confirmed memory
          headers:
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NotEntitled'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/StoreUnavailable'
  /v1/receipts:
    post:
      tags:
      - decisions
      summary: Report what the host did after an action decision
      description: 'Attaches one terminal, host-reported execution receipt to the durable

        `decision_id` returned by `recall_for_action`. ContextDB records the

        report but does not inspect the downstream system. Structured fields

        only: free-text payloads are not accepted. Acting after an `ask` or

        `abstain` decision is retained with `policy_alignment=violated`.'
      operationId: recordExecutionReceipt
      parameters:
      - $ref: '#/components/parameters/RequiredIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionReceiptRequest'
      responses:
        '200':
          description: The terminal execution receipt
          headers:
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionReceiptResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NotEntitled'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/StoreUnavailable'
  /v1/pending_confirmations:
    get:
      tags:
      - decisions
      summary: Facts waiting on a yes (query string)
      operationId: pendingConfirmationsGet
      parameters:
      - name: user_id
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/UserId'
      responses:
        '200':
          description: Memories pending confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingConfirmationsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NotEntitled'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/StoreUnavailable'
    post:
      tags:
      - decisions
      summary: Facts waiting on a yes (JSON body)
      operationId: pendingConfirmationsPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PendingConfirmationsRequest'
      responses:
        '200':
          description: Memories pending confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingConfirmationsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NotEntitled'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/StoreUnavailable'
components:
  schemas:
    ExecutionReceiptRequest:
      type: object
      required:
      - user_id
      - decision_id
      - action_name
      - status
      properties:
        user_id:
          $ref: '#/components/schemas/UserId'
        decision_id:
          type: string
          format: uuid
        action_name:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9._:\-]{0,127}$
          description: Stable action category, such as appointment.book
        status:
          type: string
          enum:
          - succeeded
          - failed
          - skipped
        external_ref:
          type: string
          pattern: ^[A-Za-z0-9._:\-]{1,128}$
          description: Optional opaque non-PII identifier in the downstream system
        error_code:
          type: string
          pattern: ^[A-Za-z0-9._:\-]{1,128}$
          description: Structured failure code; allowed only when status is failed
      additionalProperties: false
    PendingConfirmationsResponse:
      type: object
      required:
      - memories
      properties:
        memories:
          type: array
          items:
            $ref: '#/components/schemas/Memory'
      additionalProperties: false
    RecallForActionResponse:
      type: object
      required:
      - decision_id
      - outcome
      - memories
      - pending_confirmation_ids
      properties:
        decision_id:
          type: string
          format: uuid
          description: Durable receipt target for this action evaluation
        outcome:
          type: string
          enum:
          - act
          - ask
          - abstain
        memories:
          type: array
          items:
            $ref: '#/components/schemas/Memory'
          description: Trusted memories; populated only for an act outcome
        pending_confirmation_ids:
          type: array
          items:
            type: string
          description: Memories that caused an ask outcome
      additionalProperties: false
    RecallForActionRequest:
      type: object
      required:
      - user_id
      - query
      properties:
        user_id:
          $ref: '#/components/schemas/UserId'
        query:
          type: string
          minLength: 1
          maxLength: 2000
        top_k:
          type: integer
          minimum: 1
          maximum: 50
          default: 5
        entity:
          type: string
          maxLength: 200
        attribute:
          type: string
          maxLength: 200
      additionalProperties: false
      description: Pass the entity and attribute the action needs, for example user and email, so only current memory in that slot can yield act or ask. Without them, any trusted memory the query retrieves yields act, whether or not it answers the request. entity and attribute must be set together (400 otherwise).
    EpistemicSource:
      type: string
      enum:
      - user_stated
      - agent_inferred
      - third_party
      description: Who vouches for the claim. Required on writes.
    ConfirmResponse:
      type: object
      required:
      - memory
      - memory_version
      - primary_wal_lsn
      properties:
        memory:
          $ref: '#/components/schemas/Memory'
        memory_version:
          $ref: '#/components/schemas/MemoryVersion'
        primary_wal_lsn:
          $ref: '#/components/schemas/PrimaryWalLsn'
      additionalProperties: false
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable message; never a stack trace
        request_id:
          type:
          - string
          - 'null'
      additionalProperties: false
    PrimaryWalLsn:
      type:
      - string
      - 'null'
      pattern: ^[0-9A-F]+/[0-9A-F]+$
      description: Primary PostgreSQL WAL position observed after commit.
    ConfirmRequest:
      type: object
      required:
      - user_id
      - memory_id
      properties:
        user_id:
          $ref: '#/components/schemas/UserId'
        memory_id:
          type: string
          minLength: 1
          maxLength: 128
      additionalProperties: false
    UserId:
      type: string
      pattern: ^[A-Za-z0-9._:@+\-]{1,128}$
      description: End-user memory partition key. Not an identity assertion.
    MemoryVersion:
      type: integer
      minimum: 0
      description: Monotonic consistency version within one organization/project.
    ExecutionReceipt:
      type: object
      required:
      - id
      - decision_id
      - action_name
      - status
      - policy_alignment
      - external_ref
      - error_code
      - request_id
      - created_at
      properties:
        id:
          type: string
          format: uuid
        decision_id:
          type: string
          format: uuid
        action_name:
          type: string
        status:
          type: string
          enum:
          - succeeded
          - failed
          - skipped
        policy_alignment:
          type: string
          enum:
          - aligned
          - violated
          description: Violated when the host attempted execution after ask or abstain
        external_ref:
          type:
          - string
          - 'null'
        error_code:
          type:
          - string
          - 'null'
        request_id:
          type: string
        created_at:
          type: string
          format: date-time
      additionalProperties: false
    ExecutionReceiptResponse:
      type: object
      required:
      - decision_id
      - outcome
      - receipt
      properties:
        decision_id:
          type: string
          format: uuid
        outcome:
          type: string
          enum:
          - act
          - ask
          - abstain
        receipt:
          $ref: '#/components/schemas/ExecutionReceipt'
      additionalProperties: false
    Memory:
      type: object
      required:
      - id
      - content
      - user_id
      - epistemic_source
      - confidence
      - corroboration_count
      - action_relevant
      - requires_confirmation
      - confirmed
      - independent_corroboration
      - injection_suspect
      - entity_key
      - attribute_key
      - valid_until
      - superseded_by
      properties:
        id:
          type: string
        content:
          type: string
          description: Stored content with PII redacted as `[TYPE]` placeholders
        user_id:
          type:
          - string
          - 'null'
        epistemic_source:
          $ref: '#/components/schemas/EpistemicSource'
        confidence:
          type: number
          minimum: 0
          maximum: 1
        corroboration_count:
          type: integer
          minimum: 0
        action_relevant:
          type: boolean
        requires_confirmation:
          type: boolean
        confirmed:
          type: boolean
        independent_corroboration:
          type: integer
          minimum: 0
        injection_suspect:
          type: boolean
        entity_key:
          type:
          - string
          - 'null'
        attribute_key:
          type:
          - string
          - 'null'
        valid_until:
          type:
          - string
          - 'null'
          format: date-time
        superseded_by:
          type:
          - string
          - 'null'
      additionalProperties: false
    PendingConfirmationsRequest:
      type: object
      required:
      - user_id
      properties:
        user_id:
          $ref: '#/components/schemas/UserId'
      additionalProperties: false
  responses:
    RateLimited:
      description: 'The client IP/project exceeded its request rate, or the project''s

        idempotency retention capacity is full until older keys expire.

        '
      headers:
        Retry-After:
          description: Seconds until a request is likely to be accepted
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          description: Sustained requests allowed per minute
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Remaining:
          description: Requests remaining in the current burst bucket
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Scope:
          description: Limiting identity (`ip` or `project`)
          schema:
            type: string
            enum:
            - ip
            - project
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Target not found in the caller's partition (or missing)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    StoreUnavailable:
      description: Memory or metadata store unreachable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthenticated:
      description: Missing, malformed, unknown, or revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    IdempotencyConflict:
      description: 'The key was reused with a different request, an identical request is

        still running, or a previous process ended with an ambiguous outcome.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Malformed request or failed validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: 'The decision already has a terminal receipt, or the Idempotency-Key

        conflicts with an earlier request.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotEntitled:
      description: Authenticated but not allowed (entitlement or billing state)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Project-scoped retry key (8-128 URL-safe characters). The same key and

        canonical payload replay the encrypted stored response. Reusing a key

        with a different route or payload returns 409. On extract_memories this

        applies only when mode is commit.

        '
      schema:
        type: string
        pattern: ^[A-Za-z0-9._:\-]{8,128}$
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: 'Stable project-scoped key for this logical mutation or job. Retrying

        with the same key and payload resolves to the original resource or

        response; reuse with a different payload returns 409.

        '
      schema:
        type: string
        pattern: ^[A-Za-z0-9._:\-]{8,128}$
  headers:
    IdempotencyReplayed:
      description: true when this response was replayed; false for the owner request
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
  securitySchemes:
    ProjectKey:
      type: http
      scheme: bearer
      description: Project-wide server credential (`cdb_…`). Never in browsers.
    McpOAuth:
      type: oauth2
      description: User-bound marketplace connector grant (`cmo_…`).
      flows:
        authorizationCode:
          authorizationUrl: https://app.contextdb.ai/oauth/authorize
          tokenUrl: https://api.contextdb.ai/oauth/token
          refreshUrl: https://api.contextdb.ai/oauth/token
          scopes:
            memory:read: Recall memory and evaluate evidence before actions
            memory:write: Remember, confirm, and forget memory
            offline_access: Rotate a refresh token for continued access