API Reference¶

Complete reference for all HTTP endpoints exposed by the Agentomatic platform. All per-agent endpoints are prefixed with /api/v1/{agent_name}/.

Platform Endpoints¶

These endpoints are global — not scoped to a specific agent.

Method	Path	Description
`GET`	`/`	Platform info and version
`GET`	`/health`	Aggregated health check
`GET`	`/ready`	Lightweight liveness/readiness probe
`GET`	`/readiness`	Kubernetes readiness probe
`GET`	`/status`	Unified status dashboard (HTML)
`GET`	`/api/v1/status`	Unified platform status (JSON)
`GET`	`/docs`	OpenAPI interactive docs
`GET`	`/.well-known/agent.json`	A2A protocol discovery
`GET`	`/api/v1/agents`	List all registered agents
`GET`	`/api/v1/storage/stats`	Storage backend statistics
`GET`	`/metrics`	Prometheus metrics endpoint

Resource surfaces. Dynamic resources appear in the live /openapi.json only after they are discovered. /{name} below is a registered resource name; the /async and /batch variants require the task subsystem (enabled by the standard platform configuration).

Method	Path	Description
`POST`/`GET`/`DELETE`	`/api/v1/tasks[/{id}][/events\\|/result\\|/cancel]`	Task board — submit, poll, stream, cancel, delete
`GET`/`POST`	`/api/v1/plugins[/{name}/health\\|/model_card\\|/predict[/(async\\|batch)]\\|/reload]`	ML plugins — list, inspect, predict, reload one or all (`POST /api/v1/plugins/reload`)
`GET`/`POST`/`DELETE`	`/api/v1/pipelines/...`	Pipelines — list, validate a draft, save/delete a definition, run sync/async/batch, inspect, visualize; see the pipeline API table
`GET`/`POST`	`/api/v1/ingestors` and `/api/v1/ingestion/{name}/...`	Always-available ingestor registry plus discovered-resource info, health, sync/async/batch run routes
Declared by endpoint	`/api/v1/endpoints[/{name}{path}]`	Custom endpoints — list, call; `GET`/`HEAD` input is query-bound and write-method input is JSON
`GET`/`POST`	`/api/v1/logs[/{id}\\|/analyze\\|/analysis]`	Invocation logs across resources (`?resource=` + `name=`; when `logs_history` on)
`GET`/`POST`	`/api/v1/control[/...]`	Control plane (when enabled)

Dedicated guides

Full details live in Tasks & Execution Modes, Status Dashboard, Ingestion & RAG, Pipelines, ML Plugins, and Custom Endpoints. The Frontend API Guide has copy-paste TypeScript for async task polling and SSE.

`GET /`¶

Platform information.

Response:

{
  "platform": "Agentomatic",
  "version": "1.0.0",
  "agents": 3
}

`GET /health`¶

Aggregated health check across all agents.

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "agents": {
    "my_agent": {"status": "healthy"},
    "rag_agent": {"status": "healthy"}
  }
}

`GET /readiness`¶

Kubernetes readiness probe. Returns 200 when the platform is ready to accept traffic.

curl http://localhost:8000/readiness

`GET /api/v1/agents`¶

List all registered agents with metadata.

curl http://localhost:8000/api/v1/agents

Response:

{
  "agents": {
    "my_agent": {
      "name": "my_agent",
      "slug": "my-agent",
      "description": "A helpful assistant",
      "version": "1.0.0",
      "framework": "langgraph"
    }
  }
}

Per-Agent Endpoints¶

All prefixed with /api/v1/{agent_name}/.

Execution¶

`POST /invoke`¶

Invoke agent synchronously. Returns the full response after execution completes.

Request Body — AgentInvokeRequest:

Field	Type	Required	Default	Description
`query`	`string`	✅	—	User query or input
`user_id`	`string`		`"default-user"`	User identifier
`context`	`object`		`{}`	Additional context for the agent
`thread_id`	`string \\| null`		auto-generated	Thread ID for continuity
`prompt_version`	`string`		`"v1"`	Prompt version to use
`temperature`	`float \\| null`		`null`	Temperature override (0.0–2.0)
`max_tokens`	`int \\| null`		`null`	Max tokens override
`metadata`	`object`		`{}`	Extra metadata

Example:

curl -X POST http://localhost:8000/api/v1/my_agent/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the capital of France?",
    "user_id": "user-123",
    "thread_id": "thread-abc",
    "temperature": 0.7
  }'

