Mnemom Traces API

AP-Trace artifacts and queries.

GitHub OpenAPI

Operations 3

GET /agents/{agent_id}/traces Get traces for agent (AAP query alias) #
GET /traces Query traces with filters #
GET /traces/{trace_id} Get single trace by ID #

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-traces-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-traces-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Mnemom Traces 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: Traces
  description: AP-Trace artifacts and queries.
paths:
  /agents/{agent_id}/traces:
    get:
      operationId: getAgentTraces
      summary: Get traces for agent (AAP query alias)
      tags:
      - Traces
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 1000
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      responses:
        '200':
          description: List of traces
          content:
            application/json:
              schema:
                type: object
                properties:
                  traces:
                    type: array
                    items:
                      $ref: '#/components/schemas/APTrace'
                  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'
  /traces:
    get:
      operationId: queryTraces
      summary: Query traces with filters
      tags:
      - Traces
      security:
      - {}
      - ApiKeyAuth: []
      - BearerAuth: []
      - CookieAuth: []
      parameters:
      - name: agent_id
        in: query
        schema:
          type: string
        description: Agent identifier whose traces to return (e.g. smolt-abc123). Required — requests without it are rejected to prevent cross-agent listing.
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 1000
        description: Maximum number of traces to return, most recent first (1–1000, default 50).
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Number of traces to skip from the start of the result set, for pagination (default 0).
      responses:
        '200':
          description: Filtered list of traces
          content:
            application/json:
              schema:
                type: object
                properties:
                  traces:
                    type: array
                    items:
                      $ref: '#/components/schemas/APTrace'
                  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'
        '502':
          $ref: '#/components/responses/BadGateway'
  /traces/{trace_id}:
    get:
      operationId: getTrace
      summary: Get single trace by ID
      tags:
      - Traces
      security:
      - {}
      - ApiKeyAuth: []
      - BearerAuth: []
      - CookieAuth: []
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Trace details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APTrace'
        '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:
    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'
  parameters:
    AgentId:
      name: agent_id
      in: path
      required: true
      schema:
        type: string
      description: Agent identifier (e.g. smolt-abc123)
  schemas:
    APTrace:
      type: object
      properties:
        trace_id:
          type: string
        agent_id:
          type: string
        timestamp:
          type: string
          format: date-time
        action:
          type:
          - object
          - 'null'
          description: Null only when the trace's stored evidence has expired under retention; `evidence.state` is then `expired` (MNE-7505).
          properties:
            type:
              type: string
            name:
              type: string
            category:
              type: string
              description: How the action relates to the autonomy envelope, as stored and as verification reads it. A turn with no tool call (plain model inference) is stored as `escalation_trigger` with `name` `inference`, so verification does not check it against `bounded_actions`; that value does not mean an escalation occurred. Use `display_category` for display.
            display_category:
              type: string
              description: 'Customer-facing label for `category`: `inference` for a turn with no tool call (stored `category` `escalation_trigger` with `name` `inference`), otherwise equal to `category`. Display only; verification uses `category`. Additive field (MNE-9764); absent on traces whose action has no `category`.'
        decision:
          type:
          - object
          - 'null'
          description: Null only when the trace's stored evidence has expired under retention; `evidence.state` is then `expired` (MNE-7505).
          properties:
            selected:
              type: string
            selection_reasoning:
              type: string
            values_applied:
              type: array
              items:
                type: string
            confidence:
              type:
              - number
              - 'null'
              description: 'On traces recorded by the Mnemom observer this is a thinking-length signal, not a calibrated probability: 0.9 when the turn''s captured thinking is longer than 500 characters, 0.6 when it is 500 characters or fewer, and 0.3 when no thinking was captured. It measures how much reasoning the model showed, not how likely the decision is to be correct.'
        verification:
          type:
          - object
          - 'null'
          properties:
            verified:
              type: boolean
            violations:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  severity:
                    type: string
                  description:
                    type: string
                additionalProperties: true
        created_at:
          type: string
          format: date-time
        evidence:
          type: object
          description: Present only when the trace's payload has expired under retention (MNE-7505). The trace row remains, and `action`, `decision`, `escalation` and `context` are null. Absent on every other trace.
          properties:
            state:
              type: string
              enum:
              - expired
          required:
          - state
    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`.'
  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).'