Send Session Events
const url = 'https://agents.lumalabs.ai/v1/sessions/example/events';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', '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);}curl --request POST \ --url https://agents.lumalabs.ai/v1/sessions/example/events \ --header 'Authorization: Bearer <token>' \ --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" } ] }'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
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”Input events for one session, validated as a batch and dispatched in order.
object
A message from the caller; opens or joins a run.
object
Run this capability on the message. The result's run_id is the capability run.
object
The capability's slug from GET /v1/apps, or 'slug@version' to pin the release.
Typed fields matching the capability's intake input_schema. Absent, the message content is the brief.
object
Extra standing instructions for the capability's own work.
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:
Stop the current turn, or with target_run_id that one run. tree also stops descendant sessions.
object
The run to cancel: a brief, a generate run or a capability run on this session. Absent, the current turn is interrupted.
The result of a custom tool the session asked the caller to run.
object
The caller's answer to a review gate.
object
object
One of the app's typed commands, run against the session outside a turn.
object
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
The command the app authorizes the call as.
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
Identifier of the offered quote, echoed back on accept.
Responses
Section titled “ Responses ”Successful Response
One ack per input event, in request order.
object
The acknowledgement for one user.message.
object
Why the input was rejected.
object
Structured detail for an error. The precondition arm carries the two revisions.
object
Jobs a refused user.command had already started; they run on and can be polled.
Event id, present when the input was recorded.
Present when accepted or replayed.
object
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.
Feed seq, present when the input was recorded.
The acknowledgement for one user.interrupt.
object
Why the input was rejected.
object
Structured detail for an error. The precondition arm carries the two revisions.
object
Jobs a refused user.command had already started; they run on and can be polled.
Event id, present when the input was recorded.
Present when accepted or replayed.
object
Feed seq, present when the input was recorded.
The acknowledgement for one user.tool_result.
object
Why the input was rejected.
object
Structured detail for an error. The precondition arm carries the two revisions.
object
Jobs a refused user.command had already started; they run on and can be polled.
Event id, present when the input was recorded.
Present when accepted or replayed.
object
Feed seq, present when the input was recorded.
The acknowledgement for one user.gate_verdict.
object
Why the input was rejected.
object
Structured detail for an error. The precondition arm carries the two revisions.
object
Jobs a refused user.command had already started; they run on and can be polled.
Event id, present when the input was recorded.
Present when accepted or replayed.
object
Feed seq, present when the input was recorded.
The acknowledgement for one user.command.
object
Why the input was rejected.
object
Structured detail for an error. The precondition arm carries the two revisions.
object
Jobs a refused user.command had already started; they run on and can be polled.
Event id, present when the input was recorded.
Present when accepted or replayed.
object
object
Feed seq, present when the input was recorded.
The acknowledgement for one user.consent.
object
Why the input was rejected.
object
Structured detail for an error. The precondition arm carries the two revisions.
object
Jobs a refused user.command had already started; they run on and can be polled.
Event id, present when the input was recorded.
Present when accepted or replayed.
object
Which offer the quote was: the deferred finals quote, or a top-up to a running session.
Feed seq, present when the input was recorded.
Example
{ "data": [ { "status": "accepted", "type": "user.message" } ]}Validation Error
object
object
object
Examplegenerated
{ "detail": [ { "ctx": {}, "input": "example", "loc": [ "example" ], "msg": "example", "type": "example" } ]}