--- title: Send Session Events | Luma Agents --- POST /v1/sessions/{session\_id}/events Select code samplecURL (shell:curl) ```js const url = 'https://agents.lumalabs.ai/v1/sessions/example/events'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"events":[{"asset_ids":["example"],"attachment_ids":["example"],"capability":{"app":"example","input":{},"system_context":"example"},"content":"example","context_refs":["example"],"idempotency_key":"example","type":"user.message"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url https://agents.lumalabs.ai/v1/sessions/example/events \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "events": [ { "asset_ids": [ "example" ], "attachment_ids": [ "example" ], "capability": { "app": "example", "input": {}, "system_context": "example" }, "content": "example", "context_refs": [ "example" ], "idempotency_key": "example", "type": "user.message" } ] }' ``` - Productionagents.lumalabs.ai/v1/sessions/{session\_id}/events Send a session up to 20 input events: messages, interrupts, tool results, gate verdicts, commands and consent. Every event is validated and authorized before any is dispatched, so one invalid event fails the whole request and nothing runs. Valid events are dispatched in order; the first one refused is acked `rejected` and the rest `skipped`. A retry with the same `idempotency_key` is acked `replayed` with the original result; `SESSION.INPUT_IN_FLIGHT` and `SESSION.INPUT_OUTCOME_UNKNOWN` are retryable with that same key. ## Authorizations - **[BearerAuth](/api/agents/index.md#bearerauth)** ## Parameters ### Path Parameters **session\_id** required *Session Id* string ## Request Bodyrequired Media typeapplication/json *SendSessionEventsRequest* Input events for one session, validated as a batch and dispatched in order. object **events** required *Events* Array \>= 1 items <= 20 items One of: discriminator: type - [UserMessageInput](#tab-panel-0-0) - [UserInterruptInput](#tab-panel-0-1) - [UserToolResultInput](#tab-panel-0-2) - [UserGateVerdictInput](#tab-panel-0-3) - [UserCommandInput](#tab-panel-0-4) - [UserConsentInput](#tab-panel-0-5) *UserMessageInput* A message from the caller; opens or joins a run. object **asset\_ids** *Asset Ids* Array\ **attachment\_ids** *Attachment Ids* Array\ **capability** *CapabilityRequest* Run this capability on the message. The result's run\_id is the capability run. object **app** required *App* The capability's slug from GET /v1/apps, or 'slug\@version' to pin the release. string <= 128 characters **input** *Input* Typed fields matching the capability's intake input\_schema. Absent, the message content is the brief. object ***key*** additional properties any **system\_context** *System Context* Extra standing instructions for the capability's own work. string <= 32768 characters **content** required *Content* string **context\_refs** *Context Refs* Things of your team for the session's agent to follow on this message and the work it orders, each by the id its own list prints: brand\_kit: from GET /v1/brand-kits. Up to 4. Each is read as the message is sent, and what it says is stored ahead of your words as part of the message. One this team cannot read is not found. Naming the same kit again is how a session picks up an edit; a kit it already holds unchanged is named but not repeated. Array\ <= 4 items **idempotency\_key** *Idempotency Key* string <= 255 characters **type** required *Type* string Allowed value: user.message *UserInterruptInput* Stop the current turn, or with target\_run\_id that one run. tree also stops descendant sessions. object **idempotency\_key** *Idempotency Key* string <= 255 characters **target\_run\_id** *Target Run Id* The run to cancel: a brief, a generate run or a capability run on this session. Absent, the current turn is interrupted. string **tree** *Tree* boolean **type** required *Type* string Allowed value: user.interrupt *UserToolResultInput* The result of a custom tool the session asked the caller to run. object **idempotency\_key** *Idempotency Key* string <= 255 characters **invocation\_id** required *Invocation Id* string **result** required *Result* **type** required *Type* string Allowed value: user.tool\_result *UserGateVerdictInput* The caller's answer to a review gate. object **idempotency\_key** *Idempotency Key* string <= 255 characters **invocation\_id** required *Invocation Id* string **type** required *Type* string Allowed value: user.gate\_verdict **verdict** required *Verdict* object ***key*** additional properties any *UserCommandInput* One of the app's typed commands, run against the session outside a turn. object **command** required *Command* The command body in the app's command schema. Unless the body's own schema declares them, expected\_revision must match the plan artifact's revision before the command runs, and it and operation\_id are left out of the recorded input and its idempotency comparison. object ***key*** additional properties any **idempotency\_key** *Idempotency Key* string <= 255 characters **operation** required *Operation* The command the app authorizes the call as. string **type** required *Type* string Allowed value: user.command *UserConsentInput* The caller's answer to a billing offer the session's pending names by quote\_id. Names only the quote, never an amount: the server holds the offer's frozen terms. object **decision** required *Decision* string Allowed values: accept decline **idempotency\_key** *Idempotency Key* string <= 255 characters **quote\_id** required *Quote Id* Identifier of the offered quote, echoed back on accept. string **type** required *Type* string Allowed value: user.consent ## Responses ### 200 Successful Response Media typeapplication/json *SendSessionEventsResponse* One ack per input event, in request order. object **data** required *Data* Array One of: discriminator: type - [UserMessageAck](#tab-panel-1-0) - [UserInterruptAck](#tab-panel-1-1) - [UserToolResultAck](#tab-panel-1-2) - [UserGateVerdictAck](#tab-panel-1-3) - [UserCommandAck](#tab-panel-1-4) - [UserConsentAck](#tab-panel-1-5) *UserMessageAck* The acknowledgement for one user.message. object **error** *PublicError* Why the input was rejected. object **code** required *Code* string **details** *PublicErrorDetails* Structured detail for an error. The precondition arm carries the two revisions. object **current\_revision** *Current Revision* integer **expected\_revision** *Expected Revision* integer **job\_ids** *Job Ids* Jobs a refused user.command had already started; they run on and can be polled. Array\ **message** required *Message* string **retryable** required *Retryable* boolean **id** *Id* Event id, present when the input was recorded. string **result** *UserMessageResult* Present when accepted or replayed. object **message\_seq** *Message Seq* The message's position in the session's history. Absent when the message arrived during a turn, or while the session owes a tool result: it takes its position after that turn's reply, or right after the last owed tool result once it is delivered. integer **run\_id** *Run Id* string **seq** *Seq* Feed seq, present when the input was recorded. integer **status** required *Status* string Allowed values: accepted replayed rejected skipped **type** required *Type* string Allowed value: user.message *UserInterruptAck* The acknowledgement for one user.interrupt. object **error** *PublicError* Why the input was rejected. object **code** required *Code* string **details** *PublicErrorDetails* Structured detail for an error. The precondition arm carries the two revisions. object **current\_revision** *Current Revision* integer **expected\_revision** *Expected Revision* integer **job\_ids** *Job Ids* Jobs a refused user.command had already started; they run on and can be polled. Array\ **message** required *Message* string **retryable** required *Retryable* boolean **id** *Id* Event id, present when the input was recorded. string **result** *UserInterruptResult* Present when accepted or replayed. object **cancelled\_run\_ids** required *Cancelled Run Ids* Array\ **seq** *Seq* Feed seq, present when the input was recorded. integer **status** required *Status* string Allowed values: accepted replayed rejected skipped **type** required *Type* string Allowed value: user.interrupt *UserToolResultAck* The acknowledgement for one user.tool\_result. object **error** *PublicError* Why the input was rejected. object **code** required *Code* string **details** *PublicErrorDetails* Structured detail for an error. The precondition arm carries the two revisions. object **current\_revision** *Current Revision* integer **expected\_revision** *Expected Revision* integer **job\_ids** *Job Ids* Jobs a refused user.command had already started; they run on and can be polled. Array\ **message** required *Message* string **retryable** required *Retryable* boolean **id** *Id* Event id, present when the input was recorded. string **result** *UserToolResultResult* Present when accepted or replayed. object **seq** *Seq* Feed seq, present when the input was recorded. integer **status** required *Status* string Allowed values: accepted replayed rejected skipped **type** required *Type* string Allowed value: user.tool\_result *UserGateVerdictAck* The acknowledgement for one user.gate\_verdict. object **error** *PublicError* Why the input was rejected. object **code** required *Code* string **details** *PublicErrorDetails* Structured detail for an error. The precondition arm carries the two revisions. object **current\_revision** *Current Revision* integer **expected\_revision** *Expected Revision* integer **job\_ids** *Job Ids* Jobs a refused user.command had already started; they run on and can be polled. Array\ **message** required *Message* string **retryable** required *Retryable* boolean **id** *Id* Event id, present when the input was recorded. string **result** *UserGateVerdictResult* Present when accepted or replayed. object **seq** *Seq* Feed seq, present when the input was recorded. integer **status** required *Status* string Allowed values: accepted replayed rejected skipped **type** required *Type* string Allowed value: user.gate\_verdict *UserCommandAck* The acknowledgement for one user.command. object **error** *PublicError* Why the input was rejected. object **code** required *Code* string **details** *PublicErrorDetails* Structured detail for an error. The precondition arm carries the two revisions. object **current\_revision** *Current Revision* integer **expected\_revision** *Expected Revision* integer **job\_ids** *Job Ids* Jobs a refused user.command had already started; they run on and can be polled. Array\ **message** required *Message* string **retryable** required *Retryable* boolean **id** *Id* Event id, present when the input was recorded. string **result** *UserCommandResult* Present when accepted or replayed. object **job\_ids** required *Job Ids* Array\ **payload** required *Payload* object ***key*** additional properties any **seq** *Seq* Feed seq, present when the input was recorded. integer **status** required *Status* string Allowed values: accepted replayed rejected skipped **type** required *Type* string Allowed value: user.command *UserConsentAck* The acknowledgement for one user.consent. object **error** *PublicError* Why the input was rejected. object **code** required *Code* string **details** *PublicErrorDetails* Structured detail for an error. The precondition arm carries the two revisions. object **current\_revision** *Current Revision* integer **expected\_revision** *Expected Revision* integer **job\_ids** *Job Ids* Jobs a refused user.command had already started; they run on and can be polled. Array\ **message** required *Message* string **retryable** required *Retryable* boolean **id** *Id* Event id, present when the input was recorded. string **result** *UserConsentResult* Present when accepted or replayed. object **offer** required *ConsentOffer* Which offer the quote was: the deferred finals quote, or a top-up to a running session. string Allowed values: finals top\_up **seq** *Seq* Feed seq, present when the input was recorded. integer **status** required *Status* string Allowed values: accepted replayed rejected skipped **type** required *Type* string Allowed value: user.consent ##### Example ```json { "data": [ { "status": "accepted", "type": "user.message" } ] } ``` ### 422 Validation Error Media typeapplication/json *HTTPValidationError* object **detail** *Detail* Array\ *ValidationError* object **ctx** *Context* object **input** *Input* **loc** required *Location* Array **msg** required *Message* string **type** required *Error Type* string ##### Examplegenerated ```json { "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ] } ```