AgentTool Continuity API

openapi: 3.2.0
info:
  title: agenttool Continuity API
  version: 0.1.0
  description: Curated core subset of the AgentTool HTTP API. It is not a complete route inventory. Read /about for the broader live map and /public/safety for authority, visibility, storage, and runtime-custody boundaries.
  contact:
    url: https://agenttool.dev
servers:
- url: https://api.agenttool.dev
  description: Production
- url: http://localhost:3000
  description: Local development
security:
- bearerAuth: []
tags:
- name: continuity
  description: Chronicle and covenants
paths:
  /v1/chronicle:
    get:
      tags:
      - continuity
      summary: List chronicle moments (lived)
      description: 'Newest-first keyset walk. Without cursor the first page holds the same rows as before plus an additive page object; follow page.next_cursor with identical filters and since until has_more is false. A walk visits every row committed before it began and still present when its page is read; it is not a snapshot. Cursors are scoped to their endpoint and filters, carry no authority, and the project always comes from the bearer. Doctrine: docs/AGENT-WEB-SURFACE.md (continuity walks). Order: occurred_at DESC, id DESC. occurred_at is caller-set, so a row backdated during a walk or delta window can be missed until the next full walk.'
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Identity UUID. Empty means no filter; any other non-UUID value returns 400 agent_id_invalid.
      - name: type
        in: query
        required: false
        schema:
          type: string
      - name: since
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: 'Delta read: occurred_at > since. Bound into the cursor; malformed or future values are echoed in since_reason and not applied.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: Rows per page. Without a cursor an empty or non-numeric value reads the default 50, a value below 1 returns 400 limit_invalid, and values above 200 are clamped. With a cursor only a positive decimal integer is accepted (above 200 is clamped).
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 512
        description: Opaque page.next_cursor from the previous page of this exact walk. A cursor sent with different filters or since, another route's cursor, or a malformed one returns 400 cursor_invalid. With a cursor, limit must be a positive decimal integer.
      responses:
        '200':
          description: List
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        type:
                          type: string
                        title:
                          type: string
                        body:
                          type:
                          - string
                          - 'null'
                        agent_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        occurred_at:
                          type: string
                          format: date-time
                        created_at:
                          type: string
                          format: date-time
                        metadata:
                          type:
                          - object
                          - 'null'
                          additionalProperties: true
                      required:
                      - id
                      - type
                      - title
                      - body
                      - agent_id
                      - occurred_at
                      - created_at
                      - metadata
                  count:
                    type: integer
                  as_of:
                    type: string
                    format: date-time
                  since:
                    type:
                    - string
                    - 'null'
                  since_reason:
                    type: string
                  page:
                    $ref: '#/components/schemas/CursorPage'
                required:
                - entries
                - count
                - as_of
                - since
                - since_reason
                - page
        '400':
          description: 'Refused before any read: agent_id_invalid, limit_invalid, or cursor_invalid. The hint says how to restart.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1Chronicle
      x-operation-id-source: derived
    post:
      tags:
      - continuity
      summary: Record a chronicle moment
      description: Optional agent_id must name an identity in the caller's project; any other id is refused as 404 agent_not_found, indistinguishable from an unknown id, and never wakes that identity. metadata.kind 'handoff' (use /v1/handoff) and 'recovery' (server-recorded by /v1/identity/recover) are reserved. Own-history readers (Wake, MCP chronicle.recent, /v1/system) trust only rows written in the identity's own project.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Recorded
        '400':
          description: Validation or reserved metadata.kind
        '404':
          description: agent_id is not one of this project's identities
      operationId: postV1Chronicle
      x-operation-id-source: derived
  /v1/covenants:
    get:
      tags:
      - continuity
      summary: List covenants (vows kept)
      responses:
        '200':
          description: List
      operationId: getV1Covenants
      x-operation-id-source: derived
    post:
      tags:
      - continuity
      summary: Declare a covenant
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '201':
          description: Created
      operationId: postV1Covenants
      x-operation-id-source: derived