Response Body — AgentInvokeResponse:

Field	Type	Description
`response`	`string`	Agent response text
`output`	`any \\| null`	Structured `state_to_output()` payload when available
`agent_type`	`string`	Agent slug identifier
`thread_id`	`string \\| null`	Thread ID used
`suggestions`	`string[]`	Follow-up suggestions
`citations`	`object[]`	Source citations
`steps_taken`	`string[]`	Processing steps
`context`	`any`	Context data (RAG docs, search results)
`metadata`	`object`	Response metadata incl. `prompt_version`
`duration_ms`	`float`	Processing time in milliseconds

Response Example:

{
  "response": "The capital of France is Paris.",
  "output": null,
  "agent_type": "my-agent",
  "thread_id": "thread-abc",
  "suggestions": ["Tell me about Paris landmarks"],
  "citations": [],
  "steps_taken": ["retrieve", "generate"],
  "context": {},
  "metadata": {"prompt_version": "v1"},
  "duration_ms": 142.5
}

Error Responses:

Status	Description
`404`	Agent not found
`202`	Execution suspended (HITL) — returns `approval_id`
`500`	Agent invocation failed

`POST /invoke/stream`¶

Invoke agent with Server-Sent Events (SSE) streaming.

Request Body: Same as POST /invoke (AgentInvokeRequest).

Example:

curl -X POST http://localhost:8000/api/v1/my_agent/invoke/stream \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain quantum computing"}'

SSE Response:

id: 1
data: {"response": "", "steps_taken": ["retrieve"]}

id: 2
data: {"response": "Quantum computing uses...", "steps_taken": ["retrieve", "generate"]}

id: 3
data: [DONE]

Headers:

Header	Value
`Content-Type`	`text/event-stream`
`X-Agent`	Agent name
`X-Stream-Id`	Identity to replay this stream with
`Cache-Control`	`no-cache`

`GET /invoke/stream/{stream_id}`¶

Re-send the frames a previous /invoke/stream already produced, using the X-Stream-Id that response carried. Accepts ?since= or Last-Event-ID and returns only the frames after that point; 404 once the stream is no longer retained.

A retained stream is scoped to the agent that produced it and the principal it was produced for. Replaying another agent's stream — or another caller's — returns 404, the same answer as an id that does not exist, so the response never confirms that someone else's stream is there.

curl -N "http://localhost:8000/api/v1/my_agent/invoke/stream/stream_a1b2c3d4?since=2"

Replay is not resumption

This returns what was already produced. It does not restart the run: the agent execution is bound to the request that was cancelled, so a client that disconnects mid-answer loses the generation, and replay recovers only the part that had been emitted.

For a stream that keeps working across a dropped connection, submit the work as a task and follow the task's events — that path is resumable end to end:

TASK=$(curl -sX POST http://localhost:8000/api/v1/my_agent/invoke/async \
  -H 'Content-Type: application/json' -d '{"query": "..."}' | jq -r .id)
curl -N "http://localhost:8000/api/v1/tasks/$TASK/events"

See Tasks & Execution Modes.

`POST /chat`¶

Session-aware chat with automatic conversation memory. When a thread store is configured, this endpoint automatically loads history, invokes the agent, and persists messages.

Request Body — AgentChatRequest:

Field	Type	Required	Default	Description
`content`	`string`	✅	—	User message
`user_id`	`string`		`"default-user"`	User identifier
`thread_id`	`string \\| null`		auto-generated	Thread ID
`context`	`object`		`{}`	Context for agent code
`metadata`	`object`		`{}`	Extra metadata
`messages`	`object[] \\| null`		`null`	Override: supply own message history
`include_history`	`boolean`		`true`	Load history from store
`max_history`	`int \\| null`		`null`	Max messages to load
`persist`	`boolean`		`true`	Auto-save messages to store
`prompt_version`	`string`		`"v1"`	Prompt version

Example:

curl -X POST http://localhost:8000/api/v1/my_agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is our PTO policy?",
    "thread_id": "thread_abc123",
    "user_id": "user_42",
    "context": {"department": "engineering"}
  }'

Response:

{
  "response": "Based on our handbook, the PTO policy is...",
  "thread_id": "thread_abc123",
  "agent_type": "hr-agent",
  "suggestions": ["Ask about sick days"],
  "citations": [],
  "steps_taken": ["search_policy", "generate"],
  "context": {},
  "duration_ms": 234.5,
  "metadata": {"prompt_version": "v1"},
  "history_loaded": 12
}

