Polymath Zero

Developers

API reference

Zero's local API runs at http://localhost:7878. All requests are unauthenticated on localhost. All endpoints return JSON. Use standard HTTP clients.

Authentication

Zero's local API at localhost:7878 is designed for local machine use only. It is not exposed to the internet by default. No API key is required for local access — the server only accepts connections from localhost.

  • Scripts on the same machine: no authentication required. Use the API directly.
  • Remote access: not supported in current releases. API key support is planned for secure remote access via the console.
API key authentication is in development. Current releases do not require an API key for localhost access.
Recommended integration flow. The primary operator path is Work-centered, not state-transition-centered:
  1. Create a Work item — POST /cases
  2. Create a session — POST /cases/:id/sessions
  3. Poll or stream until plan_ready — GET /cases/:id/sessions/:sid/stream
  4. Approve the plan — POST /cases/:id/sessions/:sid/approve (Work mode begins)
  5. Stream execution events until complete
  6. Attach proof — POST /cases/:id/proof
  7. Verify proof — PUT /cases/:id/proof/:pid/verify
Direct state transitions via PUT /cases/:id/state are a compatibility path. Prefer session-based flow.

Cases

MethodPathDescription
GET/casesList all Work items. Supports ?state=RESOLVED&outcome=ConfirmedCodeBug.
POST/casesCreate Work item. Body: { "title": "string", "type": "bug" }.
GET/cases/:idGet Work item by ID.
PUT/cases/:idUpdate title or description. Body: { "title": "string" }.
DELETE/cases/:idDelete Work item and all memory (irreversible).
PUT/cases/:id/stateTransition state directly. Compatibility path — prefer session-based flow for Work execution. Body: { "state": "IMPLEMENTING" }.
curl -s http://localhost:7878/cases?state=RESOLVED

Sessions

MethodPathDescription
GET/cases/:id/sessionsList all sessions for a Work item.
POST/cases/:id/sessionsCreate a new session. Body: { "type": "implementing" }.
GET/cases/:id/sessions/:sidGet a single session by ID.
POST/cases/:id/sessions/:sid/approveApprove session plan. Unlocks Work mode — agent begins executing the approved plan.
GET/cases/:id/sessions/:sid/streamSSE stream of execution events.
# Stream session execution events
curl -N http://localhost:7878/cases/:id/sessions/:sid/stream

Memory

MethodPathDescription
GET/cases/:id/memory/:filenameRead a memory file (markdown). Returns raw text.
PUT/cases/:id/memory/:filenameWrite a memory file. Body: raw markdown text.

Proof

MethodPathDescription
GET/cases/:id/proofList all proof artifacts for a Work item.
POST/cases/:id/proofAttach proof. Body: { "type": "test-log", "content": "..." }.
PUT/cases/:id/proof/:pid/verifyMark a proof artifact as verified.
POST/cases/:id/proof/checklistAdd a proof checklist item. Body: { "description": "...", "type": "test-log", "required": true }.
# Attach test log proof
curl -s -X POST http://localhost:7878/cases/:id/proof \
  -H "Content-Type: application/json" \
  -d '{"type": "test-log", "content": "test result: 47 passed, 0 failed"}'

Providers

Dev-only boundary. Provider transport via API is in development. Current releases use the local CLI-based runner. The endpoints below reflect the planned API; they are not available in production builds.
MethodPathDescription
GET/providersList available providers and availability status. Dev builds only.
POST/providers/:id/runRun a provider with a prompt. Body: { "prompt": "string" }. Dev builds only.

System

MethodPathDescription
GET/healthHealth check. Returns { "status": "ok" }.
GET/versionReturns current Zero version and build info.

Error codes

  • 422 — Proof gate blocked (missing verified proof), or requested operation not valid for current run state.
  • 404 — Work item or resource not found.
  • 400 — Bad request (missing required fields).
  • 409 — Conflict — e.g. Work mode already active for this session.

Related: Case model, Session model.