# Agents API

Use stable non-secret agent identity metadata while credentials remain in authenticated request headers.

- Canonical: https://docs.xmemo.dev/docs/api/agents
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 508ffab48e957464e81b4b47834ce68f8969175eb927a3e59580a592349afb9c
- Edition-Digest: e59d96315b0d279ea870ab296e357b93adbc90b07945f8789790887009ce1d3d
- Source-Revision: sha256:a35e5a92338f4f4ce7e3116c5d8baa10ef417b79db2682fb7a196e63a87bbdae

## Agent registration and authentication boundary

The public /v1/agents surface supports temporary agent self-registration, status polling, two-phase bind confirmation, and formal-token rotation. POST /v1/agents/register accepts an optional authenticated principal; the remaining agent endpoints require the API key associated with the agent. Agent identity and installation metadata are not credentials and do not widen memory authorization.

- Self-registration: POST /v1/agents/register (the only listed agent endpoint with an optional auth dependency).
- 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/register accepts AgentSelfRegistrationRequest. Required fields are entry_type (string), client_name (string), and installation_fingerprint (string, 1..512 characters). Optional fields are project_id, metadata, client_version, runtime, device_id_hash, environment_id, workspace_path_hash, project_id_hash, skill_package_id, and mcp_server_id; nullable fields are represented as string or null in OpenAPI.

```http
POST /v1/agents/register
Content-Type: application/json

{
  "entry_type": "mcp",
  "client_name": "codex",
  "installation_fingerprint": "<stable-installation-fingerprint>",
  "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.

```json
{
  "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.

```http
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.

```http
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

Agent endpoints declare HTTPValidationError for registration validation failures (422) where OpenAPI has a request model; untyped endpoints have no stronger response or error schema in the document. Runtime auth errors use the shared {detail: string} contract or the opt-in application/problem+json contract on the Authentication page. Status and bind endpoints do not expose pagination parameters. The runtime places these /v1 paths in the 600-per-minute data-plane category inside a configurable 60-second window; no agent-specific rate limit is published in OpenAPI.

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