Inspection¶

`GET /health`¶

Per-agent health check.

curl http://localhost:8000/api/v1/my_agent/health

{
  "status": "healthy",
  "agent": "my_agent",
  "framework": "langgraph"
}

`GET /config`¶

Get agent configuration.

curl http://localhost:8000/api/v1/my_agent/config

{
  "agent": "my_agent",
  "config": {
    "model": "gpt-4o",
    "temperature": 0.7,
    "prompt_version": "v1"
  }
}

`GET /prompts`¶

List available prompt versions and the active version.

curl http://localhost:8000/api/v1/my_agent/prompts

{
  "agent": "my_agent",
  "versions": ["v1", "v2"],
  "active": "v1"
}

A2A Protocol¶

`GET /card`¶

A2A Agent Card — machine-readable agent description for agent-to-agent discovery.

curl http://localhost:8000/api/v1/my_agent/card

{
  "name": "my-agent",
  "description": "A helpful assistant",
  "version": "1.0.0",
  "framework": "langgraph",
  "capabilities": {
    "streaming": true,
    "chat": true,
    "invoke": true,
    "a2a": true,
    "stateTransitionHistory": true,
    "pushNotifications": true,
    "resumableStreams": true
  },
  "endpoints": {
    "invoke": "/api/v1/my_agent/invoke",
    "chat": "/api/v1/my_agent/chat",
    "stream": "/api/v1/my_agent/invoke/stream",
    "stream_replay": "/api/v1/my_agent/invoke/stream/{stream_id}",
    "health": "/api/v1/my_agent/health",
    "card": "/api/v1/my_agent/card",
    "a2a_tasks": "/api/v1/my_agent/a2a/tasks",
    "a2a_events": "/api/v1/my_agent/a2a/tasks/{task_id}/events"
  },
  "metadata": {}
}

stateTransitionHistory, pushNotifications and resumableStreams all depend on the task subsystem. When it is disabled they report false and the a2a_* endpoints are omitted — the card describes what this deployment actually serves, so a client is never sent down a path that answers 501.

Discovery returns the same card

GET /.well-known/agent.json — the canonical A2A discovery document — renders each agent through the same builder, so its cards are identical to this one, wrapped in a platform envelope:

{"platform": "My Platform", "version": "1.0.0", "agents": {"my_agent": { ... }}}

`POST /a2a/tasks`¶

Submit an A2A protocol task.

Request Body — A2ATaskRequest:

Field	Type	Required	Description
`message`	`object`	✅	A2A message — protocol `parts`, or a `content` / `text` string
`metadata`	`object`		Extra metadata

The protocol form carries text in parts; the simplified content string is also accepted. A message with no readable text is rejected with 422 rather than silently running the agent on an empty query.

# Protocol form
curl -X POST http://localhost:8000/api/v1/my_agent/a2a/tasks \
  -H "Content-Type: application/json" \
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Analyze this dataset"}]}}'

# Simplified form
curl -X POST http://localhost:8000/api/v1/my_agent/a2a/tasks \
  -H "Content-Type: application/json" \
  -d '{"message": {"content": "Analyze this dataset"}}'

{
  "task_id": "task_a1b2c3d4e5f6",
  "status": "completed",
  "result": "Analysis complete..."
}

`GET /a2a/tasks/{task_id}`¶

Get A2A task status.

These per-agent A2A routes — status, events and cancel — only accept tasks submitted to this agent. A task belonging to another agent answers 404, the same as an id that does not exist. The shared task board at /api/v1/tasks/{id} is cross-agent by design and is unaffected.

curl http://localhost:8000/api/v1/my_agent/a2a/tasks/task_a1b2c3d4e5f6

{
  "task_id": "task_a1b2c3d4e5f6",
  "status": "completed",
  "message": "Task tracking requires storage backend"
}

`GET /a2a/tasks/{task_id}/events`¶

Subscribe — or re-subscribe — to an A2A task's progress over Server-Sent Events. Frames are A2A task objects (submitted, working, completed, failed, canceled), and the stream ends with data: [DONE]. Returns 501 without the task subsystem, 404 for an unknown task.

Every frame carries an SSE id: holding the event's monotonic sequence, so a client that loses the connection resumes precisely instead of restarting:

