REST API

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

Most of what it does is also reachable over the MCP server, so use whichever fits your client. Claude Code and Claude Desktop connect over MCP; scripts and CI workflows typically use REST. The two surfaces are not yet a mirror image of each other: the Capability column below is the id they share, so comparing it against the MCP verb list tells you which of the two serves what you need.

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 dev_pat_…"

Tokens are scoped at creation time. See Scopes below.

PAT capability asymmetries

Multi-org context: The dashboard UI session can switch organizations, toggling which org a request sees via the X-Dz-Account header. PATs ignore that header: a token minted in one account stays bound to that account for its entire lifetime. The header is membership-fenced before any route runs on UI sessions, never trusted from a PAT request. If you need to work with multiple organizations, issue a separate PAT in each one.

Personal-only surfaces: The subroutes under /v1/me/ (personal keys, preferences, system prompt) and the routes under /v1/notifications* (inbox, preferences) need a human behind the credential, because "me" has to resolve to somebody. What decides that is whether the token names a user, not that it is a token: a PAT you mint while signed in carries your user id and reaches your own personal data as you, while a token with no human behind it (a box connection token, or a PAT minted before tokens recorded their minter) returns 403 Forbidden on all of them. GET /v1/me is not in that set and always answers: it is the self-check, and it reports the calling credential's own scopes.

Base URL

https://api.developerz.ai

Every path below is absolute and carries its own prefix. The capability surface is versioned under /v1; the handful of routes that are not (/join, /unsubscribe, /gh/installed) are the unversioned legs a browser, a mail client or a fresh box hits without a bearer token.

Collections

Every endpoint that returns a list answers one envelope, so you write one pager and it works everywhere:

{ "data": [ ... ], "next_cursor": "b3AxMDA" }

Send next_cursor straight back as ?cursor= and never parse it: it is opaque and its internals will change. ?per_page= sets the page size, and a value above a collection's maximum is refused rather than quietly clamped, so you always know what you asked for is what you got.

Paging is keyset. A cursor names a position in the collection, not a row count to skip, so it carries the order it was minted under and the sort keys of the last row it gave you. Two things follow. A bare ?cursor= is enough: you do not have to repeat the sort or the per_page that produced it, and changing per_page mid walk continues from the same row instead of rebasing. And rows written while you page never shift the ones you have not read yet, which is what an offset could not promise.

There is no ?page=. A page number is an offset by another name, and on a collection anything is appending to it re-serves rows you already have. Sending one is refused by name rather than ignored, and the error points at next_cursor. Re-sending the same ?sort= alongside a cursor is fine, since a generic pager appends its base parameters to every request; sending a different one is a 400, because the keys you are holding address a place in the old order.

next_cursor: null means there is nothing after this page. That is a promise, not a placeholder. Some collections are always served in full (your org roster, the connectors on an account, the notification category matrix) and those answer null every time and take no paging parameters at all. Any collection that could truncate hands you a real cursor instead, so a null never hides rows you have not seen.

Two endpoints are the exception and say so in their own description: GET /v1/sessions and GET /v1/prs/pending-approvals are bounded summary views behind ?limit=, so a full page there can mean more rows exist and no cursor reaches them. Narrow the request rather than paging it. Everything else keeps the promise above.

?per_page= is the page-size parameter. ?limit= was an older spelling of it on the endpoints that published both, and it is gone: send it and the call is a 400 whose detail names per_page as the replacement, rather than being quietly ignored. Three reads spell their page size limit and keep it, because they never had a ?per_page= beside it and it is their own canonical knob: GET /v1/sessions, GET /v1/prs/pending-approvals and GET /v1/digests.

Endpoints

