# REST API

Accessing SurrealDB Agent Memory directly via its HTTP REST API.

SurrealDB Agent Memory exposes a REST API over HTTP from the **api** role. Every SDK and harness adapter maps to these endpoints, so you can integrate from any language that can make HTTP requests.

## URL structure

One host (default port **9090**) serves:

| Path | Purpose |
| --- | --- |
| `/api/v1/{context_id}/...` | End-user operations: facts, documents, query, chat, sessions, traces |
| `/api/v1/contexts/...` | Management: Context lifecycle and key provisioning (management key) |
| `/api/v1/health` | Liveness |
| `/mcp` | MCP server (Streamable HTTP); same Bearer auth |

The `{context_id}` segment is the identifier you assigned at bootstrap (for example `dev`), not an opaque UUID unless you chose one.

## Authentication

```http
Authorization: Bearer <api_key>
```

Do not send a raw secret without the `Bearer` prefix. Management and end-user keys both use the same header; the server infers capabilities from the key material.

Optional on writes:

```http
Idempotency-Key: <stable-id>
```

## The four verbs

| Verb | Endpoint | When to use |
| --- | --- | --- |
| Remember | `POST /api/v1/{ctx}/facts`, `POST .../facts/batch` | Conversations, single facts, harness batch capture |
| Upload | `POST /api/v1/{ctx}/documents` | PDFs, manuals, code, media |
| Recall | `POST /api/v1/{ctx}/query` | Ranked hits over the unified substrate |
| Chat | `POST /api/v1/{ctx}/chat` | Let SurrealDB Agent Memory run recall + synthesis |

Formatted prompt text without raw hit lists: `POST /api/v1/{ctx}/context`.

## Example: remember and recall

```bash
export SPECTRON_URL=http://localhost:9090
export SPECTRON_API_KEY=<context-key>
export SPECTRON_CONTEXT_ID=dev

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/facts" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Alice was promoted to CTO.","infer":"full","scope":["org/acme/user/alice"]}'

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/query" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is Alice'\''s role?","limit":10,"scope":["org/acme/user/alice"]}'
```

The [`spectron`](/docs/agent-memory/reference/cli.md) CLI wraps the same paths (`spectron remember`, `spectron recall`, `spectron chat`).

## Full reference

Endpoint tables, session introspection routes, document APIs, traces, and scope/principal management are documented in [REST API reference](/docs/agent-memory/reference/rest-api.md).