API and structured output

Channels are for people. The API is for systems, such as a CI pipeline, a ticketing system, a nightly job or your own product, and returns a result they can parse. Runs are the same governed conversations as in xpander Chat, with the agent’s skills, approvals, budget and record. If the caller can’t hold an API key, use the webhook.

Start a run

Endpoint	Returns
`POST /v1/agents/{agent_id}/invoke`	Waits and returns the finished task, with `result`
`POST /v1/agents/{agent_id}/invoke/stream`	Server-sent events until `task_finished`: text, skill calls, plan updates, sub-tasks, approvals
`POST /v1/agents/{agent_id}/invoke/async`	The task at once, status `pending`. Poll `GET /v1/tasks/{task_id}`.

Authenticate with x-api-key and an organization API key from Platform > Organization > Access. A key can be limited to named agents. The Developer access row also shows POST /v1/agents/{agent_id}/conversations/invoke. It sends a message in a conversation and returns the reply with the conversation record, and it is what xpander Chat uses. Continue with the next message’s conversation_id. /invoke starts a one-shot task and returns the task record. Pass an existing conversation id to continue. Both take the same key.

curl -X POST 'https://api.xpander.ai/v1/agents/<agent_id>/invoke' \
  -H "x-api-key: $XPANDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "Summarize the failures in last night'\''s test run"}}'

Behind a load balancer with an idle timeout, a synchronous call whose turn runs longer than the timeout never returns. An AWS ALB, for example, answers 504 after 60 seconds by default. For turns that may take more than a minute, use /invoke/async and poll the task, or use the streaming endpoint.

Other body fields:

Field	What it does
`input.files`	URLs the agent reads
`input.user`	Who the run is for, so the record and per-person credentials resolve to them
`id`	An existing conversation id, to continue it
`llm_model_provider`, `llm_model_name`	The model for this run
`sub_tasks_mode`	`sync`, `async` or `auto`, for sub-tasks the agent creates
`additional_context`, `instructions_override`, `title`, `tool_call_limit`	Also accepted
`version=draft`	Query parameter: run the staged version

A dropped stream doesn’t stop the run. The answer lands in the task. On a self-hosted location, use that location’s API address.

Read tasks

GET /v1/tasks lists tasks (filter by agent, user, parent task, status, dates). GET /v1/tasks/{task_id} returns one, and /thread, /thread/full (with sub-tasks) and /llm_usage (model calls with cost) add detail. POST /v1/tasks/{task_id}/stop stops it. Statuses: pending, executing, paused, error, failed, completed, stopped. Full reference: REST API.

Get told when a run ends

Set the agent’s notification_settings with PATCH /v1/agents/{agent_id} to send the outcome to email, Slack or your webhook, on success, error and budget events. The webhook gets the task’s name, subject, body, type, duration, result and link, with your headers:

{"notification_settings": {"on_success": {"webhook": [{"url": "https://ci.example.com/hooks/xpander", "headers": {"X-Token": "..."}}]},
                           "on_error":   {"email": [{"to": "oncall@example.com"}]}}}

Structured output

Four ways to get the same shape every time. Start with the first:

The agent’s output format. In Agent settings > Advanced > Output format, choose Structured output and give a JSON Schema (Generate with AI drafts one). Every answer is validated and repaired when possible, on every channel. The API returns the JSON as result. Chat channels show prose and keep the JSON in the record. Use this when a system parses the answer.

Agent settings, Output format row with Default, Markdown and Structured output (selected), a JSON schema editor holding the seeded AI Agent Result schema, Learn more and Generate with AI — Output format set to Structured output, with the seeded schema. Shown with sample data.

Required sections in the instructions. For a human-readable answer with fixed sections, write them into the static prompt. Instructions are never trimmed.
A format per channel. A routed Slack channel can carry its own format, overriding the agent’s. See Channels.
A schema per call. output_format and output_schema in the invoke body apply to that run only. Turns through the agent’s conversation use the agent-level schema, so prefer the agent setting.

Over the webhook, a structured result comes back as JSON, and ?getter=result.<field> extracts one field.

Workflows

All of this also works for workflows, at POST /v1/workflows/{workflow_id}/invoke.

Start here

Build an agent

Company Brain

Channels

Run and monitor

xpander Desktop

API and structured output

Start a run

Read tasks

Get told when a run ends

Structured output

Workflows

Next steps

Browse the REST API

Run an agent from a webhook

​Start a run

​Read tasks

​Get told when a run ends

​Structured output

​Workflows

​Next steps

Browse the REST API

Run an agent from a webhook

Start a run

Read tasks

Get told when a run ends

Structured output

Workflows

Next steps