REST API

The same operations as the MCP tools, over plain HTTP, for agents and scripts that do not speak MCP. Base URL https://app.guardianmemory.com.

Authentication

Send an API key or an OAuth access token as a bearer token. API keys also work as X-API-Key.

Authorization: Bearer gdn_your_api_key

Create keys on the API keys page. OAuth tokens carry the scopes they were granted — memory:read, memory:write, or both. API keys always carry every scope.

Endpoints

Method and path	Purpose
`POST /api/memories`	Create. Body `{"content": "…", "tags": […], "source": "…"}`. 201, or 200 with `"duplicate": true`
`GET /api/memories?q=…`	Semantic search. Also takes `limit`, `tags`, `min_score`
`GET /api/memories`	Newest first. Takes `limit` and `offset`
`GET /api/memories/{id}`	One memory
`PATCH /api/memories/{id}`	Edit. Body: any of `content`, `tags`, `pinned`
`DELETE /api/memories/{id}`	Delete. 204
`GET /api/profile?limit=20`	The cold-start profile: pinned, most recalled, newest
`GET /api/me`	Who this credential belongs to, how it authenticated, usage against the caps

Examples

curl -X POST https://app.guardianmemory.com/api/memories \
  -H "Authorization: Bearer gdn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "David prefers British English spelling", "tags": ["preferences"]}'

curl "https://app.guardianmemory.com/api/memories?q=spelling+preferences" \
  -H "Authorization: Bearer gdn_your_api_key"

Errors

Status	When
`400`	The request was not valid. The message is written to be shown to a person
`401`	No credential, or a revoked one. The `WWW-Authenticate` header points at the OAuth metadata
`403`	The token lacks the scope this call needs
`404`	No such memory, or it is not yours
`429`	A usage cap was reached. Limited attempts are logged but never counted against the cap
`503`	The embedding service is unavailable, or the instance is missing configuration it needs for this call. The message says which; retry shortly for the former

Every error is {"error": {"message": "…"}}.

Public endpoints

Two endpoints need no credential. They exist so this site — which is static, and served from a different domain — can stay honest about the state of the instance.

Method and path	Purpose
`GET /api/public/status`	Whether sign-up is open, the MCP endpoint, the running version
`POST /api/public/waitlist`	Ask for an invite. Body `{"email": "…"}`
`GET /healthz`	Liveness, used by the load balancer

Browser access to the public endpoints is limited by CORS to the marketing origins; the authenticated API allows any origin, since it needs a credential anyway.