One memory per end user

A subject is one end user of your product, given their own isolated memory partition inside your organization. You provision a subject once, then any call can act as that subject by adding a single header. Omit the header and calls act as the API key owner, so single-user integrations never think about this at all.

Before you start

A key that can provision

PUT and DELETE on subjects need subjects:provision. An admin key also qualifies.

A stable id per user

1 to 128 characters of A-Z a-z 0-9 . _ : -. Your own user id works well.

Somewhere to store it

Your database maps your user to their subject id. Exo never returns your mapping.

The shortest call that works

Provisioning takes no request body. The id in the path is the whole request.

curl -X PUT https://api.get-exo.com/v1/subjects/customer_6412 \
  -H "X-Exo-API-Key: $EXO_KEY"

import httpx

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

const r = await fetch("https://api.get-exo.com/v1/subjects/customer_6412", {
  method: "PUT",
  headers: { "X-Exo-API-Key": process.env.EXO_KEY! },
});
console.log(r.status, await r.json());

201 Created

{
  "id": "customer_6412",
  "createdAt": "2026-07-30T14:22:08Z"
}

The call is idempotent: 201 the first time, 200 every time after, with the same body. That means you can call it on every login without checking whether the subject exists.

Selecting a subject on a call

Send X-Exo-Subject. That header is the selector, on every route that takes one.

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 onboarding?"}'

import httpx

exo = httpx.Client(
    base_url="https://api.get-exo.com",
    headers={"X-Exo-API-Key": EXO_KEY},
)

def as_subject(subject_id: str) -> dict:
    return {"X-Exo-Subject": subject_id}

r = exo.post(
    "/v1/retrieve",
    headers=as_subject("customer_6412"),
    json={"query": "What did this customer decide about onboarding?"},
)

function exoHeaders(subjectId?: string): Record<string, string> {
  const h: Record<string, string> = {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
  };
  if (subjectId) h["X-Exo-Subject"] = subjectId;
  return h;
}

const r = await fetch("https://api.get-exo.com/v1/retrieve", {
  method: "POST",
  headers: exoHeaders("customer_6412"),
  body: JSON.stringify({ query: "What did this customer decide about onboarding?" }),
});

Subject selection is a header, not a body field. Putting subject in a JSON body does not select a subject on the ingest, retrieve or condition routes, and no error tells you it was ignored: the call silently reads and writes the key owner’s partition instead. If a call is returning the wrong person’s data, check that the header is actually being sent.

Because the selector is a header, wrap it once in your client rather than threading it through every call site. Both snippets above show the shape worth copying.

The lifecycle

Provision on first sight

Call PUT /v1/subjects/{id} when the end user first appears in your product, or on every login. It is idempotent, so there is no “already exists” branch to write.

Write and read as them

Every ingest, import, retrieve, search, condition and recall call takes X-Exo-Subject. Their content lands in their partition and never mixes with another subject’s.

curl -X POST https://api.get-exo.com/v1/ingest \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "X-Exo-Subject: customer_6412" \
  -H "Content-Type: application/json" \
  -d '{"content": "Prefers async review over live calls."}'

List and inspect

GET /v1/subjects is keyset-paginated: page with nextCursor until hasMore is false. pageSize is coerced into 1 to 100 and defaults to 25.

curl "https://api.get-exo.com/v1/subjects?pageSize=50" \
  -H "X-Exo-API-Key: $EXO_KEY"

200 OK

{
  "data": [
    { "id": "customer_6412", "createdAt": "2026-07-30T14:22:08Z" },
    { "id": "customer_7781", "createdAt": "2026-07-29T09:04:55Z" }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET /v1/subjects/{id} fetches one, or returns 404 subject_not_found. Use it as an existence check.

Erase when they leave

DELETE /v1/subjects/{id} is the documented right-to-be-forgotten path. It returns 204 and is idempotent.

curl -X DELETE https://api.get-exo.com/v1/subjects/customer_6412 \
  -H "X-Exo-API-Key: $EXO_KEY" -i

See Forgetting and portability for exactly what it removes.

Choosing subject ids

The id must be 1 to 128 characters drawn from A-Za-z0-9._:-. It is yours to choose and it is the only handle you get back, so pick something you already store.

Good	Why
`customer_6412`	Your own primary key, prefixed
`0d5b7c92-3a41-4e88-9b02-6f7c1d4a5e30:user_338`	Encodes your own tenancy in one stable string
`u_9f2c1e04`	Opaque, stable, no personal data in the id

Avoid raw email addresses: @ is not in the allowed character set, and an id is not the place for personal data you may later have to erase.

A subject id that collides with the key owner is rejected with 409. The key owner is not a subject; it is the identity a request acts as when no selector is sent.

What isolation actually means

Each organization gets its own physical database schema. Subjects live inside it, scoped per user. Two consequences worth designing around:

Cross-subject reads do not happen by accident. A node belonging to another subject returns 404 rather than leaking its existence.
Any key in your organization can read any subject in it. Subjects isolate your end users from each other, not from you. Your API key is an organization credential, so treat it like one.

GET /v1/me reports subjectDefault, which is always the key owner’s user id: the identity used when no selector is sent. It is deliberately not the resolved X-Exo-Subject value, because internal subject user ids are an isolation detail and never leave the API. Do not use subjectDefault to confirm which subject a call read.

When it goes wrong

What you see	Why	What to do
`403 permission_denied` on a normal call	The header names a subject that was never provisioned	`PUT` the subject first. An unprovisioned selector is refused before the handler runs. See permission_denied
`404 subject_not_found` on `GET /v1/subjects/{id}`	No such subject in this organization	Provision it, or check for a typo in the id
`409` on `PUT`	The id collides with the key owner	Choose a different id
`409 subject_mapping_invalid` on `DELETE`	The mapping is corrupt and points at a non-service user	Nothing is erased. Contact support with the `requestId`. See subject_mapping_invalid
`422` on `PUT`	The id is longer than 128 chars or uses characters outside `A-Za-z0-9._:-`	Normalize ids before sending, especially if they came from an email
Data lands on the wrong person	The selector was sent in the body instead of the header	Move it to `X-Exo-Subject`

Subjects and isolation

The isolation model underneath, and why subjectDefault is never the resolved selector.

Forgetting and portability

Erase one subject completely, or export everything they ever stored.

Start

Building with Exo

Platform

One memory per end user

Before you start

A key that can provision

A stable id per user

Somewhere to store it

The shortest call that works

Selecting a subject on a call

The lifecycle

Choosing subject ids

What isolation actually means

When it goes wrong

Next

Subjects and isolation

Forgetting and portability

​Before you start

A key that can provision

A stable id per user

Somewhere to store it

​The shortest call that works

​Selecting a subject on a call

​The lifecycle

​Choosing subject ids

​What isolation actually means

​When it goes wrong

​Next

Subjects and isolation

Forgetting and portability

Before you start

The shortest call that works

Selecting a subject on a call

The lifecycle

Choosing subject ids

What isolation actually means

When it goes wrong

Next