Introduction

Base URL

https://api.bsyncs.com

All endpoints are prefixed with /brain. If you are self-hosting, replace the base URL with your own domain or IP.

Authentication

Atlas uses API key authentication. Pass your key in the x-api-key request header on every call.

curl -X POST https://api.bsyncs.com/brain/retrieve \
  -H "x-api-key: atlas_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "What database does Acme use?", "k": 5}'

The 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

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:

{
  "error": "rate_limit_exceeded",
  "limit": 10,
  "tier": "free",
  "retry_after_seconds": 43,
  "upgrade": "https://atlas.bsyncs.com/pricing"
}

Monthly operation limits

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:

{
  "error": "monthly_limit_exceeded",
  "tier": "free",
  "upgrade": "https://atlas.bsyncs.com/pricing"
}

Response format

All endpoints return JSON. Successful responses follow the schema documented per endpoint. Error responses always have a detail field:

{
  "detail": "Service still loading models."
}

Common status codes

Code	Meaning
`200`	Success
`400`	Validation error — check request body
`401`	Invalid or revoked API key
`403`	Feature not available on your plan
`429`	Rate limit or monthly budget exceeded
`503`	Service still starting up (models loading) — retry in 30s

Health check

Before making any memory calls, you can verify the service is fully online:

curl https://api.bsyncs.com/brain/health

{
  "ready": true,
  "models_loaded": true,
  "neo4j": "connected",
  "redis": "connected",
  "qdrant": "connected",
  "version": "1.0.0"
}

The service takes up to 120 seconds to load models on cold start. If models_loaded is false, wait and retry. All memory endpoints return 503 until models are ready.

SDK vs. direct API

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.

Ingest

Store text into episodic and semantic memory.

Retrieve

Hybrid search across all memory stores.

Consolidate

Decay, prune, and compress memories.

Graph QA

Natural language multi-hop graph queries.

API documentation

Endpoint examples

Base URL

Authentication

Rate limits

Monthly operation limits

Response format

Common status codes

Health check

SDK vs. direct API

Ingest

Retrieve

Consolidate

Graph QA

​Base URL

​Authentication

​Rate limits

​Monthly operation limits

​Response format

​Common status codes

​Health check

​SDK vs. direct API

Ingest

Retrieve

Consolidate

Graph QA

Base URL

Authentication

Rate limits

Monthly operation limits

Response format

Common status codes

Health check

SDK vs. direct API