# Subscribe
curl -N http://localhost:8000/api/v1/my_agent/a2a/tasks/task_a1b2c3d4e5f6/events

# Re-subscribe after event 4 — replays 5 onwards, then goes live
curl -N -H "Last-Event-ID: 4" \
  http://localhost:8000/api/v1/my_agent/a2a/tasks/task_a1b2c3d4e5f6/events
curl -N "http://localhost:8000/api/v1/my_agent/a2a/tasks/task_a1b2c3d4e5f6/events?since=4"

{"task_id": "task_a1b2c3d4e5f6", "sequence": 5, "status": "working",
 "progress": {"percent": 60.0, "message": "step 3"}}

A reconnect whose resume point has already been evicted receives a {"event": "truncated"} frame followed by the current task object, so a client is never handed a partial history as if it were complete. See Tasks & Execution Modes for retention limits and the multi-worker caveat.

`POST /a2a/tasks/{task_id}/cancel`¶

Request cooperative cancellation of an in-flight A2A task. This endpoint is available when the task subsystem is configured; it returns 501 when the agent is running without task persistence.

curl -X POST http://localhost:8000/api/v1/my_agent/a2a/tasks/task_a1b2c3d4e5f6/cancel

Thread Management¶

`POST /threads`¶

Create a new conversation thread.

Request Body — CreateThreadRequest:

Field	Type	Default	Description
`thread_id`	`string \\| null`	auto-generated	Custom thread ID
`user_id`	`string`	`"default-user"`	User identifier
`title`	`string \\| null`	`null`	Thread title
`metadata`	`object`	`{}`	Extra metadata

curl -X POST http://localhost:8000/api/v1/my_agent/threads \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_42", "title": "Onboarding questions"}'

`GET /threads`¶

List threads, optionally filtered by user.

# All threads for this agent
curl http://localhost:8000/api/v1/my_agent/threads

# Filter by user
curl http://localhost:8000/api/v1/my_agent/threads?user_id=user_42

{
  "threads": [
    {
      "id": "thread_abc123",
      "user_id": "user_42",
      "agent_name": "my_agent",
      "title": "Onboarding questions",
      "created_at": "2026-06-18T20:00:00Z"
    }
  ],
  "count": 1
}

`GET /threads/{thread_id}`¶

Get a specific thread.

curl http://localhost:8000/api/v1/my_agent/threads/thread_abc123

`PATCH /threads/{thread_id}`¶

Update thread title or metadata.

Request Body — UpdateThreadRequest:

Field	Type	Description
`title`	`string \\| null`	New title
`metadata`	`object \\| null`	New metadata (replaces existing)

curl -X PATCH http://localhost:8000/api/v1/my_agent/threads/thread_abc123 \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title"}'

`DELETE /threads/{thread_id}`¶

Delete a thread and all its messages.

curl -X DELETE http://localhost:8000/api/v1/my_agent/threads/thread_abc123

{"status": "deleted", "thread_id": "thread_abc123"}

`GET /threads/{thread_id}/messages`¶

Get messages with pagination.

Query Param	Type	Default	Description
`limit`	`int`	`100`	Max messages to return
`offset`	`int`	`0`	Offset for pagination

curl "http://localhost:8000/api/v1/my_agent/threads/thread_abc/messages?limit=20&offset=0"

{
  "thread_id": "thread_abc",
  "messages": [
    {"role": "user", "content": "Hello", "timestamp": "..."},
    {"role": "assistant", "content": "Hi there!", "timestamp": "..."}
  ],
  "count": 2,
  "limit": 20,
  "offset": 0
}

`DELETE /threads/{thread_id}/messages`¶

Clear all messages in a thread (keeps the thread itself).

curl -X DELETE http://localhost:8000/api/v1/my_agent/threads/thread_abc/messages

{"status": "cleared", "thread_id": "thread_abc"}

`GET /threads/{thread_id}/summary`¶

Get or generate a conversation summary.

curl http://localhost:8000/api/v1/my_agent/threads/thread_abc/summary

{
  "thread_id": "thread_abc",
  "summary": "User asked about PTO policy and sick days. Agent provided handbook references."
}

Thread Forking & Lineage¶

`POST /threads/{thread_id}/fork`¶

Fork a thread at a specific message index.

Request Body — ForkThreadRequest:

