-
Notifications
You must be signed in to change notification settings - Fork 0
fix: replace Mintlify branding and add real API reference #2
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+142
−97
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| .DS_Store | ||
| node_modules/ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,55 +1,32 @@ | ||
| # Mintlify Starter Kit | ||
| <div align="center"> | ||
|
|
||
| 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 | ||
| [](https://docs.usezombie.com) | ||
| [](https://usezombie.com) | ||
| [](https://opensource.org/licenses/MIT) | ||
|
|
||
| **[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)** | ||
| </div> | ||
|
|
||
| ## 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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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.' | ||
| --- | ||
|
|
||
| <Info> | ||
| This reference covers the public spec submission and run management API. Internal endpoints (authentication sessions, billing, harness management, agent profiles) are not documented here. | ||
| </Info> | ||
|
|
||
| ## 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 <token>" \ | ||
| 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. | ||
|
|
||
| <Card | ||
| title="OpenAPI Spec" | ||
| icon="code" | ||
| href="https://api.usezombie.com/openapi.json" | ||
| > | ||
| View the full OpenAPI 3.1 specification | ||
| </Card> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.