Mnemom Checkpoints API

Integrity checkpoints and proof artifacts.

GitHub OpenAPI

Operations 6

GET /agents/{agent_id}/checkpoints Paginated integrity checkpoints #
GET /agents/{agent_id}/checkpoints/{checkpoint_id} Get single checkpoint #
GET /agents/{agent_id}/failover-events Paginated model-failover events #
POST /agents/{agent_id}/reverify Re-verify AAP traces against updated card #
POST /agents/{agent_id}/reverify/aip Re-evaluate AIP checkpoints against updated card #
GET /agents/{agent_id}/timeline Unified dual-rail AIP + AAP timeline #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/mnemom-ai:mnemom-ai-checkpoints-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mnemom-ai-checkpoints-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Mnemom Checkpoints API
  description: Trust infrastructure for AI agents. Transparent alignment verification, behavioral drift detection, and accountability primitives.
  version: 1.0.0
  contact:
    name: Mnemom
    url: https://mnemom.ai
    email: support@mnemom.ai
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.mnemom.ai/v1
  description: Production
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Checkpoints
  description: Integrity checkpoints and proof artifacts.
paths:
  /agents/{agent_id}/checkpoints:
    get:
      operationId: listCheckpoints
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      - CookieAuth: []
      summary: Paginated integrity checkpoints
      tags:
      - Checkpoints
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 1000
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: verdict
        in: query
        schema:
          type: string
          enum:
          - clear
          - review_needed
          - boundary_violation
          - unverified
          - unanalyzed
      - name: session_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated checkpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkpoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/Checkpoint'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /agents/{agent_id}/checkpoints/{checkpoint_id}:
    get:
      operationId: getCheckpoint
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      - CookieAuth: []
      summary: Get single checkpoint
      description: 'Authorization: authentication is required (401 without credentials), and the caller must be an `owner`, `admin` or `member` of the organization that owns `agent_id` — checkpoint telemetry is member-only; there is no anonymous read. `checkpoint_id` is queried together with `agent_id`. A checkpoint under an agent the caller cannot access (the caller is not in the agent''s organization, or the agent does not exist) returns the same 404 as a checkpoint that does not exist, as does one belonging to a different agent — never another tenant''s data. A `viewer` or `auditor` of the agent''s own organization gets 403: they can already see the agent exists.'
      tags:
      - Checkpoints
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: checkpoint_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Checkpoint details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Checkpoint'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /agents/{agent_id}/failover-events:
    get:
      operationId: listFailoverEvents
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      - CookieAuth: []
      summary: Paginated model-failover events
      description: 'Reads `model_failover_events`: rows recorded at checkpoint-write time whenever the (provider, model) reported on a checkpoint differs from the immediately preceding checkpoint in the same session. Each row is strictly an OBSERVED provider/model change — this API has no visibility into *why* the change happened, so `reason` is always null today. Same owner-scoped read gate as GET /v1/agents/{agent_id}/checkpoints (no new authorization surface).'
      tags:
      - Checkpoints
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 1000
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - name: from
        in: query
        description: ISO-8601 lower bound (inclusive) on detected_at.
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: ISO-8601 upper bound (inclusive) on detected_at.
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Paginated model-failover events
          content:
            application/json:
              schema:
                type: object
                properties:
                  failover_events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_id:
                          type: string
                        agent_id:
                          type: string
                        session_id:
                          type: string
                        from_provider:
                          type: string
                        from_model:
                          type: string
                        to_provider:
                          type: string
                        to_model:
                          type: string
                        triggering_checkpoint_id:
                          type:
                          - string
                          - 'null'
                        reason:
                          type:
                          - string
                          - 'null'
                        detected_at:
                          type: string
                          format: date-time
                        created_at:
                          type: string
                          format: date-time
                  limit:
                    type: integer
                  offset:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /agents/{agent_id}/reverify:
    post:
      operationId: reverifyTraces
      summary: Re-verify AAP traces against updated card
      description: Re-runs AAP structural verification of the agent's stored traces against its currently-active alignment card. **Paginated, and a single call is not a full re-verification:** at most 40 traces are processed per call (Cloudflare Workers subrequest limit). Use `has_more` / `next_offset` to walk the remainder — a caller that stops after one page leaves later traces carrying verdicts from the previous card. `complete` is true only when the pass reached the end of the agent's traces with no write errors; the reputation score is recomputed only on such a pass, and `reputation_recompute_skipped_reason` says why it was not.
      tags:
      - Checkpoints
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        schema:
          type: integer
          default: 40
          maximum: 40
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Re-verification results
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id:
                    type: string
                  card_id:
                    type: string
                  total_traces_in_batch:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  reverified:
                    type: integer
                  still_violating:
                    type: integer
                  now_clean:
                    type: integer
                  total_traces:
                    type:
                    - integer
                    - 'null'
                    description: Exact total number of traces stored for this agent, or null if the count could not be established. Null means coverage is UNKNOWN — not zero, and not complete.
                  traces_scanned:
                    type: integer
                    description: offset + rows processed in this call.
                  has_more:
                    type: boolean
                    description: True if traces beyond this page remain un-re-verified.
                  next_offset:
                    type:
                    - integer
                    - 'null'
                    description: Offset to pass to the next call, or null when there is no next page.
                  complete:
                    type: boolean
                    description: True only if this pass reached the end of the agent's traces with no write errors. False means the agent's history is NOT yet fully consistent with the current card.
                  reputation_recomputed:
                    type: boolean
                    description: Whether the agent's reputation score was recomputed. Only ever true on a complete pass that updated at least one trace.
                  reputation_recompute_skipped_reason:
                    type:
                    - string
                    - 'null'
                    enum:
                    - incomplete_pass
                    - trace_total_unknown
                    - write_errors_in_batch
                    - no_traces_updated
                    - recompute_failed
                    - null
                  errors:
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
  /agents/{agent_id}/reverify/aip:
    post:
      operationId: reverifyAipCheckpoints
      summary: Re-evaluate AIP checkpoints against updated card
      tags:
      - Checkpoints
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 20
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Re-evaluation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id:
                    type: string
                  card_id:
                    type: string
                  total_in_batch:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  re_evaluated:
                    type: integer
                  resolved_to_clear:
                    type: integer
                  kept_non_clear:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                  errors:
                    type:
                    - array
                    - 'null'
                    items:
                      type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /agents/{agent_id}/timeline:
    get:
      operationId: getTimeline
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      - CookieAuth: []
      summary: Unified dual-rail AIP + AAP timeline
      tags:
      - Checkpoints
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      responses:
        '200':
          description: Timeline events
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent_id:
                    type: string
                  events:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                  summary:
                    type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
