Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

/v1/sessions is the entry point to everything. A session is one recorded run of a workflow.

​
Create a session

POST /v1/sessions
Authorization: Bearer nsk_live_...
Content-Type: application/json

{
  "workflow": "process_invoice",
  "metadata": {
    "vendor": "Acme",
    "amount": 4500
  },
  "actor": { "id": "alex@nusomi.com", "kind": "human" }
}

​
Body

FieldTypeRequiredNotes
workflowstringyesSlug. ^[a-z0-9_]{2,64}$.
metadataobjectnoArbitrary JSON. ≤16 KB total.
actorobjectno{ id, kind }. kind is human | model | script.
startboolnoIf true, immediately enter recording. Default false.
idempotency_keystringnoPass via header Idempotency-Key: instead.

​
Response 201

{
  "id": "ses_01HZ...",
  "workflow": "process_invoice",
  "status": "created",
  "metadata": { ... },
  "actor": { ... },
  "started_at": null,
  "stopped_at": null,
  "duration_ms": 0,
  "frame_count": 0,
  "event_count": 0,
  "created_at": "2026-05-07T14:01:33Z"
}

​
Start a session

POST /v1/sessions/{id}/start
No body. Returns the updated session with status: "recording".

​
Stop a session

POST /v1/sessions/{id}/stop
No body. Idempotent. Returns the session with status: "stopped" (transitions to sealed once indexing finishes — typically within seconds).

​
Tag a session

POST /v1/sessions/{id}/tags
Content-Type: application/json

{
  "name": "submitted_for_approval",
  "data": { "approver": "anna@acme.com" }
}
Tags can be applied while recording or after sealing.

​
Get a session

GET /v1/sessions/{id}
Returns the session object. Pass ?include=events,tags,frames_summary to embed related data.

​
List sessions

GET /v1/sessions

​
Query

ParamNotes
workflowFilter to one or more slugs. Repeat the param for multiple.
statuscreated | recording | stopped | sealed.
outcomesuccess | error | abandoned. Derived from tags + detected events.
actor.kindhuman | model | script.
sinceISO timestamp or relative duration (30d, 1h).
untilISO timestamp.
tagSessions carrying a specific tag.
limit1–500. Default 100.
cursorFrom the previous response’s next_cursor.

​
Response 200

{
  "data": [ { "id": "ses_01HZ...", ... } ],
  "next_cursor": "eyJ0aW1lc3RhbXAiOiAi...",
  "has_more": true
}

​
Delete a session

DELETE /v1/sessions/{id}
Soft-deletes for 30 days. After 30 days the underlying frames and events are purged irrecoverably. The session id remains queryable in audit logs. To hard-delete immediately: 
DELETE /v1/sessions/{id}?hard=true
Requires admin scope.

​
Bulk operations

Stop multiple in-progress sessions at once: 
POST /v1/sessions:batch_stop

{ "ids": ["ses_a", "ses_b", "ses_c"] }
Useful for crash-recovery scripts that find and seal abandoned sessions.