# 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..." } } ```