Skip to main content
POST
Invoke an agent

Authorizations

X-API-Key
string
header
required

Body

application/json
user_id
string
required

Your user's ID. Scopes memory and session to this user.

Example:

"user_123"

soul
string
required

The soul name to invoke.

Example:

"support"

input
string
required

The user's message or task input.

Example:

"My invoice looks wrong."

role
string
default:default

Memory and session scope within the user. Defaults to default.

session_id
string

Session ID for multi-turn conversation continuity. Omit for a stateless invocation.

Example:

"chat_abc123"

stream
boolean

Set true to receive a streaming SSE response. Alternatively, send Accept: text/event-stream.

Response

Invocation completed. Returns JSON or SSE stream depending on request.

invocation_id
string

Unique ID for this invocation.

Example:

"a1b2c3d4-..."

output
string

The agent's final text response.

memory_delta
object

Memory keys written during this turn.

tool_calls
object[]
tokens_input
integer
tokens_output
integer
duration_ms
integer
session_id
string
status
enum<string>
Available options:
completed,
failed