Developers

API reference

Zero's local API runs at http://localhost:7878. It is the local-first interface to Zero's runtime — all state, memory, and execution live on the operator's machine. All requests are unauthenticated on localhost. All endpoints return JSON.

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.

What's available now. Work item, session, memory, proof, planning pipeline, worktrees, GitHub integration, and system endpoints are available in current releases. Provider API is in development (dev builds only). No cloud transport or remote access in current builds.

Recommended integration flow. The primary operator path is Work-centered, not state-transition-centered:

Create a Work item — POST /cases
Create a session — POST /cases/:id/sessions
Poll or stream until plan_ready — GET /cases/:id/sessions/:sid/stream
Approve the plan — POST /cases/:id/sessions/:sid/approve (Work mode begins)
Stream execution events until complete
Attach proof — POST /cases/:id/proof
Verify proof — PUT /cases/:id/proof/:pid/verify

Direct state transitions via PUT /cases/:id/state are a compatibility path. Prefer session-based flow.

Work items `/cases`

Method	Path	Description
`GET`	`/cases`	List all Work items. Supports `?state=RESOLVED&outcome=ConfirmedCodeBug`.
`POST`	`/cases`	Create Work item. Body: `{ "title": "string", "type": "bug" }`.
`GET`	`/cases/:id`	Get Work item by ID.
`PUT`	`/cases/:id`	Update title or description. Body: `{ "title": "string" }`.
`DELETE`	`/cases/:id`	Delete Work item and all memory (irreversible).
`PUT`	`/cases/:id/state`	Transition state directly. Compatibility path — prefer session-based flow for Work execution. Body: `{ "state": "IMPLEMENTING" }`.

curl -s http://localhost:7878/cases?state=RESOLVED

Sessions

Each session begins in Plan mode — the agent reads context and proposes a plan. The operator reviews and approves. Approval unlocks Work mode: the agent executes the approved plan and produces a diff. No execution happens before the operator approves.

Method	Path	Description
`GET`	`/cases/:id/sessions`	List all sessions for a Work item.
`POST`	`/cases/:id/sessions`	Create a new session. Body: `{ "type": "implementing" }`.
`GET`	`/cases/:id/sessions/:sid`	Get a single session by ID.
`POST`	`/cases/:id/sessions/:sid/approve`	Operator approves the plan. Transitions session from Plan mode to Work mode — agent executes. This is an explicit operator gate, not an automated step.
`GET`	`/cases/:id/sessions/:sid/stream`	SSE stream of execution events.

# Stream session execution events
curl -N http://localhost:7878/cases/:id/sessions/:sid/stream

Session control

Sessions are queued per Work item. Only one session per worktree can hold the lock at a time. Pause, resume, and abort are operator-driven actions — the agent does not self-interrupt.

Method	Path	Description
`GET`	`/api/sessions/queue`	List queued sessions across all Work items.
`POST`	`/api/sessions/queue`	Enqueue a session. Body: `{ "case_id": "..." }`.
`GET`	`/api/sessions/active`	List all currently active sessions.
`GET`	`/api/worktrees/:case_id/lock`	Read the current lock state for a worktree.
`POST`	`/api/worktrees/:case_id/lock`	Acquire the session lock. Returns error if already held.
`DELETE`	`/api/worktrees/:case_id/lock`	Release the session lock.
`POST`	`/api/cases/:id/session/pause`	Pause the active session for this Work item.
`POST`	`/api/cases/:id/session/resume`	Resume a paused session.
`POST`	`/api/cases/:id/session/abort`	Abort the active session. Cannot be undone.
`GET`	`/api/worktrees/:case_id/memory-root`	Return the memory root path for a worktree.

Memory

Method	Path	Description
`GET`	`/cases/:id/memory/:filename`	Read a memory file (markdown). Returns raw text.
`PUT`	`/cases/:id/memory/:filename`	Write a memory file. Body: raw markdown text.

Global memory

