POST /v1/agents/sessions

Record an agent session

Access

Authenticated

agent:create

Cost

Free

Rate limit

20 / minute per account

Quota

None

Write the summary row for a finished agent session (goal spec, outcome, the R2 transcript key, the project it created). The account and acting member are taken from the credential; the x-vamo-actor tag it ran under is recorded. The full transcript lives in R2 — this is the queryable index, not the system of record.

Request body `RecordAgentSessionRequest`

sessionId string required

Your own identifier for the session being recorded.

max 200 chars
goalSpec string required

What the session was trying to achieve.

onboardingnew-project
outcome string required

How it ended.

completedabandoned
r2Key string required

Where the session transcript is stored.

max 200 chars
projectId string

The project this session belonged to, when there was one.

max 16 chars
startedAt string required

When the session started, as an ISO 8601 instant.

max 40 chars
finishedAt string required

When it finished, as an ISO 8601 instant.

max 40 chars

Responses

201 The recorded session summary
- id string required
  
  The stored record id.
- sessionId string required
  
  The session identifier you supplied, echoed back.
- outcome string required
  
  The recorded outcome.
- createdAt string required
  
  When the record was written, as an ISO 8601 instant.
401 No or invalid credential
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.
403 Missing agent:create
- code string required
  
  Stable machine-readable error code. Branch on this, never on the numeric status.
  
  bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_error
- message string required
  
  Human-readable explanation of the refusal.
- status integer required
  
  The HTTP status code, repeated in the body.
- remedy object
  
  A self-serve path forward, when one exists (a 402 points at the credit top-up).
  - kind string required
    
    What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.
    
    topupconnect_mailbox
  - url string required
    
    Where to go to clear the condition: an API path, or a web app page when only a person can.

Request body RecordAgentSessionRequest

Responses

Request body `RecordAgentSessionRequest`