Field	Type	Required	Description
`message_index`	`int`	✅	Fork point (0-indexed)
`new_thread_id`	`string \\| null`		Custom ID for fork
`title`	`string \\| null`		Title for forked thread

curl -X POST http://localhost:8000/api/v1/my_agent/threads/thread_abc/fork \
  -H "Content-Type: application/json" \
  -d '{"message_index": 2, "title": "A/B Test Variant"}'

{
  "id": "thread_xyz789",
  "parent_thread_id": "thread_abc",
  "fork_message_index": 2,
  "title": "A/B Test Variant"
}

`GET /threads/{thread_id}/lineage`¶

Get the full ancestry tree (ancestors and descendants).

curl http://localhost:8000/api/v1/my_agent/threads/thread_xyz789/lineage

{
  "thread_id": "thread_xyz789",
  "ancestors": [{"id": "thread_abc", "title": "Original"}],
  "descendants": []
}

Human-in-the-Loop (HITL)¶

`GET /threads/{thread_id}/pending`¶

List pending HITL approvals for a thread.

curl http://localhost:8000/api/v1/my_agent/threads/thread_001/pending

{
  "thread_id": "thread_001",
  "pending": [
    {
      "id": "tx_984712",
      "node_name": "financial_transfer",
      "state_snapshot": {"amount": 1000, "recipient": "..."},
      "created_at": "2026-06-18T20:00:00Z"
    }
  ],
  "count": 1
}

`POST /threads/{thread_id}/approve`¶

Approve a suspended state and resume execution.

Request Body — ApproveSuspendedRequest:

Field	Type	Required	Default	Description
`approval_id`	`string`	✅	—	ID of the suspended state
`approved`	`boolean`		`true`	Approval flag
`context`	`object`		`{}`	Additional context to merge

curl -X POST http://localhost:8000/api/v1/my_agent/threads/thread_001/approve \
  -H "Content-Type: application/json" \
  -d '{
    "approval_id": "tx_984712",
    "context": {"approved_limit": 500}
  }'

Behavior:

Retrieves the suspended state snapshot
Deletes the pending record
Merges context into state.metadata
Sets state.metadata.hitl_approved = true
Resumes graph execution with the updated state
Returns the final AgentInvokeResponse

Re-suspension

If the resumed execution hits another HITL node, a new 202 Accepted response is returned with a new approval_id.

`POST /threads/{thread_id}/reject`¶

Reject a suspended state and discard the execution context.

Request Body — RejectSuspendedRequest:

Field	Type	Required	Description
`approval_id`	`string`	✅	ID of the suspended state
`reason`	`string \\| null`		Rejection reason

curl -X POST http://localhost:8000/api/v1/my_agent/threads/thread_001/reject \
  -H "Content-Type: application/json" \
  -d '{"approval_id": "tx_984712", "reason": "Amount exceeds policy"}'

{
  "status": "rejected",
  "approval_id": "tx_984712",
  "reason": "Amount exceeds policy"
}

Feedback¶

`POST /feedback`¶

Submit user feedback on an agent response.

Request Body — FeedbackRequest:

Field	Type	Default	Description
`user_id`	`string`	`"anonymous"`	User identifier
`rating`	`int \\| null`	`null`	1–5 star rating
`comment`	`string \\| null`	`null`	Text comment
`correction`	`string \\| null`	`null`	Correct answer
`feedback_type`	`string`	`"thumbs"`	`thumbs \\| rating \\| correction \\| comment`
`query`	`string`	`""`	Original query
`response`	`string`	`""`	Agent response being rated
`thread_id`	`string \\| null`	`null`	Thread ID
`metadata`	`object`	`{}`	Extra metadata

curl -X POST http://localhost:8000/api/v1/my_agent/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "comment": "Very helpful!",
    "query": "What is PTO policy?",
    "response": "Our PTO policy states...",
    "thread_id": "thread_abc"
  }'

{"status": "recorded", "feedback_id": "fb_abc123"}

`GET /feedback`¶

List feedback for this agent.

Query Param	Type	Default	Description
`limit`	`int`	`50`	Max records to return

curl "http://localhost:8000/api/v1/my_agent/feedback?limit=20"

`GET /feedback/export`¶

Export feedback as JSONL for optimization datasets (DeepEval, fine-tuning).

curl http://localhost:8000/api/v1/my_agent/feedback/export

