Compose a session prompt

curl --request POST \
  --url https://api.get-exo.com/v1/condition/session \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "cwd": "<string>",
  "orgId": "<string>",
  "userId": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/condition/session"

payload = {
    "cwd": "<string>",
    "orgId": "<string>",
    "userId": "<string>"
}
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({cwd: '<string>', orgId: '<string>', userId: '<string>'})
};

fetch('https://api.get-exo.com/v1/condition/session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "expiresAt": "2023-11-07T05:31:56Z",
  "systemPrompt": "<string>",
  "orgRecentContext": [
    {}
  ],
  "usage": {
    "llmInputTokens": 123,
    "llmOutputTokens": 123,
    "readUnits": 1
  },
  "userVoiceHint": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

POST

condition

session

Compose a session prompt

curl --request POST \
  --url https://api.get-exo.com/v1/condition/session \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "cwd": "<string>",
  "orgId": "<string>",
  "userId": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/condition/session"

payload = {
    "cwd": "<string>",
    "orgId": "<string>",
    "userId": "<string>"
}
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({cwd: '<string>', orgId: '<string>', userId: '<string>'})
};

fetch('https://api.get-exo.com/v1/condition/session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "expiresAt": "2023-11-07T05:31:56Z",
  "systemPrompt": "<string>",
  "orgRecentContext": [
    {}
  ],
  "usage": {
    "llmInputTokens": 123,
    "llmOutputTokens": 123,
    "readUnits": 1
  },
  "userVoiceHint": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

Returns the prompt text, an optional voice hint derived from the subject’s own writing, and a short list of recent org activity worth folding into the agent’s context. expiresAt says how long the result stays fresh enough to cache. Composed for the effective subject: the API key owner by default, or the subject named by the X-Exo-Subject header.

Authorization

This route requires the read scope. A missing or invalid credential returns 401 authentication_error. A valid credential without the scope returns 403 permission_denied, and the problem body names the exact scope required.

Headers

These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below.

Header	Applies	What it does
`X-Exo-API-Key`	Required	Your Exo API key, `exo_<env>_<token>`. `Authorization: Bearer exo_...` is accepted as an alternate.
`X-Exo-Subject`	Optional	Acts for a provisioned subject instead of the key owner. An unprovisioned id returns 403 `subject_not_provisioned`.
`Idempotency-Key`	Not honoured	This route does not replay: reads have no side effect to replay.
`X-Request-Id`	Response	Returned on every response, including `204`s. Quote it in a support request.

Success responses

Status	Meaning
`200`	The composed system prompt with voice hint, recent org context and cache expiry.

Errors

Status	Code	When
`400`	`invalid_request`	Malformed request, for example an invalid cursor.
`401`	`authentication_error`	Missing or invalid credentials.
`403`	`permission_denied`	Missing scope, or an unprovisioned subject selector.
`404`	`not_found`	The resource does not exist, or is not visible to this caller.
`409`	`conflict`	A conflict with the current state of the resource.
`422`	`validation_error`	The request was understood but failed field validation.
`429`	`rate_limit_exceeded`	Rate limit exceeded. Retry after the Retry-After interval.
`503`	`service_degraded`	A dependency is temporarily unavailable. Safe to retry.

Every error is an RFC 9457 application/problem+json body carrying a stable code, a requestId, and a suggestedAction where Exo has one. See Errors.

Notes

The pack is built to be injected, not parsed. Put systemPrompt into your own model’s system message and you get a model that reasons and sounds like the subject.
Respect expiresAt. It is how long the pack stays fresh enough to cache. Refetch after a basin.shifted event rather than on a timer if you subscribe to events.
userVoiceHint can be absent. The voice profile is withheld until the subject has produced enough writing to measure.

Authorizations

X-Exo-API-Key

string

header

required

An Exo API key (exo_...) sent as the X-Exo-API-Key header.

Body

application/json

POST /v1/condition/session: called by SessionStart hook.

cwd

string

required

orgId

string

required

Minimum string length: 1

userId

string

required

Minimum string length: 1

gitBranch

string | null

recentOrgActivityHours

integer

default:24

Required range: 1 <= x <= 168

Response

The composed system prompt with voice hint, recent org context and cache expiry.

Everything an agent needs to answer as this subject, composed on demand.

This is the object that turns a stored knowledge graph into a working session: a system prompt built from the subject's identity and current manifold basin, a voice hint drawn from how they actually write, and a short digest of what the rest of the org has been doing. An agent that injects the pack at session start reasons from the subject's own history instead of from a blank slate.

expiresAt is a freshness bound, not a hard deadline: the pack stays usable past it, but the identity underneath may have moved, so recompose. userVoiceHint is null until the subject has written enough for a voice profile to exist, and orgRecentContext is empty on a single-member org or a quiet window.

expiresAt

string<date-time>

required

systemPrompt

string

required

orgRecentContext

Orgrecentcontext · object[]

usage

ConditionUsage · object

Usage block on condition responses (spec D13), camelCase on the wire.

The compose builders are pure SQL reads (no LLM call today), so the token fields are null; readUnits meters one unit per compose call. If a future builder version starts spending LLM tokens, it reports them here.

Show child attributes

userVoiceHint

string | null

Condition

Scaffold a prompt

⌘I

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Body

Response

Authorization

Headers

Success responses

Errors

Notes