HTTP API Reference
AgentVisor™ exposes an OpenAPI/REST transport (LangGraph Agent Protocol) on port 8090.
Base URL
http://localhost:8090
Authentication
When authentication is enabled, clients authenticate via OIDC:
# OIDC Bearer token
curl -H "Authorization: Bearer <token>" http://localhost:8090/agents
Endpoints
| Endpoint | Method | Description |
|---|---|---|
| Threads | ||
/threads | POST | Create thread |
/threads/{id} | GET | Get thread |
/threads/{id} | PATCH | Update thread |
/threads/{id} | DELETE | Delete thread |
/threads/{id}/copy | POST | Copy thread |
/threads/search | POST | Search threads |
/threads/{id}/history | GET, POST | Get checkpoint history |
| Runs (per thread) | ||
/threads/{id}/runs | POST | Create run |
/threads/{id}/runs | GET | List runs |
/threads/{id}/runs/{runId} | GET | Get run |
/threads/{id}/runs/{runId}/stream | GET | Stream run output |
/threads/{id}/runs/{runId}/cancel | POST | Cancel run |
| Stateless runs | ||
/runs | POST | Stateless run (async) |
/runs/wait | POST | Stateless run (sync) |
/runs/stream | POST | Stateless run (streaming) |
| Run by ID | ||
/runs/{id} | GET | Get run status |
/runs/{id}/wait | GET | Wait for run |
/runs/{id}/stream | GET | Stream run output |
/runs/{id}/cancel | POST | Cancel run |
/runs/{id} | DELETE | Delete run |
| State | ||
/threads/{id}/state | GET | Get state |
/threads/{id}/state | POST | Update state |
/threads/{id}/state/checkpoint | POST | Get state at a checkpoint/namespace |
/threads/{id}/state/{checkpoint_id} | GET | Get state at a checkpoint ID |
| Agents | ||
/agents | GET | List agents |
/agents/search | POST | Search agents |
/agents/{name} | GET | Get agent |
/agents/{name}/schemas | GET | Get schemas |
| Store | ||
/store/namespaces | POST | List namespaces |
/store/items | PUT | Put item |
/store/items | GET | Get item |
/store/items | DELETE | Delete item |
/store/items/search | POST | Search items |
| Tracing | ||
/traces/events/stream | GET | Stream gVisor seccheck trace events (SSE) |
| System | ||
/health | GET | Liveness check |
/ready | GET | Readiness probe |
/metrics | GET | Prometheus metrics |
/openapi.json | GET | OpenAPI spec |
/schema | GET | Aggregated agent schemas |
/swagger-ui/ | GET | Swagger UI |
Response Format
Success
{
"thread_id": "abc123",
"status": "idle",
"created_at": "2024-01-15T10:30:00Z",
"metadata": {"user": "alice"}
}
Error
{
"error": "thread not found",
"code": "not_found"
}
code is a lowercase snake_case string. Some low-level validation failures (e.g. a
malformed JSON body) are returned by generic request handling before an error code is
assigned and omit the code field, leaving only error.
Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 201 | Created (thread created, thread copied) |
| 202 | Accepted (run created or cancelled asynchronously) |
| 204 | No Content (thread/run deleted, store item put/deleted) |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden (policy denied) |
| 404 | Not found |
| 409 | Conflict (thread busy) |
| 413 | Payload too large |
| 429 | Rate limited |
| 500 | Internal error |
| 503 | Service unavailable |
| 504 | Timeout (e.g. wait/timeout exceeded) |
Error Codes
The code field on an error response is one of:
| Code | HTTP Status |
|---|---|
not_found | 404 |
invalid_input | 400 |
unauthorized | 401 |
forbidden | 403 |
conflict | 409 |
internal_error | 500 |
unavailable | 503 |
timeout | 504 |
rate_limited | 429 |
payload_too_large | 413 |
invalid_json | 400 |
json_depth_exceeded | 400 |
invalid_parameter | 400 |
connection_limit | 503 |
Interactive Documentation
Access Swagger UI at:
http://localhost:8090/swagger-ui/