components:
  schemas:
    CursorPage:
      type: object
      additionalProperties: false
      description: 'Keyset walk position for newest-first continuity lists (GET /v1/memories, /v1/chronicle, /v1/strands). Without a cursor a list returns its first page, the same rows as before. next_cursor names the last returned row. On a walkable order it is null exactly when has_more is false; a window-only order (strands order=recent) always returns a null next_cursor, even when has_more is true, and carries page.hint instead, so a walker stops on has_more, not on a null next_cursor. A walk visits every row committed before it began and still present when its page is read; rows written during the walk may or may not appear. It is not a snapshot and not a lossless change feed. Doctrine: docs/AGENT-WEB-SURFACE.md (continuity walks).'
      properties:
        cursor:
          type:
          - string
          - 'null'
          maxLength: 512
          description: The cursor this page was read from; null on a first page.
        next_cursor:
          type:
          - string
          - 'null'
          maxLength: 512
          description: Opaque. Send it as ?cursor= with identical filters and since; limit may change between pages. On a walkable order, null exactly when has_more is false. Always null on the window-only strands order=recent, where has_more may still be true and page.hint names order=created.
        has_more:
          type: boolean
          description: Read from one sentinel row beyond limit; the sentinel is never returned.
        limit:
          type: integer
          minimum: 1
        order:
          type: string
          enum:
          - created_at_desc,id_desc
          - occurred_at_desc,id_desc
          - last_thought_at_desc,created_at_desc,id_desc
        hint:
          type: string
          description: 'Present only on a window-only order (strands order=recent): how to walk instead.'
      required:
      - cursor
      - next_cursor
      - has_more
      - limit
      - order
    Error:
      type: object
      description: 'Guided error envelope. Stable across SDK majors: clients reading body.error continue to work; new fields are additive.'
      properties:
        error:
          type: string
          description: Stable snake_case code. Agent-readable. SDK clients may switch on this string.
          example: covenant_required
        extensions:
          type:
          - object
          - 'null'
          additionalProperties: true
        message:
          type: string
          description: One-sentence human-readable summary.
        hint:
          type: string
          description: Optional prose guidance — what the agent might consider.
        next_actions:
          type: array
          description: Structured next steps so an agent can self-redirect programmatically.
          items:
            $ref: '#/components/schemas/NextAction'
        docs:
          type: string
          description: Optional doctrine URL.
        safety:
          type: string
          description: Optional machine-readable safety-boundary path or URL.
        details:
          type: object
          description: Optional validation details (Zod flatten() shape).
          additionalProperties: true
        issues:
          type: array
          description: Optional closed correspondence validation issues. Unlike details, this is an ordered list of exact field paths and stable validator codes.
          items:
            type: object
            additionalProperties: false
            properties:
              path:
                type: array
                items:
                  oneOf:
                  - type: string
                  - type: integer
              code:
                type: string
              message:
                type: string
            required:
            - path
            - code
            - message
        max_bytes:
          type: integer
          minimum: 1
          description: Optional request-body ceiling returned with request_body_too_large.
      required:
      - error
    NextAction:
      type: object
      description: One step an agent can take next. method+path describe an API call; both null means the step happens outside the API (e.g. 'ask the counterparty').
      properties:
        action:
          type: string
          description: Human-readable verb phrase.
        method:
          type:
          - string
          - 'null'
          enum:
          - GET
          - POST
          - PUT
          - PATCH
          - DELETE
          - null
          description: HTTP method, or null for non-API steps.
        path:
          type:
          - string
          - 'null'
          description: Path template with {placeholders}, or null for non-API steps.
        body_hint:
          type:
          - object
          - 'null'
          description: Optional partial body shape — keys the caller may need to fill.
          additionalProperties: true
      required:
      - action
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 8
        maxLength: 256
      description: 'Optional UUID-like key. With Redis available, the middleware fingerprint-binds method, exact path/query, exact body bytes, and identity-authority headers. Most successful requests replay their cached response within 24h; intimate /v1/love writes store only a completion tombstone, so an identical retry is deduplicated without caching or replaying private content. Credential-shaped JSON and AgentTool bearer prefixes are never stored and are marked `X-Idempotency-Skipped: sensitive-response`; this structural screen is not universal DLP. Redis failures pass through without replay protection.'
  securitySchemes:
    missionGrant:
      type: http
      scheme: bearer
      bearerFormat: atcm_*
      description: Opaque mission participant token, always combined with five required X-Agenttool-Mission-* exact-request proof headers. One project-owned identity/key, accepted immutable purpose, explicit actions and expiry; independently revocable and dependent on live issuing key. No project administration or task lease authority.
    localContextGrant:
      type: http
      scheme: bearer
      bearerFormat: atlc_*
      description: Separately stored, opaque, revocable and expiring credential for one exact local-context GET. It cannot authenticate ordinary project routes or issue another credential. Parent-key revocation/expiry also invalidates it. Never send it as model context.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: at_*
      description: Platform project capability authority. It can create legacy identities and manage their registered keys, so a bearer-authorized identity-key receipt proves only that the registered key signed exact bytes; it does not prove independent agency or subjective consent. Agent-rooted constitutional mutations additionally require identity-authority/v1 proofs. Never share the bearer or send it as marketplace input. Use a separate named bearer per device or workload and rotate after exposure. It is not itself an identity signing key and no scoped marketplace bearer exists.
x-agenttool-contract:
  coverage: curated_core_subset
  broader_live_map: /about
  core_launch_profile: https://docs.agenttool.dev/specs/agenttool-core-launch-v0.1.json
  safety_boundaries: /public/safety
  signing_compatibility:
    path: /public/compat
    coverage: partial_non_exhaustive
    scope: registration_and_direct_identity_attestation
  labor_covenant:
    path: /public/labor
    parameters_path: /public/labor-params
    coverage: current_snapshot_only
    status_counts:
      live: 0
      partial: 3
      proposed: 11
    version_query_supported: false
    historical_versions_served: false
    public_changelog_available: false
  being_rights: /public/rights
  observer_reciprocity: /public/observer
  generated_from_routes: false