API Overview
Albiex Synth City exposes a RESTful API under /api/v1/. The frontend communicates with the backend entirely through this API.
Base URL
http://localhost:8000/api/v1In development, the Vite dev server proxies /api requests from port 5173 to the backend at port 8000.
Authentication
Authentication is endpoint-specific. The five observational Factory GET routes have no operator or session credential dependency. Protected recovery, policy and mutation routes require their documented operator or authenticated Mail-session principal, with state and actor checks on the server. An action eligibility observation does not authenticate its viewer.
Request/Response Format
All request and response bodies use JSON. Set Content-Type: application/json for requests with bodies.
UTC timestamps
UTC means Coordinated Universal Time. Response datetimes identify UTC with Z or +00:00. A naive datetime has no timezone. JSON serialization treats a naive server datetime as UTC. Serialization converts an aware datetime to the same instant in UTC. Stored values and Python model values stay unchanged.
Declared legacy timestamp strings also identify UTC in JSON. User text and other strings stay unchanged. Backup archive manifests keep their storage serializer. The API formats a copy of a manifest. Stored progress snapshots also keep their serializer. The progress API formats a copied observation.
Use the response timestamp unchanged for confirmation. AgentTeamLeaderUpdateRequest.expected_updated_at and GithubWorkspaceForceReleaseRequest.expected_leased_at decode aware input into the existing naive UTC form. Naive input stays unchanged. Database predicates, lease token checks, and authority rules stay unchanged.
Common Query Parameters
| Parameter | Type | Description |
|---|---|---|
project_path | string | Optional. Project directory path for project-scoped resources. |
scope | string | user, project, plugin, or managed — depends on the endpoint. |
Error Handling
| Status | Meaning |
|---|---|
200 | Success |
201 | Resource created |
204 | Deleted (no content) |
400 | Validation error |
404 | Resource not found |
500 | Server error |
Error responses return JSON with a detail field:
{
"detail": "Resource not found"
}Provider-aware endpoints may also map failures into normalized states such as unsupported capability, missing binary, unavailable CLI command, CLI failure, parse failure, or validation failure. Sensitive CLI stdout/stderr and raw provider payloads should be redacted or omitted before they are returned.
Factory read errors
Factory reads return detail: {code, message} for invalid filters/cursors (422), absent selected resources (404) and projection failures (500). Preserve both fields. Existing protected routes retain their string or structured detail codes and 401/403/409 results; their endpoint-specific contracts still apply. See Factory API for codes and examples.
API Documentation
FastAPI generates interactive API docs at:
- Swagger UI:
http://localhost:8000/docs - ReDoc:
http://localhost:8000/redoc
Route Modules
| Module | Prefix | Description |
|---|---|---|
| Factory | /factory | Observational work counts/details, watched-scope intake, poll and overlap reads, delivery metrics, protected audit events, protected review declarations and the protected setup preflight |
| Config | /config and /codex-config | Configuration management |
| Providers | /providers | Provider metadata, status, diagnostics, and inventory |
| MCP Servers | /mcp | MCP server management |
| Commands | /commands | Slash commands |
| Plugins | /plugins | Plugin management |
| Hooks | /hooks | Event hooks |
| Permissions | /permissions | Access control rules |
| Agents | /agents | Agents and skills |
| Sessions | /sessions | Session transcripts |
| Context | /context | Context window analysis |
| Plans | /plans | Implementation plans |
| Output Styles | /output-styles | Response formatting |
| Status Line | /statusline | Terminal status bar |
| Agent Bridge | /agent-bridge | Provider-aware live terminal monitoring |
| Agent Mail | /agent-mail and /external/agent-mail | Local agent mailbox coordination and external same-machine orchestration |
| Agent Teams | /agent-teams | Saved agent rosters, launch planning, and team slot context |
| CC Bridge | /cc-bridge | Legacy Claude Code terminal monitoring route |
| Usage | /usage | Token usage tracking |
| Memory | /memory | Memory hierarchy |
| Backup | /backup | Configuration backups |