Skip to main content
POST
Invoke an agent (async)

Authorizations

X-API-Key
string
header
required

Body

application/json
user_id
string
required

Your user's ID.

Example:

"user_123"

soul
string
required

The soul name to invoke.

Example:

"advisor"

input
string
required

The task or message for the agent.

Example:

"Research our top 5 competitors and summarise findings."

role
string
default:default

Memory and session scope. Defaults to default.

session_id
string

Session ID for conversation continuity.

callback_url
string<uri>

Optional URL to POST the result to when the job completes. Receives the same shape as the poll response.

Response

Job queued successfully.

job_id
string

Unique job ID. Use to poll status.

Example:

"2e4edc0c-8597-4e04-bf0a-c16349c6d35e"

status
enum<string>

Always pending on creation.

Available options:
pending
poll_url
string

Convenience URL for polling this job.

Example:

"/v1/agent/jobs/2e4edc0c-8597-4e04-bf0a-c16349c6d35e"