API Reference

The Platos platform exposes a FastAPI-powered REST + WebSocket API. This page lists every endpoint by resource group. For detailed request/response schemas, use the live OpenAPI spec.

Live OpenAPI

Start the API (docker compose up platos-api or uv run uvicorn platos.main:app --reload --app-dir apps/api) and open:

URL	Description
GET /openapi.json	Raw OpenAPI 3.1 JSON spec.
GET /docs	Swagger UI with try-it-out support.
GET /redoc	ReDoc three-column view.

Auth model

Every org-scoped endpoint requires a JWT on the Authorization: Bearer ... header. The JWT carries org_id and user_id claims; the API filters every query by org_id server-side. Cross-tenant leaks are a critical bug.

The SDK’s WebSocket transport uses a long-lived PLATOS_SECRET (an SDK agent JWT) rather than a user JWT. The two token types are scoped separately so a leaked SDK secret can’t impersonate an end user and vice versa.

Endpoints by resource

Health

Method	Path	Description
GET	/health	Liveness check.

Auth (/api/v1/auth)

Method	Path	Description
POST	/api/v1/auth/register	Create a new user + org.
POST	/api/v1/auth/login	Authenticate and receive access + refresh tokens.
POST	/api/v1/auth/logout	Revoke the current session.
GET	/api/v1/auth/me	Return the current user’s session status.
POST	/api/v1/auth/refresh	Exchange a refresh token for new access + refresh tokens.

Organization (/api/v1/org)

Method	Path	Description
GET	/api/v1/org	Get the current organization.
PATCH	/api/v1/org	Update organization settings.
GET	/api/v1/org/members	List org members.
POST	/api/v1/org/members	Invite a new member.
PATCH	/api/v1/org/members/{member_id}/role	Change a member’s role.
DELETE	/api/v1/org/members/{member_id}	Remove a member.
GET	/api/v1/org/api-keys	List API keys.
POST	/api/v1/org/api-keys	Create an API key.
DELETE	/api/v1/org/api-keys/{key_id}	Revoke an API key.
GET	/api/v1/org/sdk-connections	List SDK connections.
POST	/api/v1/org/sdk-connections	Create an SDK connection (generates PLATOS_SECRET).
DELETE	/api/v1/org/sdk-connections/{connection_id}	Revoke an SDK connection.

Agents (/api/v1/agents)

Method	Path	Description
GET	/api/v1/agents	List agents in the org.
POST	/api/v1/agents	Create an agent.
GET	/api/v1/agents/{agent_id}	Get agent details.
PATCH	/api/v1/agents/{agent_id}	Update an agent.
DELETE	/api/v1/agents/{agent_id}	Delete an agent.
GET	/api/v1/agents/{agent_id}/rate-limits	Get agent rate limits.
GET	/api/v1/agents/{agent_id}/prompt	Get the agent’s prompt config.
POST	/api/v1/agents/{agent_id}/prompt/blocks	Add a prompt block.
PATCH	/api/v1/agents/{agent_id}/prompt/blocks/{block_id}	Update a prompt block.
DELETE	/api/v1/agents/{agent_id}/prompt/blocks/{block_id}	Delete a prompt block.
PUT	/api/v1/agents/{agent_id}/prompt/blocks/reorder	Reorder prompt blocks.
GET	/api/v1/agents/{agent_id}/prompt/preview	Preview the assembled prompt.
GET	/api/v1/agents/{agent_id}/prompt/versions	List prompt versions.
POST	/api/v1/agents/{agent_id}/prompt/rollback/{version_number}	Roll back to a previous prompt version.
GET	/api/v1/agents/{agent_id}/tools	List tools assigned to an agent.
GET	/api/v1/agents/{agent_id}/tool-config	Get agent tool config (smart selection, allowlist).
PATCH	/api/v1/agents/{agent_id}/tool-config	Update agent tool config.
POST	/api/v1/agents/{agent_id}/tools/preview	Preview tool selection for a given query.

Agent invoke (/api/v1/agents)

Method	Path	Description
GET	/api/v1/agents/{agent_id}/schemas	Get agent input/output schemas.
PATCH	/api/v1/agents/{agent_id}/schemas	Update agent schemas (admin).
POST	/api/v1/agents/{agent_id}/invoke	Invoke an agent with typed input.

