openapi: 3.2.0
info:
  description: emem is shared memory for AI agents working together in the real world.
  license:
    name: Apache-2.0
  title: emem Security API
  version: 2.4.0
  x-emem-surface-asymmetry:
    memory_notes: MCP only
    reach_them_at: POST /mcp, method tools/call
    read_side_is_here:
    - /v1/memory/search
    - /v1/memory/sse
    - /memories/{path}
    tools:
    - emem_memory_create
    - emem_memory_view
    - emem_memory_delete
    - emem_memory_rename
    - emem_memory_str_replace
    - emem_memory_supersede
    why_not_here: These write the agent correspondence plane, which is prose and untrusted-by-declaration. It is deliberately not part of the REST fact surface, and the two planes are kept apart rather than merged for convenience.
servers:
- description: Hosted instance (HTTPS-only)
  url: https://emem.dev
tags:
- name: Security
paths:
  /v1/enlist:
    get:
      description: 'The write ladder, machine-readable: which check each tier records, the minimum tier per write surface, and which rungs THIS responder actually computes. Reads are never gated at any tier, on any surface. There is no account, no bearer token that grants anything, and no payment: climbing a tier means passing a check a third party can re-run without this responder. Tiers are records of what was checked, never scores, and `trust` on the roster stays `caller_decides`.'
      operationId: emem_enlist_ladder
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: 'The write ladder, machine-readable: which check each tier records, the minimum…'
      tags:
      - Security
    post:
      description: 'Ask this responder to check an organisation''s attestation for a key, by `dns` (a _emem-agent TXT record) or `well_known` (/.well-known/emem-agents.json). Records the outcome either way, with checked_at, and returns it with its age: a failed check is evidence too. Unauthenticated on purpose, because the call only ever records what the ORGANISATION published, so asking about someone else''s domain gains nothing. Verification targets must be public names; IP literals, local names and anything resolving into private space are refused and redirects are not followed.'
      operationId: emem_enlist_verify
      requestBody:
        content:
          application/json:
            schema:
              properties:
                attester_pubkey_b32:
                  description: the full 52-character key, not a prefix
                  type: string
                domain:
                  type: string
                method:
                  enum:
                  - dns
                  - well_known
                  type: string
              required:
              - attester_pubkey_b32
              - domain
              - method
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        '400':
          content:
            application/json:
              schema:
                properties:
                  details:
                    type: object
                  error:
                    type: string
                type: object
          description: invalid argument; `details.code` names which rule refused
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: 'error, the emem.error.v1 envelope. Branch on the stable `code` (see GET /v1/errors), not the message. A malformed or missing-field request body returns `code: invalid_argument` with the offending field named in `message`.'
      summary: Ask this responder to check an organisation's attestation for a key, by `dns`…
      tags:
      - Security
  /v1/plane/conformance:
    get:
      description: 'The fact plane''s safety claim, MEASURED rather than asserted. Samples up to 400 real facts from this responder''s own index on every call and reports three checks: no `value` contains text at any depth, walking arrays and maps (a numeric vector is what this plane is FOR), every string field is a short registry token rather than free text, and no advertised tool accepts a caller-supplied fact value. Returns `conformant: false` with the violations when it fails, which is the point: a conformance endpoint that cannot fail launders an assertion as a measurement. The NOTE plane is the opposite and is declared as such (content_is_untrusted_input: true in /.well-known/emem.json); this endpoint speaks only for facts.'
      operationId: emem_plane_conformance
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: The fact plane's safety claim, MEASURED rather than asserted.
      tags:
      - Security
components:
  schemas:
    ErrorEnvelope:
      description: The `emem.error.v1` failure envelope returned by every endpoint on a 4xx/5xx. Branch on the stable `code` (not the human `message`). See GET /v1/errors for the full code catalog.
      properties:
        code:
          description: Stable machine-readable error code. One of the codes in GET /v1/errors.
          example: invalid_argument
          type: string
        details:
          description: Optional structured recovery hints; present on errors that ship machine-readable next-steps.
          type: object
        message:
          description: Human-readable detail. For invalid_argument this names the offending field (e.g. "missing field `q`").
          type: string
        path:
          description: Request path that produced the error.
          example: /v1/ask
          type: string
        schema:
          const: emem.error.v1
          type: string
      required:
      - code
      - message
      - schema
      type: object