{
  "agent": "my_agent",
  "format": "jsonl",
  "data": "{\"query\":\"...\",\"response\":\"...\",\"rating\":5}\n{...}",
  "count": 42
}

Optimization¶

`POST /optimize/invoke`¶

Full-context invocation for optimization pipelines. Returns retrieval context, tool calls, reasoning steps — everything needed for DeepEval metrics.

Request Body — OptimizeInvokeRequest:

Field	Type	Required	Default	Description
`query`	`string`	✅	—	User query
`system_prompt_override`	`string \\| null`		`null`	System prompt to inject
`user_id`	`string`		`"optimizer"`	User ID
`context`	`object`		`{}`	Additional context
`include_retrieval_context`	`boolean`		`true`	Return RAG context
`include_steps`	`boolean`		`true`	Return execution steps

curl -X POST http://localhost:8000/api/v1/my_agent/optimize/invoke \
  -H "Content-Type: application/json" \
  -d '{"query": "What is quantum computing?"}'

Response Body — OptimizeInvokeResponse:

{
  "response": "Quantum computing is...",
  "retrieval_context": ["Document 1 content...", "Document 2 content..."],
  "tool_calls": [{"name": "search", "args": {"query": "quantum"}}],
  "steps_taken": ["retrieve", "rerank", "generate"],
  "reasoning": "First I searched for...",
  "citations": [{"source": "doc1.pdf", "page": 3}],
  "duration_ms": 456.7,
  "metadata": {}
}

Studio Debug API¶

All Studio endpoints are prefixed with /studio/.

Discovery¶

`GET /studio/info`¶

Platform-level metadata and capabilities.

curl http://localhost:8000/studio/info

{
  "version": "1.0.0",
  "platform_title": "Agentomatic Platform",
  "agent_count": 3,
  "capabilities": ["studio", "storage", "streaming"]
}

`GET /studio/agents`¶

List all agents with debugging capabilities.

curl http://localhost:8000/studio/agents

[
  {
    "name": "my_agent",
    "slug": "my-agent",
    "description": "A helpful assistant",
    "version": "1.0.0",
    "framework": "langgraph",
    "capabilities": ["graph", "streaming", "checkpoints", "state", "breakpoints", "hitl"],
    "has_graph": true,
    "has_config": true,
    "has_prompts": true
  }
]

Graph Inspection¶

`GET /studio/agents/{name}/graph`¶

Get the agent's execution graph topology.

curl http://localhost:8000/studio/agents/my_agent/graph

{
  "agent_name": "my_agent",
  "nodes": [
    {"id": "__start__", "name": "__start__", "type": "start", "metadata": {}},
    {"id": "retrieve", "name": "retrieve", "type": "agent", "metadata": {}},
    {"id": "__end__", "name": "__end__", "type": "end", "metadata": {}}
  ],
  "edges": [
    {"id": "edge_0", "source": "__start__", "target": "retrieve", "condition": null}
  ],
  "entry_point": "__start__",
  "end_points": ["__end__"]
}

`GET /studio/agents/{name}/schemas`¶

Get JSON schemas for agent input/output models.

curl http://localhost:8000/studio/agents/my_agent/schemas

`GET /studio/agents/{name}/config`¶

Get agent configuration.

curl http://localhost:8000/studio/agents/my_agent/config

Runs¶

`POST /studio/agents/{name}/runs`¶

Create and execute a run synchronously.

Request Body — StudioRunRequest:

Field	Type	Required	Default	Description
`query`	`string`	✅	—	User query
`user_id`	`string`		`"default-user"`	User ID
`thread_id`	`string \\| null`		auto-generated	Thread ID
`context`	`object`		`{}`	Additional context
`metadata`	`object`		`{}`	Extra metadata
`prompt_version`	`string`		`"v1"`	Prompt version
`breakpoints`	`string[]`		`[]`	Node names to break at
`checkpoint_id`	`string \\| null`		`null`	Checkpoint to resume from

curl -X POST http://localhost:8000/studio/agents/my_agent/runs \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello", "breakpoints": ["human_review"]}'

`POST /studio/agents/{name}/runs/stream`¶

Create and stream a run via SSE with full event detail.

curl -X POST http://localhost:8000/studio/agents/my_agent/runs/stream \
  -H "Content-Type: application/json" \
  -d '{"query": "Analyze this data"}'

Headers:

