Skip to content

Docs / REST API

REST API

Programmatic access to your audit log, policy, tasks, repos, and billing via the developerz.ai REST API.

REST API

The developerz.ai REST API is served at https://api.developerz.ai/v1.

All endpoints are also accessible via the MCP server — use whichever fits your client. Claude Code and Claude Desktop connect over MCP; scripts and CI workflows typically use REST.

Authentication

Create a personal access token (PAT) in the dashboard under Settings → API tokens, then pass it as a bearer token:

curl https://api.developerz.ai/v1/me \
  -H "Authorization: Bearer dzai_live_…"

Tokens are scoped at creation time. See Scopes below.

Base URL

https://api.developerz.ai/v1

Endpoints

Account

Method Path Scope Description
GET /me read:account Return the authenticated account.

Repositories

Method Path Scope Description
GET /repos read:repos List enabled repos.
GET /repos/:owner/:repo read:repos Get one repo.
GET /repos/:owner/:repo/policy read:repos Read the parsed .maintainer.yml.
POST /repos/:owner/:repo/policy/validate read:repos Validate a policy file without saving.
GET /repos/:owner/:repo/overview read:repos Repo health overview.
GET /repos/:owner/:repo/settings read:repos Repo settings.

Issues

Method Path Scope Description
GET /repos/:owner/:repo/issues read:issues List issues.
GET /issues/:id read:issues Get one issue.
POST /issues/:id/handoff write:issues Trigger a handoff to the coding agent.
POST /issues/:id/escalate write:issues Escalate immediately.

Pull requests

Method Path Scope Description
GET /repos/:owner/:repo/prs read:prs List PRs.
GET /prs/:id read:prs Get one PR.
POST /prs/:id/approve-pending write:prs Approve a pending PR action.
POST /prs/:id/skip-pending write:prs Skip a pending PR action.

Tasks

Method Path Scope Description
GET /tasks read:tasks List fleet tasks.
POST /tasks write:tasks Create a task.

Runners

Method Path Scope Description
GET /runners read:runners List enrolled runners.
GET /runners/:id read:runners Get one runner.
POST /runners/enroll write:runners Enroll a new runner.
POST /runners/:id/revoke write:runners Revoke a runner.

Billing

Method Path Scope Description
GET /billing/keys read:billing List BYOK keys (metadata only, no secrets).
GET /billing/usage read:usage Token usage + handled-unit counts.
POST /billing/portal write:billing Create a Stripe portal session.
POST /billing/cap write:billing Set the monthly spend cap (USD).

API tokens

Method Path Scope Description
GET /tokens read:account List tokens (metadata; secret not returned).
POST /tokens write:account Create a token.
DELETE /tokens/:id write:account Revoke a token.

Audit log (SSE)

Method Path Scope Description
GET /sessions/:id/events read:sessions Server-sent events for one session.
GET /fleet/runs/:runId/events read:tasks SSE for a fleet run.

Scopes

Scope Grants
read:account / write:account Account metadata + tokens
read:repos / write:repos Repos + policy + KB
read:issues / write:issues Issue triage + handoff
read:prs / write:prs PR review + approvals
read:tasks / write:tasks Fleet task queue
read:runners / write:runners Runner enrollment + revoke
read:sessions / write:sessions Audit log + interactive sessions
read:billing / write:billing Billing portal + spend cap
read:usage Token usage counters
read:digests Weekly digest data

Error format

{
  "error": "repo not found",
  "code": "NOT_FOUND"
}

HTTP status codes follow REST conventions: 200 OK, 201 Created, 400 Bad Request (validation), 401 Unauthorized, 403 Forbidden (scope), 404 Not Found, 429 Too Many Requests, 500 Internal Server Error.

Rate limiting

Limits are per-account, per-minute. The response headers carry:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1720000000

OpenAPI / SDK

An OpenAPI 3.1 spec is available at:

GET https://api.developerz.ai/openapi.json

A TypeScript SDK is planned. For now, use curl, fetch, or any HTTP client with the bearer token above. The MCP interface (/docs/mcp-verbs) covers the same surface in a structured, schema-validated way.