Global memory is a process-wide store guarded by the same session lock. Used during Work mode to persist learnings across sessions. Separate from per-Work-item memory files.

Method	Path	Description
`POST`	`/api/global-memory/snapshot`	Take a snapshot of the current global memory state.
`POST`	`/api/global-memory/write`	Write to global memory, guarded by session lock.

Proof

Method	Path	Description
`GET`	`/cases/:id/proof`	List all proof artifacts for a Work item.
`POST`	`/cases/:id/proof`	Attach proof. Body: `{ "type": "test-log", "content": "..." }`.
`PUT`	`/cases/:id/proof/:pid/verify`	Mark a proof artifact as verified.
`POST`	`/cases/:id/proof/checklist`	Add 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"}'

Planning pipeline

Planning runs in three stages: derive a draft from the source issue, expand hypotheses, then generate tasks. Each stage writes Markdown into the Work item's memory directory. Stages are independently invokable — the operator decides when to advance.

Method	Path	Description
`POST`	`/api/cases/:id/planning/from-issue`	Stage 1: derive a plan draft from the linked GitHub issue. Writes `problem-definition.md`.
`POST`	`/api/cases/:id/planning/hypotheses-file`	Stage 2: generate a hypotheses file. Writes `hypotheses.md`.
`POST`	`/api/cases/:id/planning/generate-tasks`	Stage 3: generate tasks from hypotheses. Writes `tasks.md`.
`GET`	`/api/cases/:id/planning/gate`	Read the current planning gate status.
`POST`	`/api/cases/:id/planning/approve`	Approve the plan — operator gate before Work mode.
`GET`	`/api/cases/:id/planning/readiness`	Check whether the Work item is ready to execute.
`GET`	`/api/cases/:id/planning-artifacts`	List all planning artifact files for a Work item.
`PUT`	`/api/cases/:id/planning-artifacts/:filename`	Write a planning artifact. Body: raw markdown.

# Run the three planning stages in sequence
curl -X POST http://localhost:7878/api/cases/:id/planning/from-issue
curl -X POST http://localhost:7878/api/cases/:id/planning/hypotheses-file
curl -X POST http://localhost:7878/api/cases/:id/planning/generate-tasks

Worktrees

Each Work item runs in an isolated git worktree. Branch names, isolation checks, and stale cleanup are exposed for tooling. Worktrees are per-machine — no cross-machine worktree sharing.

Method	Path	Description
`POST`	`/api/worktrees`	Create a new worktree for a Work item.
`POST`	`/api/worktrees/:case_id/attach`	Attach an existing directory as a worktree.
`DELETE`	`/api/cases/:id/worktree`	Detach and delete the worktree for a Work item.
`GET`	`/api/worktrees/:case_id/health`	Check worktree health (git status, lock state).
`GET`	`/api/worktrees/:case_id/status`	Return current worktree status.
`POST`	`/api/worktrees/:case_id/verify-isolation`	Verify the worktree is isolated from the main branch.
`GET`	`/api/worktrees/stale`	List stale worktrees (no active session, exceeds TTL).
`POST`	`/api/worktrees/cleanup`	Clean up stale worktrees. Operator-triggered — not automatic.
`GET`	`/api/worktrees/config`	Read worktree configuration.
`PUT`	`/api/worktrees/config`	Update worktree configuration.
`POST`	`/api/worktrees/branch-name`	Generate a branch name for a Work item.

GitHub

GitHub integration provides issue import, repo metadata, and authentication status. Only GitHub is live in current releases — Linear, Jira, GitLab, and Bitbucket are planned.

