Skip to content

Send Session Events

POST
/v1/sessions/{session_id}/events
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.

session_id
required
Session Id
string
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

A message from the caller; opens or joins a run.

object
asset_ids
Asset Ids
Array<string>
attachment_ids
Attachment Ids
Array<string>
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<string>
<= 4 items
idempotency_key
Idempotency Key
string
<= 255 characters
type
required
Type
string
Allowed value: user.message

Successful Response

Media typeapplication/json
SendSessionEventsResponse

One ack per input event, in request order.

object
data
required
Data
Array
One of: discriminator: type
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<string>
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
Example
{
"data": [
{
"status": "accepted",
"type": "user.message"
}
]
}

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
"detail": [
{
"ctx": {},
"input": "example",
"loc": [
"example"
],
"msg": "example",
"type": "example"
}
]
}