Header	Value
`Content-Type`	`text/event-stream`
`X-Studio-Run-Id`	Run identifier
`X-Accel-Buffering`	`no`

`GET /studio/agents/{name}/runs`¶

List recent runs for an agent.

Query Param	Type	Default	Description
`limit`	`int`	`50`	Max runs to return

curl "http://localhost:8000/studio/agents/my_agent/runs?limit=10"

`GET /studio/agents/{name}/runs/{run_id}`¶

Get a specific run with all events.

curl http://localhost:8000/studio/agents/my_agent/runs/run_abc123

State & Checkpoints¶

`GET /studio/agents/{name}/threads/{thread_id}/state`¶

Get the latest thread state.

curl http://localhost:8000/studio/agents/my_agent/threads/thread_001/state

{
  "thread_id": "thread_001",
  "agent_name": "my_agent",
  "state": {
    "messages": [...],
    "response": "Last response",
    "steps_taken": ["retrieve", "generate"]
  },
  "timestamp": "2026-06-18T20:00:00Z",
  "checkpoint_id": "cp_abc123"
}

`POST /studio/agents/{name}/threads/{thread_id}/state`¶

Apply a partial state update.

Request Body — StudioStateUpdate:

Field	Type	Required	Description
`updates`	`object`	✅	Key-value pairs to merge

curl -X POST http://localhost:8000/studio/agents/my_agent/threads/thread_001/state \
  -H "Content-Type: application/json" \
  -d '{"updates": {"response": "Manually overridden response"}}'

`GET /studio/agents/{name}/threads/{thread_id}/history`¶

List checkpoint history for a thread.

curl http://localhost:8000/studio/agents/my_agent/threads/thread_001/history

[
  {
    "id": "cp_003",
    "thread_id": "thread_001",
    "step": 2,
    "state": {...},
    "metadata": {},
    "parent_id": "cp_002",
    "timestamp": "2026-06-18T20:00:03Z"
  },
  {
    "id": "cp_002",
    "thread_id": "thread_001",
    "step": 1,
    "state": {...},
    "metadata": {},
    "parent_id": "cp_001",
    "timestamp": "2026-06-18T20:00:02Z"
  }
]

Resume (HITL / Interrupt)¶

`POST /studio/agents/{name}/threads/{thread_id}/resume`¶

Resume a LangGraph execution that was paused by an interrupt.

Request Body — StudioResumeRequest:

Field	Type	Required	Default	Description
`value`	`any`		`null`	Human response or approval value
`action`	`string`		`"approve"`	`"approve"` or `"reject"`

curl -X POST \
  http://localhost:8000/studio/agents/my_agent/threads/thread_001/resume \
  -H "Content-Type: application/json" \
  -d '{"value": {"approved": true, "notes": "Looks good"}, "action": "approve"}'

Uses LangGraph's Command(resume=value) to continue execution from the interrupt point. Returns an SSE stream of continued execution events.

Error Codes Reference¶

HTTP Status	Meaning	Common Causes
`200`	Success	Normal response
`202`	Accepted (Suspended)	HITL suspension — execution paused for approval
`400`	Bad Request	Thread storage not configured, no fields to update
`404`	Not Found	Agent, thread, run, or suspended state not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Agent invocation failed, graph error

Error Response Format¶

{
  "detail": "Error description string"
}

HITL Suspension Response (202)¶

{
  "detail": {
    "status": "suspended",
    "approval_id": "tx_984712",
    "node_name": "financial_transfer",
    "message": "Transaction requires human approval."
  }
}

SSE Event Types Reference¶

Events streamed via Studio's /runs/stream endpoint:

Event Type	Node Field	Description
`run_start`	—	Run execution begins
`node_start`	Node name	Graph node begins execution
`node_end`	Node name	Graph node completes (includes output)
`message_chunk`	LLM name	Token streamed from chat model
`subagent_start`	Subagent name	Subgraph execution begins
`subagent_end`	Subagent name	Subgraph execution completes
`task_update`	`planning:{tool}`	Planning tool (write_todos) detected
`breakpoint_hit`	Interrupted node	Execution paused at breakpoint
`run_complete`	—	Run execution finishes successfully
`run_error`	—	Run execution failed (includes error)
`done`	—	Stream complete

Topic	Link
Frontend integration guide	Frontend API Guide
HITL workflows	Platform Features
Storage backends	Storage Backends
Studio debug API	Agentomatic Studio
Agent structure	Agent Structure

