HTTP API

This page lists the complete HTTP surface exposed by tirea-agentos-server.

Conventions

Error response shape:

{ "error": "<message>" }

Stream responses use text/event-stream.
Query limit is clamped to 1..=200.
Canonical Run API and A2A task APIs rely on the configured ThreadReader/state store.

Endpoint Map

Health:

GET /health

Threads:

GET /v1/threads
GET /v1/threads/summaries
GET /v1/threads/:id
GET /v1/threads/:id/messages
POST /v1/threads/:id/interrupt
GET /v1/threads/:id/mailbox
PATCH /v1/threads/:id/metadata
DELETE /v1/threads/:id

Canonical runs:

GET /v1/runs
GET /v1/runs/:id
POST /v1/runs
POST /v1/runs/:id/inputs
POST /v1/runs/:id/cancel

AG-UI:

POST /v1/ag-ui/agents/:agent_id/runs
GET /v1/ag-ui/threads/:id/messages

AI SDK v6:

POST /v1/ai-sdk/agents/:agent_id/runs
GET /v1/ai-sdk/agents/:agent_id/chats/:chat_id/stream (legacy: /runs/:chat_id/stream)
GET /v1/ai-sdk/threads/:id/messages

A2A:

GET /.well-known/agent-card.json
GET /v1/a2a/agents
GET /v1/a2a/agents/:agent_id/agent-card
POST /v1/a2a/agents/:agent_id/message:send
GET /v1/a2a/agents/:agent_id/tasks/:task_id
POST /v1/a2a/agents/:agent_id/tasks/:task_id:cancel

Core Examples

Health:

curl -i http://127.0.0.1:8080/health

List thread projections:

curl 'http://127.0.0.1:8080/v1/threads?offset=0&limit=50&parent_thread_id=thread-root'

Load raw thread messages:

curl 'http://127.0.0.1:8080/v1/threads/thread-1/messages?after=10&limit=20&order=asc&visibility=all&run_id=run-1'

Interrupt thread (cancel active run and supersede queued entries):

curl -X POST http://127.0.0.1:8080/v1/threads/thread-1/interrupt

Response (202):

{
  "status": "interrupt_requested",
  "thread_id": "thread-1",
  "generation": 3,
  "cancelled_run_id": "run-1",
  "superseded_pending_count": 1,
  "superseded_pending_entry_ids": ["entry-2"]
}

List thread mailbox entries:

curl 'http://127.0.0.1:8080/v1/threads/thread-1/mailbox?offset=0&limit=50&status=queued&origin=external'

Query params: offset, limit (clamped 1..=200, default 50), status (queued, claimed, accepted, superseded, cancelled, dead_letter), origin (external, internal, none, default external), visibility (internal, none, default all).

Stream Run Endpoints

AI SDK v6 stream (id/messages payload):

curl -N \
  -H 'content-type: application/json' \
  -d '{"id":"thread-1","runId":"run-1","messages":[{"id":"u1","role":"user","content":"hello"}]}' \
  http://127.0.0.1:8080/v1/ai-sdk/agents/assistant/runs

AI SDK decision forwarding to an active run:

curl -X POST \
  -H 'content-type: application/json' \
  -d '{"id":"thread-1","runId":"run-1","messages":[{"role":"assistant","parts":[{"type":"tool-approval-response","approvalId":"fc_perm_1","approved":true}]}]}' \
  http://127.0.0.1:8080/v1/ai-sdk/agents/assistant/runs

AI SDK regenerate-message:

curl -X POST \
  -H 'content-type: application/json' \
  -d '{"id":"thread-1","trigger":"regenerate-message","messageId":"m_assistant_1"}' \
  http://127.0.0.1:8080/v1/ai-sdk/agents/assistant/runs

AI SDK resume stream for active chat id:

curl -N http://127.0.0.1:8080/v1/ai-sdk/agents/assistant/chats/thread-1/stream

AG-UI stream:

curl -N \
  -H 'content-type: application/json' \
  -d '{"threadId":"thread-2","runId":"run-2","messages":[{"role":"user","content":"hello"}],"tools":[]}' \
  http://127.0.0.1:8080/v1/ag-ui/agents/assistant/runs

Canonical Run API

Start run:

curl -N \
  -H 'content-type: application/json' \
  -d '{"agentId":"assistant","threadId":"thread-1","messages":[{"role":"user","content":"hello"}]}' \
  http://127.0.0.1:8080/v1/runs

List runs:

curl 'http://127.0.0.1:8080/v1/runs?thread_id=thread-1&status=done&origin=ag_ui&limit=20'

Forward decisions or continue:

curl -X POST \
  -H 'content-type: application/json' \
  -d '{"decisions":[{"target_id":"fc_perm_1","decision_id":"d1","action":"resume","result":{"approved":true},"updated_at":1760000000000}]}' \
  http://127.0.0.1:8080/v1/runs/run-1/inputs

Cancel:

curl -X POST http://127.0.0.1:8080/v1/runs/run-1/cancel

A2A

Gateway discovery card:

curl -i http://127.0.0.1:8080/.well-known/agent-card.json

Submit task:

curl -X POST \
  -H 'content-type: application/json' \
  -d '{"input":"hello from a2a"}' \
  http://127.0.0.1:8080/v1/a2a/agents/assistant/message:send

Get task projection:

curl http://127.0.0.1:8080/v1/a2a/agents/assistant/tasks/<task_id>

Cancel task:

curl -X POST http://127.0.0.1:8080/v1/a2a/agents/assistant/tasks/<task_id>:cancel

Validation Failures

AI SDK v6:

empty id -> 400 (id cannot be empty)
no user input and no decisions and not regenerate -> 400
trigger=regenerate-message without valid messageId -> 400
legacy payload (sessionId/input) -> 400 (legacy AI SDK payload shape is no longer supported; use id/messages)

AG-UI:

empty threadId -> 400
empty runId -> 400

Run API:

empty agentId on run creation -> 400
/inputs with both messages and decisions empty -> 400
/inputs with messages but missing agentId -> 400

A2A:

action not message:send -> 400
decision-only submit without taskId -> 400
cancel path without :cancel suffix -> 400

Shared:

unknown agent_id -> 404
unknown run/task id -> 404

Keyboard shortcuts

Tirea Documentation