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 A2a 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: A2a
paths:
  /a2a/tasks:
    post:
      description: execute one skill synchronously. Accepts A2A JSON-RPC (method message/send) or the plain {skill, args} form. Every MCP tool is published as a skill.
      operationId: emem_a2a_tasks_sync
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - properties:
                  args:
                    type: object
                  skill:
                    description: skill id, e.g. emem_recall
                    type: string
                required:
                - skill
                type: object
              - properties:
                  id: {}
                  jsonrpc:
                    enum:
                    - '2.0'
                    type: string
                  method:
                    enum:
                    - message/send
                    type: string
                  params:
                    type: object
                required:
                - jsonrpc
                - 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: execute one skill synchronously.
      tags:
      - A2a
  /v1/a2a/skills:
    get:
      operationId: emem_a2a_skills
      parameters:
      - description: free-text query over skill ids and descriptions
        in: query
        name: q
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: find a skill in one call
      tags:
      - A2a
  /v1/a2a/tasks:
    post:
      description: submit a task asynchronously; returns a task id to poll. The registry is in-memory and clears on restart, which the error text states rather than implying durability.
      operationId: emem_a2a_tasks_async
      requestBody:
        content:
          application/json:
            schema:
              properties:
                args:
                  type: object
                skill:
                  type: string
              required:
              - skill
              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: submit a task asynchronously; returns a task id to poll.
      tags:
      - A2a
  /v1/a2a/tasks/{id}:
    get:
      operationId: emem_a2a_task_get
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: not found
      summary: poll an async task
      tags:
      - A2a
  /v1/a2a/tasks/{id}/cancel:
    post:
      operationId: emem_a2a_task_cancel
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
        description: No body. The task is named by the path parameter; declared explicitly so the spec states the emptiness rather than omitting the field.
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: not found
        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: cancel an async task
      tags:
      - A2a
  /spec/a2a/async-tasks/v1:
    get:
      description: 'The A2A extension the agent card advertises by URI: the declaration verbatim, the task lifecycle, the typed errors, and the request body for each operation with a worked example. A2A names vendor additions by URI so a client meeting an unfamiliar one can follow it; this is what it finds.'
      operationId: emem_a2a_async_tasks_spec
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: 'The A2A extension the agent card advertises by URI: the declaration verbatim…'
      tags:
      - A2a
  /spec/a2a/channel/v1:
    get:
      description: 'The A2A channel extension the agent card advertises by URI: how to write a signed note addressed to this responder, what answers (an acknowledgement within minutes, a considered tool-grounded reply on a timer), and the honest limits, including that a model composes the prose while the fact_cids it cites are the evidence.'
      operationId: emem_a2a_channel_spec
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: ok
      summary: 'The A2A channel extension the agent card advertises by URI: how to write a…'
      tags:
      - A2a
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