API Gateway
The Facio HTTP surfaces for OpenAI-compatible calls, management, Placet, and A2A.
Facio runs an HTTP gateway next to the agent loop. In the quickstart container it is the service that Placet calls for management actions, while other clients can use it for OpenAI-compatible chat or A2A when those surfaces are enabled.
The gateway is intentionally split into separate surfaces with separate security expectations.
Surfaces
| Surface | Path | Auth | Purpose |
|---|---|---|---|
| Health | /health | None | Basic liveness check. |
| OpenAI-compatible | /v1/chat/completions, /v1/models | Legacy surface, no bearer token | Single-message chat calls against the configured Facio model. |
| Management | /api/v1/* | Authorization: Bearer FACIO_MANAGEMENT_TOKEN | Placet/admin control plane for settings, channels, credentials, MCP, sessions, audit, cron, workspace, and versions. |
| A2A | /a2a/v1/* | FACIO_A2A_TOKEN or management token | Google A2A-compatible inter-agent RPC. |
| Agent Card | /.well-known/agent-card.json | Public when A2A is enabled | Discovery metadata for A2A clients. |
The management and A2A routers are mounted only when their token exists and the matching feature flag is enabled. FACIO_MANAGEMENT_TOKEN and FACIO_A2A_TOKEN must not be identical.
OpenAI-compatible chat
Use this surface when a client expects an OpenAI-style API but you want the request handled by the Facio runtime.
curl http://localhost:8900/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "facio",
"messages": [{"role": "user", "content": "Summarize the current workspace."}],
"stream": false
}'Important behavior:
- Only one user message is accepted per request.
stream=trueis rejected; use non-streaming calls.session_idis optional. If provided, Facio stores the conversation underapi:session_id; otherwise it usesapi:default./v1/modelsreturns the single configured Facio model, not a full provider catalog.
Management API
The management API is the control plane Placet uses after the agent self-registers its management URL and token. It is also useful for operator tooling.
Common rules:
- Every
/api/v1/*request requiresAuthorization: Bearer $FACIO_MANAGEMENT_TOKEN. - Write requests use JSON bodies and return JSON responses.
- Resource routers may return
503when the backing runtime service is not available in the current deployment. - Treat workspace, credentials, policy, MCP, and command routes as administrative surfaces. Do not expose them directly to the public internet.
| Area | Endpoints |
|---|---|
| Health and discovery | GET /api/v1/health, GET /api/v1/agent-card |
| Settings | GET /api/v1/settings, PATCH /api/v1/settings |
| Credentials | GET/POST /api/v1/credentials, GET/PUT/DELETE /api/v1/credentials/{key}, PUT /api/v1/credentials/{key}/exposed |
| Provider credentials | GET/POST /api/v1/credentials/providers, PUT/DELETE /api/v1/credentials/providers/{name}, POST /api/v1/credentials/providers/{name}/oauth/start, GET /api/v1/credentials/providers/{name}/oauth/poll?session_id=... |
| MCP | GET/POST /api/v1/mcp, GET/PATCH/DELETE /api/v1/mcp/{name}, POST /api/v1/mcp/{name}/enable, disable, restart |
| Channels | GET /api/v1/channels, GET/PUT/DELETE /api/v1/channels/{name} |
| Sessions | GET /api/v1/sessions, GET/DELETE /api/v1/sessions/{key} |
| Audit and usage | GET /api/v1/audit, GET /api/v1/audit/tail, GET /api/v1/audit/stats, GET /api/v1/audit/runs/{runId}, GET /api/v1/usage, GET /api/v1/usage/runs/{runId} |
| Policy | GET/POST/DELETE /api/v1/policy, DELETE /api/v1/policy/all, PATCH /api/v1/policy/settings |
| Cron | GET/POST /api/v1/cron, GET/PATCH/DELETE /api/v1/cron/{id}, POST /api/v1/cron/{id}/run-now, pause, resume |
| Workspace | GET /api/v1/workspace/tree, GET/PUT/DELETE /api/v1/workspace/file |
| Skills and scripts | GET/POST /api/v1/skills, DELETE /api/v1/skills/{name}, GET /api/v1/scripts |
| Self-improvement reviews | GET /api/v1/improvement/runs, run detail, report, diff, POST /api/v1/improvement/runs/{runId}/comment, reject, approve, rollback |
| Agent versions | GET /api/v1/agent/versions, POST /api/v1/agent/versions/checkpoint, GET /api/v1/agent/versions/{sha}, diff, rollback |
| Commands | POST /api/v1/commands/stop, restart, new, reflect, GET /api/v1/commands/status |
| A2A peers | GET/POST /api/v1/a2a/peers, DELETE /api/v1/a2a/peers/{alias}, GET /api/v1/a2a/peers/{alias}/card, POST /api/v1/a2a/peers/{alias}/call |
Example:
curl http://localhost:8900/api/v1/settings \
-H "Authorization: Bearer $FACIO_MANAGEMENT_TOKEN"Hardening knobs
| Setting | Meaning |
|---|---|
api.host | Bind address for the HTTP API. Default is local-only inside the container. |
api.port / FACIO_API_PORT | Port for the HTTP API. Quickstart exposes the container port through Docker networking. |
api.timeout | Per-request timeout for OpenAI-compatible chat calls. |
api.allowedOrigins / FACIO_ALLOWED_ORIGINS | Optional CORS allow list. Empty means no CORS. |
api.rateLimitRpm / FACIO_RATE_LIMIT_RPM | Optional per-client-IP request limit. 0 disables rate limiting. |
api.managementEnabled / FACIO_MANAGEMENT_ENABLED | Mount /api/v1/* when a management token is present. |
api.a2aEnabled / FACIO_A2A_ENABLED | Mount /a2a/v1/* and the public agent card when an A2A token or management token is present. |
For public deployments, put the gateway behind a reverse proxy, keep management and A2A tokens separate, keep CORS closed unless a browser client needs it, and rate-limit exposed routes.