Search documentation
karat

+

K

User Documentation ↗
Version 2.0

Send Event

POST/api/v2/agents/agentSessions/{agentSessionId}/sendEvent
Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Send an event to the specified Agent session. Handling an event runs Agent logic and may modify platform data. An accepted result confirms that the event was accepted for handling. Retry a sessionNotReady result after a short delay.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:agents-write.

Path parameters

agentSessionId
string

Identifies an Agent session.

Query parameters

preview
booleanoptional

Enables the use of preview functionality.

Request body

SendEventRequest
object
Hide child attributes

Hide child attributes

event
object

An event sent to an Agent session.

Show child attributes

Show child attributes

Response body

SendEventResponse
object

The response to sending an event.

Hide child attributes

Hide child attributes

result
union

The result of sending an event. Indicates whether the event was accepted for asynchronous handling. A sessionNotReady status means the session has not started and cannot accept events yet. Retry after a short delay.

Show child attributes

Show child attributes

Examples

Request

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 curl -X POST \ \t-H "Content-type: application/json" \ \t-H "Authorization: Bearer $TOKEN" \ "https://$HOSTNAME/api/v2/agents/agentSessions/3fa85f64-5717-4562-b3fc-2c963f66afa6/sendEvent?preview=true" \ -d '{ "event": { "id": "b6d7e105-1793-47e9-a34b-72ecce7aef20", "eventType": "@platform/send-user-message", "payload": { "parts": [ { "type": "text", "text": "Where is my order?" } ] } } }'

Response

Copied!
1 2 3 4 5 6 { "result": { "type": "accepted", "consistencyKey": "cK_v1_eyJzZXF1ZW5jZU51bWJlciI6NDJ9" } }

Error responses

Error Name
SendEventPermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionCould not sendEvent the AgentSession.
ParametersagentSessionId
AgentSessionNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given AgentSession could not be found.
ParametersagentSessionId