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

# API reference

> Every Atlaso Build endpoint — remember, recall, delete, GDPR purge, and device credentials — with curl, Python, and Node examples.

Base URL: `https://mcp.atlaso.ai/developer/v1`. Authenticate with a project key +
subject, or a device bearer — see [Authentication](/build/authentication). All
bodies are JSON.

## Remember

Store a memory in a subject's bag.

`POST /memories`

**Body**

| Field  | Type      | Notes                                     |
| ------ | --------- | ----------------------------------------- |
| `text` | string    | Required. 1 byte – 64 KB UTF-8.           |
| `tags` | string\[] | Optional. Up to 32 tags, each ≤128 chars. |

Pass an optional `Idempotency-Key` header to make retries safe
([details](/build/limits#idempotency)).

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://mcp.atlaso.ai/developer/v1/memories \
    -H "X-Atlaso-Project-Key: $ATLASO_KEY" \
    -H "X-Atlaso-Subject: user_8213" \
    -H "Content-Type: application/json" \
    -d '{"text": "Prefers window seats.", "tags": ["prefs"]}'
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      "https://mcp.atlaso.ai/developer/v1/memories",
      headers={
          "X-Atlaso-Project-Key": ATLASO_KEY,
          "X-Atlaso-Subject": "user_8213",
      },
      json={"text": "Prefers window seats.", "tags": ["prefs"]},
  ).raise_for_status()
  ```

  ```javascript Node theme={null}
  await fetch("https://mcp.atlaso.ai/developer/v1/memories", {
    method: "POST",
    headers: {
      "X-Atlaso-Project-Key": process.env.ATLASO_KEY,
      "X-Atlaso-Subject": "user_8213",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: "Prefers window seats.", tags: ["prefs"] }),
  });
  ```
</CodeGroup>

**Response**

```json theme={null}
{ "id": "mem_9f2c…", "subject": "user_8213", "redacted": [] }
```

`redacted` lists the category names of any recognized secrets, credentials, or
high-entropy tokens scrubbed before storing, such as `aws_access_key` or
`high_entropy`. It never contains the removed values.

## Recall

Retrieve the most relevant memories for a subject, semantically ranked.

`GET /recall?q=<query>&limit=<n>`

| Param   | Notes                                            |
| ------- | ------------------------------------------------ |
| `q`     | Required. The query, ≤2048 chars.                |
| `limit` | Optional. Default 5; values are clamped to 1–50. |

<CodeGroup>
  ```bash curl theme={null}
  curl "https://mcp.atlaso.ai/developer/v1/recall?q=seating&limit=5" \
    -H "X-Atlaso-Project-Key: $ATLASO_KEY" \
    -H "X-Atlaso-Subject: user_8213"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://mcp.atlaso.ai/developer/v1/recall",
      headers={"X-Atlaso-Project-Key": ATLASO_KEY, "X-Atlaso-Subject": "user_8213"},
      params={"q": "seating", "limit": 5},
  )
  r.raise_for_status()
  print(r.json()["results"])
  ```

  ```javascript Node theme={null}
  const url = new URL("https://mcp.atlaso.ai/developer/v1/recall");
  url.search = new URLSearchParams({ q: "seating", limit: "5" });
  const res = await fetch(url, {
    headers: {
      "X-Atlaso-Project-Key": process.env.ATLASO_KEY,
      "X-Atlaso-Subject": "user_8213",
    },
  });
  const { results } = await res.json();
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "subject": "user_8213",
  "is_confident": true,
  "has_disagreement": false,
  "results": [
    {
      "id": "mem_9f2c…",
      "content": "Prefers window seats.",
      "tags": ["prefs"],
      "is_confident": true,
      "has_disagreement": false,
      "conflict_peers": []
    }
  ]
}
```

* `is_confident` — whether Atlaso is confident in the result (top level = the
  overall answer; per-result = that memory).
* `has_disagreement` / `conflict_peers` — set when the subject holds
  **conflicting** memories (e.g. "likes window seats" vs a later "now prefers
  aisle"). Atlaso surfaces both rather than silently picking one; you decide
  which to trust.

## Delete a memory

Hard-delete one memory. Idempotent — deleting something already gone returns
`deleted: false`, not an error.

`DELETE /memories/{id}?reason=<optional>`

```bash theme={null}
curl -X DELETE "https://mcp.atlaso.ai/developer/v1/memories/mem_9f2c…?reason=user_request" \
  -H "X-Atlaso-Project-Key: $ATLASO_KEY" \
  -H "X-Atlaso-Subject: user_8213"
```

```json theme={null}
{ "deleted": true, "id": "mem_9f2c…", "subject": "user_8213" }
```

This is a real erase — the memory, its search index, and its conflict links are
removed, not tombstoned.

## Delete a subject (GDPR)

Purge an end-user's **entire** memory bag in one call — for a "delete my data"
request.

`DELETE /subjects/{subject}?reason=<optional>`

```bash theme={null}
curl -X DELETE "https://mcp.atlaso.ai/developer/v1/subjects/user_8213?reason=gdpr" \
  -H "X-Atlaso-Project-Key: $ATLASO_KEY" \
  -H "X-Atlaso-Subject: user_8213"
```

The subject in the path must match the subject you're authenticated as
(mismatch → `403`). Idempotent, and it frees the storage the subject used.

```json theme={null}
{ "purged": true, "subject": "user_8213", "erased": 12 }
```

## Device credentials

Mint, batch-enroll, and revoke per-device credentials. These use the **project
key only** (no subject header). Full guide: [Devices & hardware](/build/devices).

| Method | Path                         | Purpose                                                                     |
| ------ | ---------------------------- | --------------------------------------------------------------------------- |
| `POST` | `/device-credentials`        | Mint one credential: `{ subject, external_device_id?, label?, group_id? }`. |
| `POST` | `/device-credentials/batch`  | Enroll up to 500 devices at once (`Idempotency-Key` supported).             |
| `POST` | `/device-credentials/revoke` | Revoke by `credential_id`, or a whole fleet by `group_id`.                  |

```bash theme={null}
curl -X POST https://mcp.atlaso.ai/developer/v1/device-credentials \
  -H "X-Atlaso-Project-Key: $ATLASO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "kiosk_lobby", "label": "Lobby kiosk", "group_id": "lobby-fleet"}'
```

```json theme={null}
{
  "credential_id": "…",
  "full_token": "atldev_…_…",
  "subject": "kiosk_lobby",
  "external_device_id": null,
  "existing": false
}
```

`full_token` is shown once for a newly minted credential — flash it to the
device and store nothing else.

For batch enrollment, send the devices and an optional fleet-level `group_id`:

```json theme={null}
{
  "devices": [
    {
      "subject": "kiosk_lobby",
      "external_device_id": "kiosk-001",
      "label": "Lobby kiosk"
    }
  ],
  "group_id": "lobby-fleet"
}
```

The response wraps each credential in `credentials` and includes the total:

```json theme={null}
{
  "credentials": [
    {
      "credential_id": "…",
      "full_token": "atldev_…_…",
      "subject": "kiosk_lobby",
      "external_device_id": "kiosk-001",
      "existing": false
    }
  ],
  "count": 1
}
```

Re-enrolling the same `external_device_id` returns the existing credential with
`existing: true` and `full_token: null`.

Revocation returns the number of credentials revoked:

```json theme={null}
{ "revoked": 1 }
```