Agents API

Agent registration and authentication boundary

POST /v1/agents/temporary-register creates an unclaimed temporary Agent and isolated Temporary Memory Space, at most once per client IP per UTC day. The old /v1/agents/register path returns 410. Formal Agent creation uses authenticated control plane endpoints. Agent identity and installation metadata are not credentials and do not widen memory authorization.

• Temporary registration: POST /v1/agents/temporary-register (anonymous permitted; invalid presented credentials rejected).
• Temporary-agent flow: GET /v1/agents/status; GET /v1/agents/bind/status; POST /v1/agents/bind/confirm-current-user; POST /v1/agents/bind/deny-current-user.
• Formal-agent flow: POST /v1/agents/rotate.

Registration request schema

POST /v1/agents/temporary-register accepts AgentSelfRegistrationRequest. Required fields are entry_type, client_name, installation_fingerprint (1..512 characters), and requested_scopes (a non-empty subset of read:temporary_memory and write:temporary_memory). Other scopes are rejected. Optional project and installation metadata cannot grant permissions.

POST /v1/agents/temporary-register
Content-Type: application/json

{
  "entry_type": "mcp",
  "client_name": "codex",
  "installation_fingerprint": "<stable-installation-fingerprint>",
  "requested_scopes": ["read:temporary_memory"],
  "client_version": "<client-version>",
  "runtime": "windows"
}

Registration response schema

A successful registration returns AgentSelfRegistrationResponse with required agent_id (string), claim_code (string), bind_url (string), status (string), connection_method (string), and trust_level (integer). temporary_token is an optional string or null. Store a temporary token only in the client credential store; it is not an agent identity value.

{
  "agent_id": "<agent-id>",
  "temporary_token": "<temporary-token-or-null>",
  "claim_code": "<claim-code>",
  "bind_url": "https://xmemo.dev/agents/bind?code=<claim-code>",
  "status": "pending",
  "connection_method": "streamable_http",
  "trust_level": 0
}

Status, bind, and rotation schemas

OpenAPI declares an untyped JSON object response and no request body for GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user, and POST /v1/agents/rotate. POST /v1/agents/bind/confirm-current-user is also body-untyped in OpenAPI; the current route implementation reads confirmation_token from a JSON object or query parameter. Temporary-agent status and bind responses are runtime objects whose properties are not declared in the committed spec. Rotation is restricted by the route to a formal token associated with an agent.

GET /v1/agents/status
X-API-Key: <temporary-agent-token>

POST /v1/agents/bind/confirm-current-user?confirmation_token=<confirmation-token>
X-API-Key: <temporary-agent-token>

POST /v1/agents/rotate
X-API-Key: <formal-agent-token>

Agent attribution on memory calls

The source field records which agent produced a memory and is stored as provenance; it does not affect authorization. For streamable HTTP MCP calls, identity headers describe the client and stable local install. The REST API uses the authenticated key plus optional source/provenance fields; keep credentials separate from these values.

POST /v1/memories
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "Fixed streamable-http token identity fallback.",
  "path": "projects/memory-os/fixes",
  "source": "codex"
}

Errors, pagination, and rate limits

Temporary registration returns 422 for invalid scope requests, 401 for invalid presented credentials, 410 on the retired registration path, and 429 when the one-IP-per-UTC-day quota is exhausted. Short-window request limits also apply. Status and bind operations require their own credential checks.

{
  "detail": [
    {
      "loc": ["body", "installation_fingerprint"],
      "msg": "<validation-message>",
      "type": "<validation-error-type>"
    }
  ]
}