diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..646ac51 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +node_modules/ diff --git a/README.md b/README.md index 4552fbc..b0b012b 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,32 @@ -# Mintlify Starter Kit +
-Use the starter kit to get your docs deployed and ready to customize. +# UseZombie Docs -Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with +**Documentation site for UseZombie — submit a spec, get a validated PR.** -- Guide pages -- Navigation -- Customizations -- API reference pages -- Use of popular components +[![Docs](https://img.shields.io/badge/UseZombie-Docs-blue?style=for-the-badge)](https://docs.usezombie.com) +[![Try Free](https://img.shields.io/badge/UseZombie-Try_Free-brightgreen?style=for-the-badge)](https://usezombie.com) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) -**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)** +
-## AI-assisted writing - -Set up your AI coding tool to work with Mintlify: - -```bash -npx skills add https://mintlify.com/docs -``` - -This command installs Mintlify's documentation skill for your configured AI tools like Claude Code, Cursor, Windsurf, and others. The skill includes component reference, writing standards, and workflow guidance. - -See the [AI tools guides](/ai-tools) for tool-specific setup. +--- ## Development -Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command: +Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview documentation changes locally: -``` +```bash npm i -g mint -``` - -Run the following command at the root of your documentation, where your `docs.json` is located: - -``` mint dev ``` View your local preview at `http://localhost:3000`. -## Publishing changes - -Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch. - -## Need help? +## Publishing -### Troubleshooting +Changes pushed to the default branch are deployed automatically via the [Mintlify GitHub app](https://dashboard.mintlify.com/settings/organization/github-app). -- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI. -- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`. +## License -### Resources -- [Mintlify documentation](https://mintlify.com/docs) +MIT — Copyright (c) 2026 UseZombie diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 6b8c767..2a9abec 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,70 +1,60 @@ --- -title: API overview -description: REST API for programmatic spec submission and run management. +title: 'API Reference' +description: 'UseZombie Control Plane API — spec-to-PR automation.' --- - - This reference covers the public spec submission and run management API. Internal endpoints (authentication sessions, billing, harness management, agent profiles) are not documented here. - - ## Base URL -| Environment | URL | -|-------------|-----| -| Production | `https://api.usezombie.com/v1` | -| Development | `https://api-dev.usezombie.com/v1` | +``` +https://api.usezombie.com +``` ## Authentication -All API requests require a Bearer token in the `Authorization` header: +All API endpoints require a Bearer token in the `Authorization` header, except health checks and the initial auth session creation. ```bash -curl -H "Authorization: Bearer " \ - https://api.usezombie.com/v1/runs +curl https://api.usezombie.com/v1/runs \ + -H "Authorization: Bearer $ZOMBIE_TOKEN" ``` -Get a token via `zombiectl login` or the Clerk API. +Obtain a token via the CLI login flow (`zombiectl login`) or by creating an auth session programmatically: -## Content type +1. `POST /v1/auth/sessions` — returns a `login_url` and `session_id` +2. Complete the OAuth flow in the browser +3. `GET /v1/auth/sessions/{session_id}` — poll until `status: "complete"`, then extract the `token` -All requests and responses use `application/json`. +## Errors -## Error envelope - -Errors return a structured JSON envelope: +All errors follow a consistent format: ```json { "error": { - "code": "SPEC_VALIDATION_FAILED", - "message": "File reference 'src/missing.ts' does not exist in repository." - } + "code": "WORKSPACE_NOT_FOUND", + "message": "No workspace with the given ID exists." + }, + "request_id": "req_01JQ7K..." } ``` -### Error codes - -| Code | Meaning | -|------|---------| -| `WORKSPACE_PAUSED` | Workspace is paused, no new runs accepted | -| `INVALID_STATE_TRANSITION` | Run is not in a valid state for this operation | -| `SPEC_VALIDATION_FAILED` | Spec failed structural or file reference validation | -| `DUPLICATE_RUN` | Active run with same spec hash + repo + base commit exists | -| `CREDIT_EXHAUSTED` | Free plan credit depleted | -| `BUDGET_EXCEEDED` | Workspace monthly budget exceeded | -| `UNAUTHORIZED` | Missing or invalid auth token | -| `FORBIDDEN` | Insufficient role for this operation | +Every response includes a `request_id` for tracing. -## Agent route isolation +## Conventions -The `/agents` path is isolated from the human pipeline with separate authentication and rate limits. External agents (Claude Code, Codex, OpenCode) submit specs via this route for agent-to-agent workflows. - -## Agent relay endpoint - -`POST /v1/agent/stream` is a stateless relay for lightweight agent interactions. The CLI sends tool definitions and messages, `zombied` adds the workspace's LLM API key and system prompt, forwards to the configured provider, and streams the response back as SSE. - -This endpoint powers `spec init` and `run --preview`. See the [agent relay model](/how-it-works#agent-relay-model) for the full architecture and the [endpoint reference](/api-reference/endpoint/agent-stream) for request/response details. +- **IDs** are UUIDs. +- **Timestamps** are Unix milliseconds. +- **Action endpoints** use `:action` suffix (e.g., `/v1/runs/{run_id}:cancel`). +- **Streaming endpoints** (replay, stream, agent relay) return Server-Sent Events. ## Rate limits -Rate limits are applied per workspace. Specific limits vary by plan tier. Rate-limited responses return HTTP 429 with a `Retry-After` header. +API rate limits are per-workspace. If you hit a rate limit, the response includes a `Retry-After` header. + + + View the full OpenAPI 3.1 specification + diff --git a/docs.json b/docs.json index 66241f9..161b4ba 100644 --- a/docs.json +++ b/docs.json @@ -67,6 +67,7 @@ }, { "tab": "API reference", + "openapi": "https://raw.githubusercontent.com/usezombie/usezombie/main/public/openapi.json", "groups": [ { "group": "Overview", @@ -75,30 +76,106 @@ ] }, { - "group": "Runs", + "group": "Health", + "pages": [ + "GET /healthz", + "GET /readyz", + "GET /metrics" + ] + }, + { + "group": "Authentication", "pages": [ - "api-reference/endpoint/create-run", - "api-reference/endpoint/get-run", - "api-reference/endpoint/retry-run" + "POST /v1/auth/sessions", + "GET /v1/auth/sessions/{session_id}", + "POST /v1/auth/sessions/{session_id}/complete", + "GET /v1/github/callback" ] }, { - "group": "Agent relay", + "group": "Workspaces", "pages": [ - "api-reference/endpoint/agent-stream" + "POST /v1/workspaces", + "POST /v1/workspaces/{workspace_id}:pause", + "POST /v1/workspaces/{workspace_id}:sync" ] }, { "group": "Specs", "pages": [ - "api-reference/endpoint/list-specs" + "GET /v1/specs" ] }, { - "group": "Workspaces", + "group": "Runs", + "pages": [ + "POST /v1/runs", + "GET /v1/runs", + "GET /v1/runs/{run_id}", + "POST /v1/runs/{run_id}:retry", + "GET /v1/runs/{run_id}:replay", + "GET /v1/runs/{run_id}:stream", + "POST /v1/runs/{run_id}:cancel" + ] + }, + { + "group": "Agents", + "pages": [ + "GET /v1/agents/{agent_id}", + "GET /v1/agents/{agent_id}/scores", + "GET /v1/agents/{agent_id}/improvement-report", + "GET /v1/agents/{agent_id}/proposals", + "POST /v1/agents/{agent_id}/proposals/{proposal_id}:approve", + "POST /v1/agents/{agent_id}/proposals/{proposal_id}:reject", + "POST /v1/agents/{agent_id}/proposals/{proposal_id}:veto", + "POST /v1/agents/{agent_id}/harness/changes/{change_id}:revert" + ] + }, + { + "group": "Harness", + "pages": [ + "PUT /v1/workspaces/{workspace_id}/harness/source", + "POST /v1/workspaces/{workspace_id}/harness/compile", + "POST /v1/workspaces/{workspace_id}/harness/activate", + "GET /v1/workspaces/{workspace_id}/harness/active" + ] + }, + { + "group": "Credentials", "pages": [ - "api-reference/endpoint/pause-workspace", - "api-reference/endpoint/sync-workspace" + "PUT /v1/workspaces/{workspace_id}/credentials/llm", + "GET /v1/workspaces/{workspace_id}/credentials/llm", + "DELETE /v1/workspaces/{workspace_id}/credentials/llm" + ] + }, + { + "group": "Skill Secrets", + "pages": [ + "PUT /v1/workspaces/{workspace_id}/skills/{skill_ref}/secrets/{key_name}", + "DELETE /v1/workspaces/{workspace_id}/skills/{skill_ref}/secrets/{key_name}" + ] + }, + { + "group": "Agent Relay", + "pages": [ + "POST /v1/workspaces/{workspace_id}/spec/template", + "POST /v1/workspaces/{workspace_id}/spec/preview" + ] + }, + { + "group": "Admin", + "pages": [ + "GET /v1/admin/platform-keys", + "PUT /v1/admin/platform-keys", + "DELETE /v1/admin/platform-keys/{provider}" + ] + }, + { + "group": "Billing", + "pages": [ + "POST /v1/workspaces/{workspace_id}/billing/scale", + "POST /v1/workspaces/{workspace_id}/billing/events", + "POST /v1/workspaces/{workspace_id}/scoring/config" ] } ] @@ -106,15 +183,15 @@ ], "global": { "anchors": [ + { + "anchor": "Website", + "href": "https://usezombie.com", + "icon": "globe" + }, { "anchor": "GitHub", "href": "https://github.com/usezombie/usezombie", "icon": "github" - }, - { - "anchor": "Blog", - "href": "https://usezombie.com/blog", - "icon": "newspaper" } ] } @@ -150,9 +227,8 @@ }, "footer": { "socials": { - "x": "https://x.com/usezombie", "github": "https://github.com/usezombie", - "discord": "https://discord.gg/usezombie" + "discord": "https://discord.gg/H9hH2nqQjh" } } }