| # Laddr REST API |
|
|
| **Base URL:** `http://localhost:8000` |
|
|
| --- |
|
|
| ## `GET /` |
|
|
| Returns basic API information such as name, version, and documentation links. |
|
|
| **Response Example:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "pipeline_name": "text_analysis_agent", |
| "inputs": { |
| "text": "Analyze this message for sentiment" |
| } |
| } |
| ``` |
|
|
| **Response Example:** |
| ```json |
| { |
| "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:** |
| ```json |
| [ |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "job_id": "...", |
| "request: True |
| } |
| ``` |
| |
| **Response Example:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "prompt_name": "writer", |
| "inputs": {"task": "Write a haiku"} |
| "mode": "single" // or "sequential" |
| "agents": ["analyzer", "writer"] // optional for sequential |
| } |
| ``` |
| |
| **Response Example:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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 send |
| - `timeout`: Optional response timeout (seconds) |
| - `wait`: boolean value |
| |
| **Response Example:** |
| ```json |
| // 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 return |
| - `job_id` (optional): Filter by job ID |
| - `agent` (optional): Filter by agent name |
| |
| **Response Example:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| { |
| "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:** |
| ```json |
| // 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..." |
| } |
| } |
| ``` |
|
|
