cURL — streaming

curl -X POST https://your-imp-host/agents/litellm/run/d4f7a2e1-6c3b-4a9e-8f21-0b5c9d7e3a10 \
  -H "x-api-key: sk_abc123.../my-key" \
  -H "Content-Type: application/json" \
  -H "stream: true" \
  -H "session: e7c3b8a2-0d4f-4b1e-9c72-3a6d5e8f1b20" \
  -d '{"message":{"id":"msg_01Ab","role":"user","parts":[{"type":"text","text":"Hello"}]}}'

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

"<string>"

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

Agents

Run an agent

Sends a message to an agent instance and returns the response. When the stream header is true, the response is an AI SDK UIMessage stream over SSE (text/event-stream); otherwise a sync JSON response is returned. The agent’s rights_mode controls whether an API key or session JWT is required — public agents allow unauthenticated calls. An agent-scoped API key is only valid for its bound agent instance. Supply the session header to persist messages to a session.

POST

agents

litellm

run

{instance}

cURL — streaming

curl -X POST https://your-imp-host/agents/litellm/run/d4f7a2e1-6c3b-4a9e-8f21-0b5c9d7e3a10 \
  -H "x-api-key: sk_abc123.../my-key" \
  -H "Content-Type: application/json" \
  -H "stream: true" \
  -H "session: e7c3b8a2-0d4f-4b1e-9c72-3a6d5e8f1b20" \
  -d '{"message":{"id":"msg_01Ab","role":"user","parts":[{"type":"text","text":"Hello"}]}}'

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

A valid request URL is required to generate request examples

"<string>"

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

{
  "detail": "<string>",
  "message": "<string>"
}

Authorizations

x-api-key

string

header

required

Organisation API key. Format: sk_<secret>/<keyname> — the secret portion, a literal slash, and the human-readable key name. The header exulu-api-key is accepted as an alias. A Bearer prefix is tolerated and stripped. Keys with an agent scope are only valid for the scoped agent instance.

Headers

stream

enum<string>

default:false

Set to true to receive a streaming SSE response (AI SDK UIMessage stream). Omit or set to false for a synchronous JSON response.

Available options:

true,

false

session

string<uuid>

Agent session ID. When provided, message history is loaded from and saved to the session. The caller must have write access to the session.

x-exulu-model-override

string

LiteLLM model ID to use for this request, overriding the model configured on the agent. Only accepted when the resolved model is permitted for the calling user.

Path Parameters

instance

string<uuid>

required

Agent ID (UUID).

Body

application/json

message

object

The user message to send. Used when session is set or when sending a single message without history.

Show child attributes

messages

object[]

Full conversation history. When provided without a session header and without a message field, the last element is used as the current message and the rest as prior context.

Show child attributes

customInstructions

string

Additional system instructions appended to the agent's base instructions for this run only.

disabledTools

string[]

Tool IDs to exclude from this run, even if enabled on the agent.

disabledSkills

string[]

Skill IDs to exclude from this run.

approvedTools

string[]

Tool call IDs that the user has pre-approved for execution without a confirmation prompt.

Response

Successful response. When stream: true the body is an AI SDK UIMessage stream (text/event-stream); each line is a server-sent event carrying a UIMessage part or finish chunk. When stream: false the body is a sync JSON object returned by provider.generateSync.

AI SDK UIMessage stream. Lines are SSE events; each event carries a serialised UIMessage part (text delta, tool-call, tool-result, finish-step, finish). The final finish event includes token usage in its messageMetadata.

Retrieve platform configuration

Compact a session