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, /actions/:jwt, /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.

Account

Personal settings

API tokens

Org members

Invitations

Org SSO

Repositories

Issues

Pull requests

Code review

Tasks

Blockers

Plans

Runners (fleet boxes)

Agent templates

Prompt variables

CI runs

Artifacts

Sessions

Audit log

Live streams

Knowledge base

Dashboards

Digests

Notifications

Web push

Email routes

Outbound webhooks

Integrations

Account secrets

Repository secrets

System prompts

LLM routing

Billing

Donations

Entitlement grants

Onboarding

MCP

Service

Generated from REST_ROUTES (apps/api/src/catalog.ts). 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: 60 reads and 10 writes per minute, plus a 300-per-minute per-IP bucket applied before your credential is even resolved.

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. Sixty reads a minute IS 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 about 4% of your budget instead of all of it. The MCP task run_tail verb takes the same argument. See watching a run.

Idempotency

Every POST, PUT, PATCH and DELETE under /v1 accepts an Idempotency-Key header, uniformly across every write endpoint, not opt-in per route. 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 and caches the response.
• A retry with the same key and body replays that cached response (X-Idempotent-Replayed: true) instead of running it again.
• The same key with a different body is a 409 Conflict, a client bug.
• Omit the header and the call goes through unconditionally, every time.

Keys are scoped to the caller, so two tokens sharing the same string never alias each other's responses. Routes that hand back a one-time secret (minting a token, enrolling a runner) never cache their response, so a retry always mints a fresh credential rather than replaying the first one.

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.