Method	Path	Description
`GET`	`/api/github/availability`	Check whether GitHub CLI is available and authenticated.
`GET`	`/api/github/auth/status`	Return current GitHub auth status.
`POST`	`/api/github/auth/refresh`	Refresh GitHub auth token.
`GET`	`/api/github/repo/detect`	Detect the GitHub repo from the current working directory.
`GET`	`/api/github/repo/validate`	Validate that the detected repo is accessible.
`GET`	`/api/github/repo/permissions`	Return the operator's permissions on the repo.
`GET`	`/api/github/repo/meta`	Return repo metadata (name, default branch, visibility).
`GET`	`/api/github/repo/labels`	List repo labels.
`GET`	`/api/github/repo/milestones`	List repo milestones.
`GET`	`/api/github/repo/assignees`	List available assignees.
`GET`	`/api/github/settings`	Read GitHub integration settings.
`PUT`	`/api/github/settings`	Update GitHub integration settings.
`GET`	`/api/github/me`	Return the authenticated GitHub user.
`GET`	`/api/github/issues/count`	Return the number of open issues on the repo.
`POST`	`/api/github/issues/fetch`	Fetch issues from GitHub with filters.
`POST`	`/api/github/issues/extract`	Extract structured content from an issue body.
`GET`	`/api/github/issues/:number/detail`	Get full detail for a single issue.
`GET`	`/api/github/issues/:number/comments`	List comments on an issue.
`GET`	`/api/github/issues/:number/linked-prs`	List PRs linked to an issue.
`POST`	`/api/github/issues/import-case`	Import a GitHub issue as a Work item.
`GET`	`/api/github/import/jobs`	List import jobs.
`POST`	`/api/github/import/jobs`	Create an import job.
`PATCH`	`/api/github/import/jobs/:id`	Update an import job (e.g. mark complete).
`POST`	`/api/github/sync-all`	Sync all Work items with their linked GitHub issues. Operator-triggered.
`POST`	`/api/github/webhook`	Receive a GitHub webhook event.

Work item GitHub link

Each Work item maintains a GitHub link record (issue + PR). Sync is operator-triggered — Zero does not auto-sync in the background.

Method	Path	Description
`GET`	`/api/cases/:id/github`	Read the GitHub link record for a Work item.
`POST`	`/api/cases/:id/github/sync`	Sync the Work item with its linked GitHub issue.
`GET`	`/api/cases/:id/github/sync-log`	Return the full sync log for this Work item.
`GET`	`/api/cases/:id/pr`	Get the linked PR record.
`POST`	`/api/cases/:id/pr/create`	Create a PR for this Work item. Operator action.
`GET`	`/api/cases/:id/pr/draft`	Get the PR draft (title, body, labels).
`PATCH`	`/api/cases/:id/pr`	Update the PR record.

PR review

Zero manages the full PR review lifecycle. Merge stays human — Zero never calls a merge endpoint. See PR review loop.

Method	Path	Description
`GET`	`/api/cases/:id/pr/draft`	Get the PR draft.
`POST`	`/api/cases/:id/pr/create`	Create the PR on GitHub.
`GET`	`/api/cases/:id/pr/ready-check`	Check readiness before marking ready.
`POST`	`/api/cases/:id/pr/mark-ready`	Mark PR ready for review. Posts proof comment.
`GET`	`/api/cases/:id/pr/status`	Current PR status.
`GET`	`/api/cases/:id/pr/state-timeline`	Chronological PR state transitions.
`POST`	`/api/cases/:id/pr/sync-state`	Sync PR state back to GitHub.
`GET`	`/api/cases/:id/pr/reviews`	All reviews for this PR.
`GET`	`/api/cases/:id/pr/reviews/unresolved`	Unresolved reviews blocking progression.
`POST`	`/api/cases/:id/pr/reviews/:review_id/add-to-feedback`	Queue a review for feedback session.
`POST`	`/api/cases/:id/pr/reviews/:review_id/resolve`	Mark a review resolved.
`POST`	`/api/cases/:id/pr/address-feedback`	Run a session to address queued feedback.
`POST`	`/api/cases/:id/pr/comment-proof`	Post proof artifact summary as PR comment.

PR body

Zero composes and maintains the PR body. Suggested updates queue for operator approval — Zero never silently rewrites a published PR body. See PR body composition.