API Reference¶

Platform Endpoints¶

GET /¶

GET /health¶

GET /readiness¶

GET /api/v1/agents¶

Per-Agent Endpoints¶

Execution¶

POST /invoke¶

POST /invoke/stream¶

GET /invoke/stream/{stream_id}¶

POST /chat¶

Inspection¶

GET /health¶

GET /config¶

GET /prompts¶

A2A Protocol¶

GET /card¶

POST /a2a/tasks¶

GET /a2a/tasks/{task_id}¶

GET /a2a/tasks/{task_id}/events¶

POST /a2a/tasks/{task_id}/cancel¶

Thread Management¶

POST /threads¶

GET /threads¶

GET /threads/{thread_id}¶

PATCH /threads/{thread_id}¶

DELETE /threads/{thread_id}¶

GET /threads/{thread_id}/messages¶

DELETE /threads/{thread_id}/messages¶

GET /threads/{thread_id}/summary¶

Thread Forking & Lineage¶

POST /threads/{thread_id}/fork¶

GET /threads/{thread_id}/lineage¶

Human-in-the-Loop (HITL)¶

GET /threads/{thread_id}/pending¶

POST /threads/{thread_id}/approve¶

POST /threads/{thread_id}/reject¶

Feedback¶

POST /feedback¶

GET /feedback¶

GET /feedback/export¶

Optimization¶

POST /optimize/invoke¶

Studio Debug API¶

Discovery¶

GET /studio/info¶

GET /studio/agents¶

Graph Inspection¶

GET /studio/agents/{name}/graph¶

GET /studio/agents/{name}/schemas¶

GET /studio/agents/{name}/config¶

Runs¶

POST /studio/agents/{name}/runs¶

POST /studio/agents/{name}/runs/stream¶

GET /studio/agents/{name}/runs¶

GET /studio/agents/{name}/runs/{run_id}¶

State & Checkpoints¶

GET /studio/agents/{name}/threads/{thread_id}/state¶

POST /studio/agents/{name}/threads/{thread_id}/state¶

GET /studio/agents/{name}/threads/{thread_id}/history¶

Resume (HITL / Interrupt)¶

POST /studio/agents/{name}/threads/{thread_id}/resume¶

Error Codes Reference¶

Error Response Format¶

HITL Suspension Response (202)¶

SSE Event Types Reference¶

📚 Related Documentation¶

`GET /`¶

`GET /health`¶

`GET /readiness`¶

`GET /api/v1/agents`¶

`POST /invoke`¶

`POST /invoke/stream`¶

`GET /invoke/stream/{stream_id}`¶

`POST /chat`¶

`GET /health`¶

`GET /config`¶

`GET /prompts`¶

`GET /card`¶

`POST /a2a/tasks`¶

`GET /a2a/tasks/{task_id}`¶

`GET /a2a/tasks/{task_id}/events`¶

`POST /a2a/tasks/{task_id}/cancel`¶

`POST /threads`¶

`GET /threads`¶

`GET /threads/{thread_id}`¶

`PATCH /threads/{thread_id}`¶

`DELETE /threads/{thread_id}`¶

`GET /threads/{thread_id}/messages`¶

`DELETE /threads/{thread_id}/messages`¶

`GET /threads/{thread_id}/summary`¶

`POST /threads/{thread_id}/fork`¶

`GET /threads/{thread_id}/lineage`¶

`GET /threads/{thread_id}/pending`¶

`POST /threads/{thread_id}/approve`¶

`POST /threads/{thread_id}/reject`¶

`POST /feedback`¶

`GET /feedback`¶

`GET /feedback/export`¶

`POST /optimize/invoke`¶

`GET /studio/info`¶

`GET /studio/agents`¶

`GET /studio/agents/{name}/graph`¶

`GET /studio/agents/{name}/schemas`¶

`GET /studio/agents/{name}/config`¶

`POST /studio/agents/{name}/runs`¶

`POST /studio/agents/{name}/runs/stream`¶

`GET /studio/agents/{name}/runs`¶

`GET /studio/agents/{name}/runs/{run_id}`¶

`GET /studio/agents/{name}/threads/{thread_id}/state`¶

`POST /studio/agents/{name}/threads/{thread_id}/state`¶

`GET /studio/agents/{name}/threads/{thread_id}/history`¶

`POST /studio/agents/{name}/threads/{thread_id}/resume`¶