Run an Agent

POST /api/run

The primary endpoint to send a message to your agent. By default it returns a Server-Sent Events (SSE) stream of AG-UI protocol events as the agent works.

Base URL: https://agent-api.auteryn.ai

Authenticate with a JWT from the API key exchange flow.

Tip

Need a fire-and-forget background run (e.g. from a webhook or worker, with the result delivered elsewhere)? Use the dedicated POST /api/run/async endpoint instead — it is purpose-built for that and returns 202 with the task/run IDs.

---

Request

POST https://agent-api.auteryn.ai/api/run
Authorization: Bearer <jwt>
X-Agent-Id: your-agent-uuid
Content-Type: application/json

Body:

{
  "messages": [
    {"role": "user", "content": "What are the open P1 GitHub issues?"}
  ],
  "task_id": "optional — continue an existing conversation",
  "mode": "auto",
  "stream": true
}

Field	Required	Description
messages	✅	Conversation messages. The last message must be from the user.
task_id	❌	Continue an existing conversation. Also accepted as threadId. Omit to start a new task.
mode	❌	auto, fast, or deep (default: auto). auto lets the smart router pick.
stream	❌	true for an SSE stream (default), false to dispatch to the background and return 202.
timezone	❌	IANA timezone (e.g. America/New_York) used for date-aware answers.

---

Responses

Streaming (stream: true)

Content-Type: text/event-stream

AG-UI protocol events stream as the agent works. Each line is a data: frame containing one JSON event (field names are snake_case):

data: {"type":"RUN_STARTED","thread_id":"task_xyz","run_id":"run_abc","mode":"fast"}

data: {"type":"TEXT_MESSAGE_START","message_id":"msg_1","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","message_id":"msg_1","delta":"Let me check the open bugs..."}

data: {"type":"TOOL_CALL_START","tool_call_id":"tc_1","tool_call_name":"github"}

data: {"type":"TOOL_CALL_END","tool_call_id":"tc_1"}

data: {"type":"TEXT_MESSAGE_END","message_id":"msg_1"}

data: {"type":"RUN_FINISHED","run_id":"run_abc"}

See the full event-type reference below.

Background (stream: false)

When stream: false, the run is dispatched to a background worker and the API returns 202 Accepted immediately with run metadata:

{
  "id": "run_abc123",
  "task_id": "task_xyz789",
  "type": "pending",
  "status": "pending",
  "routing_reason": "Background execution started",
  "stream_endpoint": null,
  "created_at": "2026-07-03T12:00:00Z"
}

Then follow the run with any of the poll / resume endpoints:

• GET /api/run/{task_id}/status — is a run active, and its progress
• GET /api/tasks/{task_id}/stream — SSE stream of the task’s events
• GET /api/runs/{run_id}/events — paginated JSON event history

Note

stream: false on /api/run is meant for interactive clients that will reconnect to the stream. For server-to-server / webhook-driven background work with callback delivery, prefer POST /api/run/async.

---

AG-UI event types

Events emitted on the SSE stream. Base events carry type and timestamp; listed fields are in addition to those.

type	Extra fields	Meaning
RUN_STARTED	thread_id, run_id, mode, routing_reason	Run began; mode is the resolved fast/deep.
RUN_FINISHED	run_id, result	Run completed successfully.
RUN_ERROR	message, code, run_id, details	Run failed. code defaults to EXECUTION_ERROR.
TEXT_MESSAGE_START	message_id, role	An assistant message is about to stream.
TEXT_MESSAGE_CONTENT	message_id, delta	A chunk of text to append.
TEXT_MESSAGE_END	message_id	The assistant message is complete.
TOOL_CALL_START	tool_call_id, tool_call_name, metadata	A tool call began.
TOOL_CALL_ARGS	tool_call_id, delta	Streaming JSON argument chunk.
TOOL_CALL_END	tool_call_id	Tool arguments are complete.
TOOL_CALL_RESULT	tool_call_id, content	Tool result (JSON string).
STATE_SNAPSHOT	state	Full run/UI state object.
STATE_DELTA	delta	Incremental state changes.
HEARTBEAT	—	Keepalive; no payload.
CUSTOM	name, data	Extension events — see below.

CUSTOM events wrap agent-specific signals under name, with the payload in data:

name	Meaning
THOUGHT	Reasoning / thinking step for display.
PLAN_CREATED	Deep-mode plan was created.
USER_INPUT_REQUIRED	Human-in-the-loop: the agent is blocked awaiting input. Respond via POST /api/tasks/{id}/input.
ARTIFACT_CREATED / ARTIFACT_UPDATED / ARTIFACT_REVISED / ARTIFACT_COMPLETED / ARTIFACT_PROGRESS / ARTIFACT_ERROR	Rich artifact lifecycle (chart, table, document, image, …).
USAGE	Credit / token usage for the run.
SYSTEM_STATUS	Sandbox, MCP, retry status for UI.
STOPPING	The run is being cancelled.

Caution

If you receive a CUSTOM event with name: "USER_INPUT_REQUIRED", the agent has paused and will not continue until you post the user’s answer. See the HITL flow.

---

Code examples

Python

import httpx, json, os

AGENT_ID = os.environ["AUTERYN_AGENT_ID"]
JWT = os.environ["AUTERYN_JWT"]  # from exchange/agent-token

with httpx.stream(
    "POST",
    "https://agent-api.auteryn.ai/api/run",
    headers={
        "Authorization": f"Bearer {JWT}",
        "X-Agent-Id": AGENT_ID,
    },
    json={
        "messages": [{"role": "user", "content": "What are the open P1 GitHub issues?"}],
        "stream": True,
    },
) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            print(event["type"], event)

JavaScript

const res = await fetch("https://agent-api.auteryn.ai/api/run", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUTERYN_JWT}`,
    "X-Agent-Id": process.env.AUTERYN_AGENT_ID,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [{ role: "user", content: "Summarize open issues" }],
    stream: true,
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  for (const frame of buffer.split("\n\n")) {
    if (frame.startsWith("data: ")) console.log(JSON.parse(frame.slice(6)));
  }
  buffer = buffer.endsWith("\n\n") ? "" : buffer.split("\n\n").pop();
}

cURL

curl -N -X POST https://agent-api.auteryn.ai/api/run \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Agent-Id: agent_xyz789" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Summarize open GitHub issues"}],"stream":true}'

(-N disables curl’s buffering so events print as they arrive.)

---

Rate limits & errors

POST /api/run is rate limited (default 30 requests/min per org+user). On 429 the response includes a Retry-After header. See the Errors & rate limits reference for the full list of status codes.