Method	Path	Description
`POST`	`/api/cases/:id/pr-body/compose`	Compose PR body from session summaries and proof.
`GET`	`/api/cases/:id/pr-body/draft`	Get the current composed draft.
`POST`	`/api/cases/:id/pr-body/suggest-update`	Suggest an update after feedback run. Queued for approval.
`POST`	`/api/cases/:id/pr-body/updates/:update_id/approve`	Approve and publish a queued update.

Conflicts and rebase

When a PR branch falls behind main, Zero detects merge conflicts, offers agent-assisted resolution, and lets you push a rebased branch after operator approval. See Conflicts and rebase.

Method	Path	Description
`POST`	`/api/cases/:id/pr/rebase`	Start rebase. Returns conflict file list if conflicts exist.
`GET`	`/api/cases/:id/conflicts/preview`	Raw conflict diff for all conflicting files.
`POST`	`/api/cases/:id/conflicts/resolve-with-agent`	Agent proposes resolution into worktree. No staging yet.
`POST`	`/api/cases/:id/conflicts/apply`	Stage resolved files and complete rebase. Operator-triggered.
`POST`	`/api/cases/:id/conflicts/push-rebased`	Force-with-lease push of rebased branch to remote.
`POST`	`/api/cases/:id/conflicts/abort`	Abort rebase, reset worktree to pre-rebase state.
`GET`	`/api/cases/:id/conflicts/history`	Per-case conflict history: timestamp, file count, outcome.
`GET`	`/api/cases/:id/conflicts/metrics`	Aggregated conflict frequency and resolution time.

Traceability

Traceability returns the full link graph for a workspace: GitHub issue ↔ Work item ↔ session(s) ↔ PR ↔ proof(s). Used for compliance reviews and post-incident audits. Scope is single-workspace — does not query across organizations.

Method	Path	Description
`GET`	`/api/github/traceability`	Return the full traceability graph for the workspace.

curl -s http://localhost:7878/api/github/traceability | jq '.

Export

Export produces a zip archive containing all Work items, sessions, and memory files with a JSON manifest. Use cases: audit trail, migration, offline backup.

Method	Path	Description
`GET`	`/api/export`	Export all Work items, sessions, and memory as a zip archive (markdown + JSON manifest).

API keys

API keys are for tooling integrations. The desktop app uses session auth, not API keys. Keys are managed in the console at /dashboard/keys.

Method	Path	Description
`DELETE`	`/api-keys/:id`	Revoke an API key by ID.

AI providers

AI providers handle session execution — they receive structured prompts from Zero and return execution results. This is separate from work-source integrations (GitHub, Jira, Linear), which supply context for Work items and do not affect session execution.

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.

Method	Path	Description
`GET`	`/providers`	List available providers and availability status. Dev builds only.
`POST`	`/providers/:id/run`	Run a provider with a prompt. Body: `{ "prompt": "string" }`. Dev builds only.

Editor

Operator file editing within a Work item worktree. See In-app editor for usage.

Method	Path	Description
`POST`	`/editor/complete`	Get autocomplete suggestions at cursor position.
`POST`	`/projects/:id/files`	Create or read a file in project scope.
`POST`	`/cases/:id/editor/files`	Create a file in the Work item worktree.
`DELETE`	`/cases/:id/editor/files`	Delete a file from the Work item worktree.
`POST`	`/cases/:id/editor/rename`	Rename a file in the Work item worktree.
`POST`	`/cases/:id/editor/directories`	Create a directory in the Work item worktree.

Language server

Zero proxies language servers (Rust, TypeScript, JavaScript) over a WebSocket bridge. See Language-server diagnostics.

Method	Path	Description
`WS`	`/lsp/:language/ws`	WebSocket upgrade to the language server bridge. Supported values: `rust`, `typescript`, `javascript`.
`POST`	`/lsp/:language/message`	Send a single LSP JSON-RPC message; returns the server response.

System

Method	Path	Description
`GET`	`/health`	Health check. Returns `{ "status": "ok" }`.
`GET`	`/version`	Returns 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.

NEXT STEP

Ready to start? Request early access →