Chat (/api/v1/agents)

Method	Path	Description
POST	/api/v1/agents/{agent_id}/chat	Send a chat message (streaming SSE response).

Conversations

Method	Path	Description
GET	/api/v1/agents/{agent_id}/conversations	List conversations for an agent.
GET	/api/v1/conversations/{conversation_id}	Get a conversation with messages.
DELETE	/api/v1/conversations/{conversation_id}	Delete a conversation.

Memory (/api/v1/agents)

Method	Path	Description
GET	/api/v1/agents/{agent_id}/memory-config	Get memory config.
PATCH	/api/v1/agents/{agent_id}/memory-config	Update memory config.
GET	/api/v1/agents/{agent_id}/memory/stats	Get memory stats.
GET	/api/v1/agents/{agent_id}/memory/{user_id}	Get memory view for a user.
GET	/api/v1/agents/{agent_id}/memory/{user_id}/facts	List extracted facts.
GET	/api/v1/agents/{agent_id}/memory/{user_id}/graph	Get knowledge graph.
DELETE	/api/v1/agents/{agent_id}/memory/{user_id}	Clear memory for a user.

Providers (/api/v1/providers)

Method	Path	Description
GET	/api/v1/providers	List configured providers (BYOK).
POST	/api/v1/providers	Register a provider.
DELETE	/api/v1/providers/{provider_id}	Remove a provider.
POST	/api/v1/providers/{provider_id}/test	Test a provider connection.
GET	/api/v1/providers/catalog	List supported model catalog.

Tiers (/api/v1/tiers)

Method	Path	Description
GET	/api/v1/tiers	List model tiers.
POST	/api/v1/tiers	Create a tier.
PATCH	/api/v1/tiers/{tier_id}	Update a tier.
DELETE	/api/v1/tiers/{tier_id}	Delete a tier.

Tool groups (/api/v1/tools/groups)

Method	Path	Description
GET	/api/v1/tools/groups	List tool groups.
POST	/api/v1/tools/groups	Create a tool group.
GET	/api/v1/tools/groups/{group_id}	Get a tool group.
PATCH	/api/v1/tools/groups/{group_id}	Update a tool group.
DELETE	/api/v1/tools/groups/{group_id}	Delete a tool group.

Tool health (/api/v1/tools)

Method	Path	Description
GET	/api/v1/tools/health	Get health status for all tools.
GET	/api/v1/tools/{tool_id}/health/history	Get health history for a tool.

MCP gateway (/mcp)

Method	Path	Description
POST	/mcp/{org_slug}/{endpoint_id}	MCP Streamable HTTP endpoint.
GET	/mcp/{org_slug}/{endpoint_id}/.well-known/oauth-authorization-server	OAuth discovery.
POST	/mcp/{org_slug}/{endpoint_id}/oauth/register	Dynamic client registration.
GET	/mcp/{org_slug}/{endpoint_id}/oauth/authorize	OAuth authorize.
POST	/mcp/{org_slug}/{endpoint_id}/oauth/token	OAuth token exchange.

MCP endpoints admin (/api/v1/mcp-endpoints)

Method	Path	Description
GET	/api/v1/mcp-endpoints	List MCP endpoints.
GET	/api/v1/mcp-endpoints/{endpoint_id}	Get endpoint config.
POST	/api/v1/mcp-endpoints	Create an MCP endpoint.
PATCH	/api/v1/mcp-endpoints/{endpoint_id}	Update endpoint config.
DELETE	/api/v1/mcp-endpoints/{endpoint_id}	Delete an MCP endpoint.
GET	/api/v1/mcp-endpoints/{endpoint_id}/tools	List tools exposed by an endpoint.

Workflows (/api/v1/workflows)

Method	Path	Description
GET	/api/v1/workflows	List workflows.
POST	/api/v1/workflows	Create a workflow (DAG definition).
GET	/api/v1/workflows/{workflow_id}	Get a workflow.
PATCH	/api/v1/workflows/{workflow_id}	Update a workflow.
DELETE	/api/v1/workflows/{workflow_id}	Delete a workflow.
POST	/api/v1/workflows/{workflow_id}/execute	Execute a workflow run.
POST	/api/v1/workflows/{workflow_id}/human-input	Submit human-in-the-loop input.
GET	/api/v1/workflows/{workflow_id}/runs	List runs for a workflow.
GET	/api/v1/task-runs/{run_id}	Get a task run.

