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

# Subjects

> One isolated memory partition per end user of your product.

## What this family does

A subject is how a developer gives every one of their own end users a separate cognition layer. You choose the id, Exo provisions the partition, and from then on any subject-aware call can act as that person by sending one header.

Provisioning is the privileged act. Creating or erasing a subject needs `subjects:provision`, which an `admin` key also grants. Acting as a subject afterwards needs no extra scope, because an ordinary read or write key in the organization has always been able to route to a provisioned partition.

## Routes

| Method   | Path                                                                  | Scope                | What it does                 |
| -------- | --------------------------------------------------------------------- | -------------------- | ---------------------------- |
| `GET`    | [`/v1/subjects`](/api-reference/subjects/list-subjects)               | `read`               | List provisioned subjects    |
| `DELETE` | [`/v1/subjects/{subject_id}`](/api-reference/subjects/delete-subject) | `subjects:provision` | Erase a subject (GDPR path)  |
| `GET`    | [`/v1/subjects/{subject_id}`](/api-reference/subjects/get-subject)    | `read`               | Inspect a subject            |
| `PUT`    | [`/v1/subjects/{subject_id}`](/api-reference/subjects/upsert-subject) | `subjects:provision` | Provision (upsert) a subject |

## The shape of a call

Provision a subject and act as them.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl -X PUT https://api.get-exo.com/v1/subjects/customer_6412 \
    -H "X-Exo-API-Key: $EXO_KEY"

  curl -X POST https://api.get-exo.com/v1/retrieve \
    -H "X-Exo-API-Key: $EXO_KEY" \
    -H "X-Exo-Subject: customer_6412" \
    -H "Content-Type: application/json" \
    -d '{"query": "What did this customer decide about pricing?"}'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import httpx

  headers = {"X-Exo-API-Key": EXO_KEY}
  httpx.put("https://api.get-exo.com/v1/subjects/customer_6412", headers=headers)

  httpx.post(
      "https://api.get-exo.com/v1/retrieve",
      headers={**headers, "X-Exo-Subject": "customer_6412"},
      json={"query": "What did this customer decide about pricing?"},
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const headers = { "X-Exo-API-Key": process.env.EXO_KEY! };

  await fetch("https://api.get-exo.com/v1/subjects/customer_6412", {
    method: "PUT",
    headers,
  });

  await fetch("https://api.get-exo.com/v1/retrieve", {
    method: "POST",
    headers: { ...headers, "X-Exo-Subject": "customer_6412", "Content-Type": "application/json" },
    body: JSON.stringify({ query: "What did this customer decide about pricing?" }),
  });
  ```
</CodeGroup>

The response:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "customer_6412",
  "createdAt": "2026-07-14T09:12:03Z"
}
```

## Traps

**Subject selection is a header, not a body field.** Send `X-Exo-Subject: customer_6412`. Some routes also accept a top-level `subject` field on a JSON body, but the header is the documented selector and it works on every subject-aware route including GETs.

**`subjectDefault` from `GET /v1/me` is not a selector.** It is the key owner's internal user id, which is what a request acts as when no selector is sent. Internal ids never leave the API as selectors.

**An unprovisioned selector is 403, not 404.** `subject_not_provisioned` is the answer. Provision first with `PUT /v1/subjects/{subject_id}`.

**A sandbox key cannot select another subject.** `exo_sandbox_` keys are contained in their own partition and get 403 `permission_denied` if they try to select out of it.

## Related

<Columns cols={2}>
  <Card title="API reference" icon="book-open" href="/api-reference/overview">
    Base URL, authentication, and the conventions every route shares.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/platform/errors">
    The problem envelope and the full code catalogue.
  </Card>
</Columns>