REST API.

Who should use the REST API

Use REST when you are building a service, script, or integration that cannot use MCP. Authenticate with an OAuth bearer token; the legacy API-key header exists only for V1 compatibility and should not be the default for new clients.

curl https://empirical.gauzza.com/api/v1/users/me 
  -H "Authorization: Bearer $EMPIRICAL_ACCESS_TOKEN"

Core endpoints

Use the memories collection for list and write operations, the query route for semantic retrieval, and users/me to verify identity and workspace context.

• GET/POST/PATCH/DELETE `/api/v1/memories`
• POST `/api/v1/memories/query`
• GET `/api/v1/users/me`
• GET/POST/DELETE `/api/v1/memories/:id/attachments` and `/attachments/:attachmentId` (plus `/restore`), multipart upload, proxied download
• GET `/api/v1/memories/:id/tree` — an item and everything nested under it; `?format=markdown` returns the document itself

curl -X POST https://empirical.gauzza.com/api/v1/memories/query 
  -H "Authorization: Bearer $EMPIRICAL_ACCESS_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"query":"deployment constraints","topK":3}'

Response handling and limits

Refresh tokens before expiry, retry only safe transient failures, respect rate limits, and inspect error JSON before retrying a write. REST is a lower-level surface; use MCP when an agent already supports tool discovery and OAuth.

Related: See MCP Server for tool-based integrations and Headless & CI for production token handling.