Long-running tasks

Method	Path	Description
GET	/api/v1/task-templates	List task templates.
POST	/api/v1/task-templates	Create a task template.
GET	/api/v1/task-templates/{template_id}	Get a template.
PATCH	/api/v1/task-templates/{template_id}	Update a template.
DELETE	/api/v1/task-templates/{template_id}	Delete a template.
GET	/api/v1/long-running-tasks/runs	List task runs.
POST	/api/v1/long-running-tasks/runs	Create a task run.
GET	/api/v1/long-running-tasks/runs/{run_id}	Get run details + progress.
GET	/api/v1/long-running-tasks/runs/{run_id}/progress	Get run progress checkpoints.
POST	/api/v1/long-running-tasks/runs/{run_id}/cancel	Cancel a running task.

Monitoring (/api/v1/monitoring)

Method	Path	Description
GET	/api/v1/monitoring/tool-calls	Paginated tool call logs.
GET	/api/v1/monitoring/tool-calls/stats	Aggregate tool call statistics.

Safety (/api/v1/monitoring/safety)

Method	Path	Description
GET	/api/v1/monitoring/safety	Paginated safety alerts.
GET	/api/v1/monitoring/safety/stats	Safety summary statistics.
GET	/api/v1/monitoring/safety/config	Get safety config.
PUT	/api/v1/monitoring/safety/config	Update safety config.

Quality (/api/v1/quality)

Method	Path	Description
GET	/api/v1/quality/checks	Paginated quality checks.
GET	/api/v1/quality/checks/stats	Quality statistics.
POST	/api/v1/quality/checks/run	Trigger a quality check run.

Evals (/api/v1/evals)

Method	Path	Description
GET	/api/v1/evals/datasets	List eval datasets.
POST	/api/v1/evals/datasets	Create a dataset.
GET	/api/v1/evals/datasets/{dataset_id}	Get a dataset.
PATCH	/api/v1/evals/datasets/{dataset_id}	Update a dataset.
DELETE	/api/v1/evals/datasets/{dataset_id}	Delete a dataset.
GET	/api/v1/evals/datasets/{dataset_id}/cases	List test cases.
POST	/api/v1/evals/datasets/{dataset_id}/cases	Create a test case.
PATCH	/api/v1/evals/cases/{case_id}	Update a test case.
DELETE	/api/v1/evals/cases/{case_id}	Delete a test case.
POST	/api/v1/evals/runs	Create an eval run.
GET	/api/v1/evals/runs	List eval runs.
GET	/api/v1/evals/runs/compare	Compare two eval runs.
GET	/api/v1/evals/runs/{run_id}	Get an eval run.
GET	/api/v1/evals/runs/{run_id}/results	Get per-case results for an eval run.
GET	/api/v1/evals/ab-tests	List A/B tests.
POST	/api/v1/evals/ab-tests	Create an A/B test.
GET	/api/v1/evals/ab-tests/{test_id}	Get an A/B test.
GET	/api/v1/evals/ab-tests/{test_id}/stats	Get A/B test statistics.
POST	/api/v1/evals/ab-tests/{test_id}/promote	Promote the winning variant.

WebSocket (/ws/sdk)

The SDK-facing WebSocket endpoint. SDKs connect here via platools.connect() to register tools and receive tool-call dispatches. See Python Client and TypeScript Client for the wire protocol.

Generating a client

The spec is served at /openapi.json, so you can generate a client in any language:

curl http://localhost:8000/openapi.json > platos-openapi.json
openapi-generator-cli generate \
  -i platos-openapi.json \
  -g typescript-fetch \
  -o ./generated

The REST API is for dashboard, orchestration, and monitoring flows. The platools SDK package is a separate tool-registration surface.

Changes

The OpenAPI spec is generated from the FastAPI code on every request, so /openapi.json always reflects the running server. If you see drift between this page and the live spec, the live spec wins.

Next steps

• Deployment - get the API running with Docker Compose.
• Python SDK - the tool-registration SDK that connects via WebSocket.
• TypeScript SDK - the same SDK in TypeScript.