Endpoints Reference

Detailed reference for every endpoint in the generated FastAPI application.

`GET /`

Welcome page. Returns an HTML page with basic agent info and links to docs.

Auth: None
Response: HTMLResponse (not included in OpenAPI schema)

`GET /health`

Health check for load balancers and orchestrators.

Auth: None
Response: HealthResponse

curl http://localhost:8080/health

{
  "status": "ok",
  "service": "runtime:my-agent",
  "version": "0.1.0",
  "timestamp": "2025-01-15T10:30:00Z",
  "agent": "my-agent",
  "framework": "custom"
}

Always returns 200 if the process is running.

`GET /ready`

Readiness probe. Returns 200 only when the agent adapter has been loaded successfully.

Auth: None
Response: ReadyResponse (200) or HTTPException (503)

curl http://localhost:8080/ready

{
  "success": true,
  "status": "ready",
  "agent": "my-agent"
}

Returns 503 if state.ready is false or the adapter failed to load. Use this for Kubernetes readiness probes.

`GET /metrics`

Prometheus-format metrics.

Auth: None
Response: text/plain with prometheus_client.CONTENT_TYPE_LATEST

curl http://localhost:8080/metrics

Returns standard Prometheus exposition format with dockrion_requests_total, dockrion_request_latency_seconds, and dockrion_active_requests.

`GET /schema`

Returns the agent’s input/output schema.

Auth: None
Response: SchemaResponse

{
  "success": true,
  "agent": "my-agent",
  "input_schema": {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  },
  "output_schema": {
    "type": "object",
    "properties": { "answer": { "type": "string" } }
  }
}

`GET /info`

Agent metadata and configuration summary.

Auth: None
Response: InfoResponse

{
  "success": true,
  "agent": {
    "name": "my-agent",
    "framework": "custom",
    "description": "My agent"
  },
  "auth_enabled": true,
  "version": "0.1.0",
  "metadata": {
    "maintainer": "team@company.com",
    "version": "1.0.0",
    "tags": ["production"]
  }
}

`POST /invoke`

Invoke the agent synchronously.

Auth: Required (when auth is configured)
Request body: Dynamic model from io_schema.input
Response: Dynamic InvokeResponseModel

curl -X POST http://localhost:8080/invoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "explain quantum computing"}'

Success (200)

{
  "success": true,
  "output": {
    "answer": "Quantum computing uses...",
    "confidence": 0.95
  },
  "metadata": {}
}

Validation Error (400)

{
  "success": false,
  "error": "Input validation failed",
  "code": "VALIDATION_ERROR"
}

Execution Error (500)

{
  "success": false,
  "error": "Agent execution failed: ...",
  "code": "AGENT_EXECUTION_ERROR"
}

`POST /invoke/stream`

Invoke the agent with SSE streaming. Only registered when expose.streaming is "sse".

Auth: Required
Request body: Same as /invoke
Response: StreamingResponse (text/event-stream)

See 4.4 Streaming Consumption for client-side examples.

`POST /runs`

Create an async run. Only registered when streaming.async_runs is true and dockrion_events is installed.

Auth: Required
Request body: Same as /invoke
Query params: run_id (optional, for client-provided IDs)
Response: 202 Accepted

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ACCEPTED",
  "events_url": "/runs/550e8400.../events",
  "created_at": "2025-01-15T10:30:00Z"
}

`GET /runs/{run_id}`

Get the status of an async run.

Auth: Required
Response: Run details including status, output (if complete), error (if failed)

`GET /runs/{run_id}/events`

Subscribe to run events via SSE.

Auth: Required
Query params:
- timeout (int, 1–3600, default 300) — connection timeout
- from_sequence (int, ≥0, default 0) — replay events from this sequence
Response: StreamingResponse (text/event-stream)

`DELETE /runs/{run_id}`

Cancel a running async run.

Auth: Required
Query params: reason (optional string)
Response: 200 on success, 400 if already terminal, 404 if not found

`GET /docs`

Swagger UI. Auto-generated by FastAPI.

`GET /redoc`

ReDoc documentation. Auto-generated by FastAPI.

`GET /openapi.json`

OpenAPI 3.0 specification in JSON.

Response Models

Model	Fields	Used by
`HealthResponse`	`status`, `service`, `version`, `timestamp`, `agent`, `framework`	`/health`
`ReadyResponse`	`success`, `status`, `agent`	`/ready`
`SchemaResponse`	`success`, `agent`, `input_schema`, `output_schema`	`/schema`
`InfoResponse`	`success`, `agent`, `auth_enabled`, `version`, `metadata`	`/info`
`ErrorResponse`	`success` (false), `error`, `code`	Error responses
`InvokeResponseModel`	`success`, `output` (typed), `metadata`	`/invoke`

InvokeResponseModel is dynamically created per agent — its output field uses the Pydantic model generated from io_schema.output.

Source: packages/runtime/dockrion_runtime/endpoints/, packages/common-py/dockrion_common/http_models.py

Next: 4.2 io_schema & Swagger →