components:
  responses:
    Conflict:
      description: Resource conflict — the request cannot proceed because of a current state conflict (e.g., resource already exists, version mismatch, in-flight idempotency key with a different body).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGateway:
      description: An upstream dependency returned an invalid response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          description: Requests permitted per window.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the current window (0 on a 429).
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Reset:
          description: Unix epoch seconds at which the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Checkpoint:
      type: object
      properties:
        checkpoint_id:
          type: string
        request_id:
          type: string
          nullable: true
          description: The gateway's per-proxied-request id (ADR-065 mnemom_request_id), when the gateway wrote this checkpoint with a request-scoped logger. Null on rows written before migration 548 or by a caller with no request context.
        agent_id:
          type: string
        card_id:
          type: string
        session_id:
          type: string
        timestamp:
          type: string
          format: date-time
        thinking_block_hash:
          type: string
        provider:
          type: string
        model:
          type: string
        verdict:
          type: string
          enum:
          - clear
          - review_needed
          - boundary_violation
          - unverified
          - unanalyzed
          description: '`unverified`: analysis was supposed to run but did not complete. `unanalyzed`: the agent''s integrity_mode is off (AIP off), so the turn was recorded but never analysed (migration 518). Neither is a clean integrity pass.'
        concerns:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              severity:
                type: string
              description:
                type: string
              evidence:
                type: string
        reasoning_summary:
          type: string
        conscience_context:
          type: object
        window_position:
          type: object
          properties:
            index:
              type: integer
            window_size:
              type: integer
        analysis_metadata:
          type: object
        linked_trace_id:
          type:
          - string
          - 'null'
        re_evaluated_at:
          type:
          - string
          - 'null'
          format: date-time
        original_verdict:
          type:
          - string
          - 'null'
    Error:
      type: object
      description: Canonical error envelope (ADR-API-001 conv 1). `error` is always an object — never a bare string. Every 4xx/5xx response across the API conforms to this shape; the runtime helper is `src/http-errors.ts::buildErrorBody`.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: 'Stable, machine-matchable failure identifier (lowercase snake_case). Clients may branch on this; the string is part of the contract.


                **Status-class defaults** — emitted when no caller code is supplied (`errorCodeForStatus(status)`): `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `conflict` (409), `gone` (410), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `unprocessable_entity` (422), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Fallback `error` for unmapped statuses.


                **Caller-supplied codes** — handlers may pass an explicit `code` for a specific failure class. Examples: `agent_not_found`, `invalid_hash_proof`, `already_linked`, `idempotency_conflict`, `feature_gated`, `schema_validation_failed`, `no_token`, `bad_canonical_payload`.


                **Care-framed sub-resource codes** — the cards-as-primitive surface passes its stable care code-string straight through as `error.code`. Examples: `if_match_absent`, `if_match_stale`, `if_match_malformed`, `primitive_validation_failed`.'
            message:
              type: string
              description: Human-readable, care-framed explanation of the failure.
            details:
              description: 'Optional structured context for the failure (any JSON value: object, array, or primitive). Common shapes: validation findings list, idempotency-conflict diff, `{presented_etag, current_etag}` on a stale `If-Match`, etc. Mirrors the helper''s `details?: unknown`.'
  parameters:
    AgentId:
      name: agent_id
      in: path
      required: true
      schema:
        type: string
      description: Agent identifier (e.g. smolt-abc123)
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT token in Authorization: Bearer header'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Api-Key
      description: Mnemom API key (mnm_... format)
    ServiceRole:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase service role bearer JWT. Used by /blog admin operations that talk directly to Supabase. NOT used by /internal/* or /v1/arena/internal/* — those use the custom-header schemes below.
    InternalKeyAuth:
      type: apiKey
      in: header
      name: X-Internal-Key
      description: Internal service-to-service shared secret, timing-safe compared against INTERNAL_API_KEY. Used by /internal/* gateway routes (compose, agents, webhooks emit).
    ServiceKeyAuth:
      type: apiKey
      in: header
      name: X-Service-Key
      description: Service-to-service shared secret, timing-safe compared against MNEMOM_SERVICE_KEY. Used by /v1/arena/internal/*, /v1/on-chain/*, and the /v1/internal/* readers consumed by the reputation cron.
    CoherenceTokenAuth:
      type: http
      scheme: bearer
      description: Per-cell coherence bearer token. Provisioned in 1Password vault `mnemom-coherence` (one item per receiver). Value compared against COHERENCE_<NAME>_SERVICE_TOKEN_EXPECTED. Used by /v1/internal/coherence/* and /v1/internal/governance/dispatch.
    ArenaCandidateTokenAuth:
      type: http
      scheme: bearer
      description: Dedicated arena writer token (ADR-004 §"Arena dedicated writer token"). Compared against ARENA_RECIPE_CANDIDATE_TOKEN. The token's only capability is writing recipe candidates with writer_identity='arena-bypass' (stamped server-side). Used by POST /v1/internal/recipe-candidates.
    CustomerVoiceTokenAuth:
      type: http
      scheme: bearer
      description: Customer Voice API bearer token. Timing-safe compared against CUSTOMER_VOICE_API_TOKEN. Grants access to all /v1/internal/feedback/* endpoints (MNE-1876). No customer-facing or reporter-read capability.
    CookieAuth:
      type: apiKey
      in: cookie
      name: mnemom_session
      description: 'HttpOnly, Secure, SameSite=Lax cookie issued by /v1/auth/sign-in (or the SSO / email-callback flows). The value is an AES-256-GCM-encrypted blob of {access_token, refresh_token, issued_at, auth_method}. Browser clients include this automatically with `credentials: "include"`.'
    LicenseJwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: License JWT (HS256, HMAC-signed with LICENSE_SIGNING_SECRET). Used by self-hosted deployment instances to authenticate `/v1/deployments/heartbeat`. Not interchangeable with the Supabase user JWT.
    AgentAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Agent-Proof
      description: 'Agent possession proof: the full SHA-256 hex digest of `${apiKey}|${agentName}` (or `${apiKey}` for an unnamed singleton agent) — the same `hash_proof` primitive used by POST /v1/agents claim, link-agent, and verify-binding. The server resolves the agent by `agent_hash = proof[:16]`. The agent''s *own* identity (ADR-API-001 third auth class) — distinct from ApiKeyAuth (`X-Mnemom-Api-Key`, which resolves a user/account, not an agent).'