Laddr REST API
Base URL: http://localhost:8000
GET /
Returns basic API information such as name, version, and documentation links.
Response Example:
{
"service": "Laddr API",
"version": "0.8.0",
"status": "running",
"dashboard": "http://localhost:5173",
"docs": "/docs"
}
GET /api/health
Checks the health of the Laddr system and its connected services such as the database, message bus, and storage backend.
Response Example:
{
"status": "ok",
"version": "0.8.0",
"components": {
"database": db_type,
"storage": storage_type,
"message_bus": queue_type
}
}
POST /api/jobs
Submit a new job for execution by providing the pipeline name and input data.
Request Body Example:
{
"pipeline_name": "text_analysis_agent",
"inputs": {
"text": "Analyze this message for sentiment"
}
}
Response Example:
{
"job_id": "job_1b203f",
"status": "queued",
"created_at": "2025-11-08T18:45:00Z"
}
GET /api/jobs
Fetch a list of recent jobs with pagination support.
Query Parameters:
limit(optional): Number of jobs to return (default: 50)offset(optional): Skip a number of jobs (default: 0)
Response Example:
[
{
"job_id": "job_1b203f",
"pipeline_name": "text_analysis_agent",
"status": "completed",
"created_at": "2025-11-08T18:45:00Z"
},
{
"job_id": "job_1b202b",
"pipeline_name": "image_classification_agent",
"status": "failed",
"created_at": "2025-11-08T18:40:00Z"
}
]
GET /api/jobs/{job_id}
Retrieve details for a specific job, including inputs, outputs, and execution metadata.
Response Example:
{
"job_id": "uuid",
"status": "completed",
"pipeline_name": "analyzer",
"inputs": {"numbers": [1,2,3,4,5]},
"outputs": {"sum": 15, "average": 3.0},
"error": null,
"created_at": "2025-11-03T16:40:04.630542Z",
"completed_at": "2025-11-03T16:40:05.234720Z",
"token_usage": {
"prompt_tokens": 100,
"completion_tokens": 50,
"total_tokens": 150
}
}
POST /api/jobs/{job_id}/replay
Replay a previous job.
Request Body Example:
{
"job_id": "...",
"request: True
}
Response Example:
{
"job_id": "uuid (new or same)",
"status": "completed",
"result": "Job result",
"replayed": true,
"original_job_id": "original-uuid"
}
POST /api/prompts
Submit a new prompt execution request.
Supports both single-agent and sequential multi-agent execution modes.
Request Body Example:
{
"prompt_name": "writer",
"inputs": {"task": "Write a haiku"}
"mode": "single" // or "sequential"
"agents": ["analyzer", "writer"] // optional for sequential
}
Response Example:
{
"prompt_id": "uuid",
"status": "running",
"agent": "writer",
"mode": "single",
"agents": ["writer"]
}
GET /api/prompts?limit=50
Retrieve a list of recent prompt executions.
Query Parameters:
limit(optional): Number of prompts to return (default: 50)offset(optional): Skip a number of prompts (default: 0)
Response Example:
{
"prompts": [
{
"prompt_id": "uuid",
"status": "completed",
"prompt_name": "writer",
"created_at": "2025-11-03T16:39:52.113651Z",
"completed_at": "2025-11-03T16:39:54.234720Z"
}
],
"limit": 50
}
GET /api/prompts/{prompt_id}
Get the current status, outputs, and trace summary of a specific prompt execution.
Response Example:
{
"prompt_id": "uuid",
"status": "completed",
"prompt_name": "writer",
"inputs": {"task": "Write a haiku"},
"outputs": {"result": "Haiku text..."},
"error": null,
"created_at": "2025-11-03T16:39:52.113651Z",
"completed_at": "2025-11-03T16:39:54.234720Z",
"token_usage": {
"prompt_tokens": 150,
"completion_tokens": 75,
"total_tokens": 225
}
}
GET /api/agents
List all registered agents with metadata and available tools.
Response Example:
{
"agents": [
{
"name": "writer",
"role": "Content Writer",
"goal": "Generate high-quality content",
"status": "active",
"tools": ["format_json", "parse_csv"],
"last_seen": "2025-11-03T16:30:00.000000Z"
}
]
}
GET /api/agents/{agent_name}/chat
Send a chat message to a specific agent and receive its reply.
Query Parameters:
message: The text message to sendtimeout: Optional response timeout (seconds)wait: boolean value
Response Example:
// wait=true (successful)
{
"task_id": "uuid",
"status": "completed",
"result": "Agent's response text or structured data",
"agent": "writer"
}
// wait=false (async)
{
"task_id": "uuid",
"status": "submitted"
}
// timeout
{
"task_id": "uuid",
"status": "timeout",
"message": "Agent did not respond in time"
}
GET /api/traces
Retrieve a list of trace events across all agents and jobs.
Query Parameters:
limit(optional): Number of traces to returnjob_id(optional): Filter by job IDagent(optional): Filter by agent name
Response Example:
{
"traces": [
{
"id": 510,
"job_id": "d780d103-a860-4536-98a7-1deed7097cb9",
"agent_name": "writer",
"event_type": "task_error",
"payload": {
"error": "LLM generation failed: ...",
"worker": "writer",
"ended_at": "2025-11-03T16:40:07.323933Z"
},
"timestamp": "2025-11-03T16:40:07.324541Z"
}
]
}
GET /api/traces/grouped?limit=50
Retrieve traces grouped by job ID, showing all events related to each execution.
Query Parameters:
limit(optional): Number of traces to return
Response Example:
{
"grouped_traces": [
{
"job_id": "d780d103-a860-4536-98a7-1deed7097cb9",
"trace_count": 2,
"agents": ["writer"],
"start_time": "2025-11-03T16:40:07.315138Z",
"end_time": "2025-11-03T16:40:07.324541Z",
"traces": [
{
"id": 509,
"job_id": "d780d103-a860-4536-98a7-1deed7097cb9",
"agent_name": "writer",
"event_type": "task_start",
"payload": {...},
"timestamp": "2025-11-03T16:40:07.315138Z"
},
{
"id": 510,
"job_id": "d780d103-a860-4536-98a7-1deed7097cb9",
"agent_name": "writer",
"event_type": "task_error",
"payload": {...},
"timestamp": "2025-11-03T16:40:07.324541Z"
}
]
}
]
}
GET /api/traces/{trace_id}
Retrieve details of a specific trace, including payload, timestamps, and linked job.
Response Example:
{
"id": 510,
"job_id": "d780d103-a860-4536-98a7-1deed7097cb9",
"agent_name": "writer",
"event_type": "task_error",
"payload": {
"error": "LLM generation failed: openai package not installed",
"worker": "writer",
"ended_at": "2025-11-03T16:40:07.323933Z"
},
"timestamp": "2025-11-03T16:40:07.324541Z"
}
GET /api/metrics
Get aggregated system metrics.
Response Example:
{
"total_jobs": 16,
"avg_latency_ms": 0,
"active_agents_count": 5,
"cache_hits": 0,
"tool_calls": 0,
"timestamp": "2025-11-03T16:40:30.429696Z"
}
GET /api/responses/{task_id}/resolved
Retrieve a resolved response payload, including any data that was offloaded to object storage.
Response Example:
// Inline response
{
"task_id": "uuid",
"offloaded": false,
"pointer": null,
"data": {
"result": "Agent response data"
}
}
// Offloaded response
{
"task_id": "uuid",
"offloaded": true,
"pointer": {
"bucket": "laddr",
"key": "responses/task-uuid",
"size_bytes": 524288
},
"data": {
"result": "Large agent response data..."
}
}