Atlas REST API reference — all endpoints, authentication, rate limits, and error codes.
All endpoints are prefixed with /brain. If you are self-hosting, replace the base URL with your own domain or IP.
Atlas uses API key authentication. Pass your key in the x-api-key request header on every call.
user_id in every request body is ignored by the server. Atlas derives the user namespace server-side from your API key. This prevents clients from reading other tenants' data.Rate limits are enforced per API key using a per-minute sliding window.
| Tier | Requests / minute |
|---|---|
| Free | 10 RPM |
| Starter | 60 RPM |
| Pro | 300 RPM |
| Scale | 1,000 RPM |
| Enterprise | Unlimited |
When a rate limit is hit, the API returns HTTP 429 with a Retry-After header:
In addition to per-minute rate limits, each tier has a monthly operations budget. Operations are consumed based on endpoint cost:
| Endpoint | Cost per call |
|---|---|
/ingest | 5 ops |
/retrieve | 2 ops |
/graph-qa | 10 ops |
/consolidate | 3 ops |
/prune | 1 op |
/stats | 0 ops (free) |
/health | 0 ops (free) |
When the monthly budget is exceeded:
All endpoints return JSON. Successful responses follow the schema documented per endpoint. Error responses always have a detail field:
| Code | Meaning |
|---|---|
200 | Success |
400 | Validation error — check request body |
401 | Invalid or revoked API key |
403 | Feature not available on your plan |
503 | Service still starting up (models loading) — retry in 30s |
Before making any memory calls, you can verify the service is fully online:
models_loaded is false, wait and retry. All memory endpoints return 503 until models are ready.The atlas-mem Python SDK wraps these endpoints automatically. You only need to call the REST API directly if you are using a language other than Python or building a custom integration.