HTTP API reference

Exact request/response shapes for the AgentOS HTTP API. For when to use each, read the concepts first: Invoking hosted agents and Reporting runs.

• Base URL: https://agentos-ai.dev
• Auth: Authorization: Bearer <key> — agent key (aos_agent_…) for ingest, agent or workspace key (aos_ws_…) for invoke. See Authentication.
• Envelope: every response is { "data": …, "error": … }.

---

Ingest API

Report runs your own code executes (non-hosted agents). Guide: Reporting runs.

Start a run

POST /api/ingest/v1/run/start

{
  "agent_id": "uuid",
  "trigger_type": "sdk",
  "input": { "query": "Hello" },
  "external_run_id": "optional-correlation-id"
}

trigger_type: "manual" | "scheduled" | "webhook" | "sdk" (default "sdk").

Response

{ "data": { "run_id": "uuid" }, "error": null }

Emit events

POST /api/ingest/v1/events

{
  "run_id": "uuid",
  "events": [
    {
      "type": "step.completed",
      "level": "info",
      "payload": { "step": "fetch-data", "rows": 42 },
      "occurred_at": "2026-05-11T20:00:00.000Z"
    }
  ]
}

level: "debug" | "info" | "warn" | "error". events is an array — batch multiple. See Events.

Complete a run

POST /api/ingest/v1/run/complete

{ "run_id": "uuid", "output": { "result": "Done" } }

Fail a run

POST /api/ingest/v1/run/fail

{
  "run_id": "uuid",
  "error_message": "Something went wrong",
  "error_detail": { "step": "fetch" }
}

Create / update a task

POST /api/ingest/v1/tasks

{
  "run_id": "uuid",
  "task": {
    "id": "uuid",
    "name": "parse-pdf",
    "status": "running",
    "input": { "file": "report.pdf" }
  }
}

status: "pending" | "running" | "completed" | "failed" | "skipped". Call again with a terminal status to update. See Tasks.

---

Invoke API

Ask AgentOS to run a hosted agent and return its output. Guide: Invoking hosted agents.

Invoke a hosted agent

POST /api/v1/agents/:agentId/invoke

Requires a workspace key (aos_ws_…) or an agent key scoped to that agent. Only runtime_type: hosted agents.

{
  "input": { "query": "Summarise this" },
  "prompt_variables": { "SHEET_ID": "1pjdT1FADq-..." },
  "session_id": "uuid",
  "stream": false,
  "parent_run_id": "uuid"
}

Field	Type	Notes
input	object	Defaults to {}.
prompt_variables	{ KEY: string }	Optional; fills {{KEY}} placeholders. Prompt variables.
session_id / start_session	uuid / bool	Server-managed conversation memory. Memory.
external_user_id	string	Your id for the session's end-user; only with session_id/start_session.
history	array	Client-managed history; mutually exclusive with session_id.
parent_run_id	uuid	Link as a child run (agent-to-agent).
stream	boolean	SSE token/tool stream; incompatible with output_schema agents.

Response — completed

{ "data": { "run_id": "uuid", "output": { "summary": "…" }, "session_id": "uuid" }, "error": null }

Response — paused (HTTP 202)

{ "data": { "run_id": "uuid", "awaiting_approval": { "approval_id": "uuid" }, "output": null }, "error": null }

{ "data": { "run_id": "uuid", "awaiting_input": { "request_id": "uuid", "question": "…", "options": ["…"] }, "output": null }, "error": null }

awaiting_input.question is always present; options only when the agent offered choices.

With stream: true the body is text/event-stream: chunk / tool events then a terminal done (or awaiting_approval / error). See Invoking hosted agents.

---

Error responses

{ "data": null, "error": { "code": "UNAUTHENTICATED", "message": "Invalid or revoked key." } }

Code	HTTP	Meaning
UNAUTHENTICATED	401	Missing, invalid, or revoked key
FORBIDDEN	403	Key scoped to a different agent, or no workspace
NOT_FOUND	404	Agent or run not found
VALIDATION_ERROR	400	Bad request payload, or invoking a non-hosted / paused agent
RATE_LIMITED	429	Too many requests