> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bsyncs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Atlas REST API reference — all endpoints, authentication, rate limits, and error codes.

## 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.

```bash theme={null}
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}'
```

<Note>
  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.
</Note>

***

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
curl https://api.bsyncs.com/brain/health
```

```json theme={null}
{
  "ready": true,
  "models_loaded": true,
  "neo4j": "connected",
  "redis": "connected",
  "qdrant": "connected",
  "version": "1.0.0"
}
```

<Warning>
  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.
</Warning>

***

## 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.

<CardGroup cols={2}>
  <Card title="Ingest" icon="arrow-up-to-line" href="/api-reference/endpoint-examples/ingest">
    Store text into episodic and semantic memory.
  </Card>

  <Card title="Retrieve" icon="magnifying-glass" href="/api-reference/endpoint-examples/retrieve">
    Hybrid search across all memory stores.
  </Card>

  <Card title="Consolidate" icon="compress" href="/api-reference/endpoint-examples/consolidate">
    Decay, prune, and compress memories.
  </Card>

  <Card title="Graph QA" icon="diagram-project" href="/api-reference/endpoint-examples/graph-qa">
    Natural language multi-hop graph queries.
  </Card>
</CardGroup>