Atlas API
The Atlas Cognitive Memory API gives AI agents persistent, queryable memory
across three cognitive layers: episodic, semantic, and working.
Base URL: https://api.atlas.bsyncs.com
Authentication
All endpoints (except /brain/health) require your API key in the header:
X-API-Key: atlas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Never expose your API key in frontend code or public repositories.
Always call Atlas from your backend or a server-side function.
Namespace isolation
The user_id field in request bodies is always overridden server-side
from your API key’s namespace. You cannot access another organisation’s
data by supplying a different user_id.
Your API key → resolves to → org_namespace: acme_corp_a1b2c3
user_id in body → ignored / overridden server-side
Use session_id for per-user or per-conversation isolation within your org:
{
"text": "Alice prefers dark mode.",
"user_id": "ignored",
"session_id": "user-alice-uuid"
}
All errors return:
{
"detail": "Human-readable error message"
}
| Code | Meaning |
|---|
400 | Bad request — missing or invalid field |
401 | Invalid or revoked API key |
422 | Validation error — wrong field type |
429 | Rate limit or monthly ops quota exceeded |
503 | Models still loading — retry in 60s |
500 | Internal server error |
Rate limits
| Plan | rpm | Ops / month |
|---|
| Free | 10 | 1,000 |
| Starter | 60 | 50,000 |
| Pro | 300 | 500,000 |
| Scale | 1,000 | 5,000,000 |
/brain/ingest or one /brain/retrieve call.
/brain/health, /brain/stats, and /brain/consolidate do not count.
Cold start
On first boot, Atlas loads two ML models (Qwen 0.5B + MiniLM).
During loading, all brain endpoints return 503.
Poll /brain/health until "models_loaded": true before sending requests.
import time, requests
def wait_until_ready(base_url, timeout=120):
for _ in range(timeout // 5):
r = requests.get(f"{base_url}/brain/health").json()
if r.get("ready") and r.get("models_loaded"):
return True
time.sleep(5)
raise TimeoutError("Atlas did not become ready in time")
SDK quickstart
pip install bsyncs-atlas-memory
from atlas_memory import CognitiveBrain
brain = CognitiveBrain(
api_key="atlas_your_key_here",
base_url="https://api.atlas.bsyncs.com",
user_id="user-123",
)
brain.add("Project Apollo uses PostgreSQL on AWS RDS.")
results = brain.search("What database does Apollo use?")
print(results.context)
