AutoMaxReference
REST API
The server's HTTP API.
All routes live under /api on the server started by automax serve. Request and response bodies are validated with Zod; the schemas are exported from @automax/server/schemas for typed clients.
Authentication
- Browser: session cookie
automax_sid(HttpOnly, SameSite=Lax, sliding 7 days). Non-GET requests carry thex-csrf-tokenheader returned byGET /api/auth/me. - Automation and MCP clients:
Authorization: Bearer amx_…tokens created withautomax tokens createor in Settings. Tokens carry scopes; a route requires a scope such asruns:write. - Workspace access: a project route is allowed when the user's effective role in the project's workspace permits it (
viewerreads,editorruns and edits,adminmanages).
Routes
| Area | Routes |
|---|---|
| Health | GET /api/health, GET /api/mcp/info |
| Auth | POST /api/auth/login, POST /api/auth/logout, GET /api/auth/me, GET /api/auth/setup-status, POST /api/auth/setup (one-time admin bootstrap) |
| Hierarchy | GET /api/orgs, GET/POST/DELETE /api/orgs/:slug/members, GET /api/workspaces (with effective role and project counts), POST /api/workspaces, GET /api/workspaces/:slug, members CRUD, POST /api/hierarchy/sync |
| Users, tokens | GET/POST /api/users, PATCH /api/users/:id, GET/POST /api/tokens, DELETE /api/tokens/:id, GET /api/audit |
| Projects | GET/POST /api/projects, GET/PUT /api/projects/:slug, …/envs, …/datasets (multipart upload, preview), …/users-pool, …/processes, …/processes/:name/run, …/integrations (get, put, test, sync) |
| Features | GET /api/projects/:slug/features, GET/PUT /api/projects/:slug/features/* (PUT validates and lints, 422 with diagnostics), POST …/features/validate, GET …/steps, POST …/lint, POST …/record |
| Runs | GET /api/runs, POST /api/runs (202 with the run id), GET /api/runs/:id (scenario tree grouped by module), GET /api/runs/:id/scenarios/:sid, GET /api/runs/:id/events (SSE), POST /api/runs/:id/cancel, GET /api/runs/:id/report, GET /api/runs/:id/files/*, POST /api/runs/:id/ingest (runs:ingest) |
| Artifacts | GET /api/artifacts/:id, GET /api/artifacts/compare?before&after (server-side pixel diff) |
| Stats | GET /api/stats/trends, GET /api/stats/flaky, GET /api/stats/heal, GET /api/stats/insights |
| Schedules | GET/POST /api/schedules, PUT/DELETE /api/schedules/:id, POST …/pause, …/resume, …/run-now, GET /api/schedules/next |
| Agents | GET/POST /api/agents/jobs, GET /api/agents/jobs/:id, GET /api/agents/jobs/:id/events (SSE), GET /api/proposals, POST /api/proposals/:id/accept, POST /api/proposals/:id/reject |
| MCP | POST/GET/DELETE /mcp (streamable HTTP, bearer tokens only) |
| Static | / (web UI), /reports/:runId/* (Playwright HTML report), /trace/* (trace viewer) |
Errors use one shape: { "error": { "code", "message", "hint" } }.