Subjects - Exo

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`	`read`	List provisioned subjects
`DELETE`	`/v1/subjects/{subject_id}`	`subjects:provision`	Erase a subject (GDPR path)
`GET`	`/v1/subjects/{subject_id}`	`read`	Inspect a subject
`PUT`	`/v1/subjects/{subject_id}`	`subjects:provision`	Provision (upsert) a subject

The shape of a call

Provision a subject and act as them.

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

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?"},
)

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?" }),
});

The response:

{
  "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.

API reference

Base URL, authentication, and the conventions every route shares.

Errors

The problem envelope and the full code catalogue.

​What this family does

​Routes

​The shape of a call

​Traps

​Related