Generated from the route table the app mounts, so this list cannot drift from what is running. It covers every capability endpoint; the browser login legs (/auth/* and the OAuth callbacks) are not here because they mint a credential rather than spend one.

The Scope column carries what a caller must present. A scope in backticks is asserted by the route. no bearer marks a route mounted before the token guard, whose description names what authorizes it instead (a signed link, a one-time enrollment token, a webhook signature). per request marks a route that authorizes each call inside its handler, so it publishes no single floor.

POST /v1/sessions/:id/replay (under Sessions) has a page of its own, with a runnable example, the diff it returns and when it refuses: Policy replay.

Account

Overview

Personal settings

API tokens

Operator credentials

Org members

Access requests

Users (platform operator)

Invitations

Org SSO

Repositories

Issues

Pull requests

Code review

Asks (work for triage to decide)

Tasks

Blockers

Built-in dashboards

Plans

Runners (fleet boxes)

Agent templates

Prompt variables

CI runs

Artifacts

Sessions

Audit log

Org console

Live streams

Knowledge base

Dashboards

Digests

Notifications

Web push

Email routes

Email bounce status

Outbound webhooks

Integrations

Account secrets

Repository secrets

System prompts

LLM routing

Agent modes

Agents

Billing

Donations

Entitlement grants

Onboarding

MCP

Client error reports

Service

Generated from REST_ROUTES, the route catalog the API mounts. Run bun run api:doc to regenerate.

Scopes

Which scopes does my token hold?

Ask it. GET /v1/me answers a scopes array holding exactly what the credential you called with may do, so a client reads its own limits once instead of discovering them by collecting 403s. MCP callers get the same list from whoami.

That is not the same question as what a new token could carry: GET /v1/tokens answers mintable_scopes, which is your own list minus the classes a self-minted token may never hold, and empty when you lack write:account. Offer that one in a scope picker, and use /v1/me to decide which calls to make.

Error format

Every error is an RFC 9457 problem document, served as application/problem+json:

{
  "type": "https://developerz.ai/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "repo not found",
  "instance": "/v1/repos/acme/widgets",
  "request_id": "4f0c2b8e-2b3a-4d1f-9a6e-6f6a0c2b8e4f"
}

Switch on type, never on title: the slug is a stable contract, the title is prose. detail explains this particular occurrence, instance is the path, and request_id is the correlation id described below. Some errors add extension members: errors carries flattened field errors on a validation failure, and retry_after carries seconds on a 429.

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.

Request ids

Every response carries X-Request-Id, and the same value is the request_id member of any problem body. It is the id your call was logged under, so it is the one string worth quoting when something goes wrong. There is no answer without one: successes, refusals, the unauthenticated endpoints and a 404 for a path that matches no route all carry it.

Send your own and it is adopted verbatim:

curl -i https://api.developerz.ai/v1/repos \
  -H "Authorization: Bearer dev_pat_…" \
  -H "X-Request-Id: ci-run-4711"

A value that is not printable ASCII within 200 characters is not adopted, and one is minted instead. That is deliberately not a 400: this header is often stamped by a proxy you do not control, and a diagnostic must never fail the call it is diagnosing. Nothing is hidden by that, because the id actually used comes back on the same response. So the rule to build on is the narrow one: read the response header to learn which id was used. Log it next to your own call, and a support request becomes one lookup instead of a guess at a timestamp.

Rate limiting

Limits are per token or session, not per account: 600 reads a minute (READ_CAPACITY) and 600 writes a minute (TOKEN_WRITE_CAPACITY), with writes additionally fair-shared at 120 a minute per conversation (WRITE_CAPACITY), plus a 1200-per-minute per-IP bucket applied before your credential is even resolved (PREAUTH_CAPACITY). All four are on rate limits.

Every /v1 response the guard produces carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds, not a timestamp) for the bucket that request was charged against, so a client budgets itself instead of discovering the cap by being throttled. The two publicly cacheable /v1 documents that sit ahead of the guard, GET /v1/openapi.json and the public OSS stats badge, send no such headers: a per-caller counter behind a shared cache would be a wrong number for everyone reading it. Absent headers on those two are the contract, not a protocol failure. A 429 is an RFC 9457 problem document and adds retry-after, the same seconds as RateLimit-Reset. The full contract, including how MCP calls are classified, is on rate limits.

Do not poll a run at 1 Hz. That is 60 reads a minute on one run, a tenth of the read budget, and an agent run can last hours. GET /v1/tasks/:id/events takes ?wait_ms= (up to 25000) and holds the request open until the first new event lands, so watching a run costs well under 1% of your budget instead. The MCP task run_tail verb takes the same argument. See watching a run.

Idempotency

Every authenticated POST, PUT, PATCH and DELETE under /v1 accepts an Idempotency-Key header. Accepting it is not opt-in per route; what a keyed retry gets back is. Most calls replay the first answer, and a call that hands back a credential runs again (below). Send one on a call your client might retry (a phone app, a CI script, a flaky connection):

curl -X POST https://api.developerz.ai/v1/tasks \
  -H "Authorization: Bearer dev_pat_…" \
  -H "Idempotency-Key: 8e6a6c0e-1f2e-4b6a-9c3a-2e7a6c0e1f2e" \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix flaky test"}'

• The first request with a key runs once. A call that succeeds (a 2xx) is stored; a call that fails releases the key, so the retry runs it again. The one exception is a refusal that arrives after the call already created work (a plan that admitted some of its repos): it is stored too, so the retry replays it rather than creating that work twice.
• A retry of the same request with the same key replays the stored response (X-Idempotent-Replayed: true) instead of running it again.
• The same key on a different request is a 409 Conflict. A key is bound to the credential, method, path and body of the call it first ran, so reusing it for anything else is a client bug, not only a changed body.
• Omit the header and the call goes through unconditionally, every time.

Two calls carrying the same key never run at once: the second waits for the first. If the first is still running when that wait runs out, the second answers a 409 with retry-after; send it again once that has passed. A key belongs to the credential that sent it, so another token or session presenting the same string never receives your stored response.

A call that answers a credential shown once never replays. Its response is never stored, so there is nothing to replay. The key still makes same-key calls take turns, but a retry runs the call again: it answers a fresh credential, or the call's own "already done" refusal, never the first answer. Minting a token, enrolling a runner or re-issuing its credentials, creating a webhook (its signing secret), an invitation link and a billing link all work this way.

The rule follows the outcome, not the door and not the status code. The MCP endpoint POST /v1/mcp takes the same header and behaves the same way, verb by verb: a keyed retry of a call that succeeded replays the stored result, so two identical keyed dispatches are one task, and a verb that answers a one-time credential runs again exactly as its REST route does. A failed MCP call arrives inside an HTTP 200, with the failure in the JSON-RPC body, and is still treated as a failure: its key is released and the retry runs, with the same one exception as above.

Treat those calls as non-replayable. When the outcome is unknown (a timeout, a dropped connection), look the resource up before you retry: GET /v1/tokens, GET /v1/webhooks, GET /v1/org/members/invitations, and GET /v1/runners for a box that has already joined. Retry only if it is not there. A blind retry can leave you holding a second token or webhook while the first one's secret is gone for good, so revoke the one you cannot account for.

SDK

The OpenAPI 3.1 document is published at https://api.developerz.ai/v1/openapi.json and is accessible without authentication. Generate a client in any language that supports OpenAPI tooling. For an agent, the MCP interface (/docs/mcp-verbs) is the better target because it carries schema validation and disclosures by design. A REST client is appropriate for scripts and CI workflows.