Ingest a session event

curl --request POST \
  --url https://api.get-exo.com/v1/ingest/session-event \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "event": {
    "claudeCodeVersion": "<string>",
    "cwd": "<string>",
    "lineTimestamp": "2023-11-07T05:31:56Z",
    "lineType": "<string>",
    "lineUuid": "<string>",
    "orgId": "<string>",
    "payload": {},
    "sessionId": "<string>",
    "userId": "<string>",
    "agentId": "<string>",
    "authorRole": "<string>",
    "gitBranch": "<string>",
    "parentSessionId": "<string>"
  }
}
'

import requests

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

payload = { "event": {
        "claudeCodeVersion": "<string>",
        "cwd": "<string>",
        "lineTimestamp": "2023-11-07T05:31:56Z",
        "lineType": "<string>",
        "lineUuid": "<string>",
        "orgId": "<string>",
        "payload": {},
        "sessionId": "<string>",
        "userId": "<string>",
        "agentId": "<string>",
        "authorRole": "<string>",
        "gitBranch": "<string>",
        "parentSessionId": "<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({
    event: {
      claudeCodeVersion: '<string>',
      cwd: '<string>',
      lineTimestamp: '2023-11-07T05:31:56Z',
      lineType: '<string>',
      lineUuid: '<string>',
      orgId: '<string>',
      payload: {},
      sessionId: '<string>',
      userId: '<string>',
      agentId: '<string>',
      authorRole: '<string>',
      gitBranch: '<string>',
      parentSessionId: '<string>'
    }
  })
};

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

{
  "ingested": true,
  "deduped": false,
  "nodeId": "<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

ingest

session-event

Ingest a session event

curl --request POST \
  --url https://api.get-exo.com/v1/ingest/session-event \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "event": {
    "claudeCodeVersion": "<string>",
    "cwd": "<string>",
    "lineTimestamp": "2023-11-07T05:31:56Z",
    "lineType": "<string>",
    "lineUuid": "<string>",
    "orgId": "<string>",
    "payload": {},
    "sessionId": "<string>",
    "userId": "<string>",
    "agentId": "<string>",
    "authorRole": "<string>",
    "gitBranch": "<string>",
    "parentSessionId": "<string>"
  }
}
'

import requests

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

payload = { "event": {
        "claudeCodeVersion": "<string>",
        "cwd": "<string>",
        "lineTimestamp": "2023-11-07T05:31:56Z",
        "lineType": "<string>",
        "lineUuid": "<string>",
        "orgId": "<string>",
        "payload": {},
        "sessionId": "<string>",
        "userId": "<string>",
        "agentId": "<string>",
        "authorRole": "<string>",
        "gitBranch": "<string>",
        "parentSessionId": "<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({
    event: {
      claudeCodeVersion: '<string>',
      cwd: '<string>',
      lineTimestamp: '2023-11-07T05:31:56Z',
      lineType: '<string>',
      lineUuid: '<string>',
      orgId: '<string>',
      payload: {},
      sessionId: '<string>',
      userId: '<string>',
      agentId: '<string>',
      authorRole: '<string>',
      gitBranch: '<string>',
      parentSessionId: '<string>'
    }
  })
};

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

{
  "ingested": true,
  "deduped": false,
  "nodeId": "<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>"
}

The credential decides the org and user, so identity fields in the body are provenance only. Re-sending an event is safe: per-event deduplication reports it as deduped instead of storing it twice, which is why this route takes no Idempotency-Key. Use POST /v1/ingest/session-batch for anything larger than a live tail.

Authorization

This route requires the write 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`	Refused	This route scopes data by the key owner. Sending the header returns 400 `subject_not_supported`, rather than silently reading the wrong partition.
`Idempotency-Key`	Not honoured	This route does not replay: session events deduplicate per event on their own key, which is stronger than a per-request replay.
`X-Request-Id`	Response	Returned on every response, including `204`s. Quote it in a support request.

Success responses

Status	Meaning
`202`	Whether the event was queued or recognised as a duplicate.

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

Use the batch route for anything larger than a live tail. This one is for a daemon following an active transcript.
The credential decides the organization and the user. Identity fields in the body are provenance only.

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/ingest/session-event: single event from Stop/SubagentStop hooks.

event

SessionEvent · object

required

A single Claude Code session-log line.

Maps to one parsed line from a .jsonl session transcript (~/.claude/projects//.jsonl) or a sub-agent transcript (...//subagents/agent-*.jsonl).

Sub-agent events have parent_session_id + agent_id populated. Dedup key on the server side: (user_id, line_uuid).

Wire contract uses clean user_id / org_id field names (camelCase aliases on the wire). DB column mapping is handled at the SQL boundary in the ingest worker, not here.

Show child attributes

Response

Whether the event was queued or recognised as a duplicate.

ingested

boolean

required

deduped

boolean

default:false

nodeId

string | null

Coding sessions

Ingest a session batch

⌘I

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Body

Response

Authorization

Headers

Success responses

Errors

Notes