What is the base URL?

All REST endpoints live under https://planoda.com/api/v1. The machine-readable OpenAPI 3.1 spec is served at /api/v1/openapi.json and regenerated from the routers on every deploy, so codegen never drifts.

How does pagination work?

List endpoints are cursor-paginated. Pass ?limit=50 and read the next cursor from the response's pageInfo.endCursor; request the next page with ?cursor= . The SDK exposes an async iterator (for await … of client.issues.listAll()) that follows cursors for you.

What are the rate limits?

Limits are enforced per token and per route. Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; a 429 includes Retry-After. Back off on Retry-After rather than guessing — the SDK does this automatically.

Are writes idempotent?

Yes. Send an Idempotency-Key header on any POST/PATCH and a retry with the same key returns the original result instead of creating a duplicate, so a network blip never double-creates an issue.

REST or tRPC — which should I use?

Both speak the same contract. Use REST from any language; in TypeScript, import the tRPC types (or the @planoda/sdk client generated from them) for end-to-end inference with zero hand-maintained schema.

Developers

A REST API that mirrors the product.

Q: How do I authenticate?

Send an Authorization: Bearer header. Use a personal API token for scripts and back-end jobs, or OAuth 2.0 with PKCE for third-party apps acting on a user's behalf. Tokens are scoped (issues:read, boards:write, …) and revocable from the workspace settings.

Issues, projects, boards, cycles, and automations — every resource the app uses, exposed as a typed, versioned REST API with OAuth and webhooks.

Get an API key All developer docs

Typed, predictable, versioned

Every resource — issues, projects, boards, cycles, comments — maps to a stable REST endpoint with the same shape the app uses. Responses are JSON; errors are structured with a stable `code`, a human `message`, and field-level `details`.

Cursor-paginated list endpoints
Idempotency keys on writes
Per-token, per-route rate limits with `RateLimit-*` headers

REST and tRPC, one contract

The product runs on tRPC v11; the public REST surface is generated from the same routers, so both speak an identical schema. Use REST from any language, or import the tRPC types in TypeScript for end-to-end inference with zero drift.

Versioned under `/api/v1`
tRPC v11 procedures power the same resources
No hand-maintained second contract to fall out of sync

OpenAPI 3.1, always current

A machine-readable spec lives at `/api/v1/openapi.json` — generated from the routers on every deploy, never written by hand. Point your codegen at it for typed clients in any language, or load it into Postman, Insomnia, or an MCP-aware agent.

Served at `/api/v1/openapi.json`
Drives our own SDK generation
Import into Postman / Insomnia in one click

OAuth + personal tokens

Authenticate with a personal API token for scripts, or OAuth 2.0 with PKCE for third-party apps acting on a user's behalf. Tokens are scoped (`issues:read`, `boards:write`, …) and revocable, on the same Clerk-backed identity that protects the product UI.

Webhooks for everything

Subscribe to issue, comment, and automation events. Payloads are HMAC-SHA-256 signed so you can verify authenticity before acting.

Signed payloads
At-least-once delivery
Replay from the dashboard

POST /api/v1/issues

curl https://planoda.com/api/v1/issues \
  -H "Authorization: Bearer $PLANODA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-create-auth-bug" \
  -d '{
    "team": "ENG",
    "title": "Auth fails on Safari 17",
    "priority": "high"
  }'

Full reference in the docs.

Start building

Build on the API.

Free tier includes API access. Build, automate, and integrate.

Get started — free See integrations

API in short

Base URL: https://planoda.com/api/v1. Authenticate with Authorization: Bearer <token> — a personal API token for scripts, or OAuth 2.0 + PKCE for third-party apps.
Resources (issues, projects, boards, cycles, comments, webhooks) map to stable REST endpoints; the OpenAPI 3.1 spec is served at /api/v1/openapi.json.
List endpoints are cursor-paginated; writes accept an Idempotency-Key; every response carries RateLimit-* headers and a 429 returns Retry-After.
The public REST surface is generated from the same tRPC v11 routers the product runs on, so there is no second contract to drift.

Representative endpoints

A slice of the surface. The full, always-current catalog is in the OpenAPI spec at /api/v1/openapi.json.

GET/api/v1/issuesList issues (cursor-paged)
POST/api/v1/issuesCreate an issue
GET/api/v1/issues/{id}Fetch one issue
PATCH/api/v1/issues/{id}Update an issue
GET/api/v1/projectsList projects
POST/api/v1/webhooksRegister a webhook

List issues

GET /api/v1/issues?team=ENG&limit=2http

GET /api/v1/issues?team=ENG&state=started&limit=2
Authorization: Bearer $PLANODA_TOKEN

200 OKjson

{
  "data": [
    {
      "id": "iss_8f3a2c",
      "identifier": "ENG-142",
      "title": "Auth fails on Safari 17",
      "state": { "name": "In Progress", "type": "started" },
      "priority": "high",
      "assignee": { "id": "usr_31a", "name": "Ada L." },
      "createdAt": "2026-06-17T09:24:00Z"
    }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "eyJjIjoiMTQyIn0"
  }
}

Create & update

POST /api/v1/issues → 201 Createdjson

{
  "id": "iss_9b71e4",
  "identifier": "ENG-143",
  "title": "Auth fails on Safari 17",
  "priority": "high",
  "url": "https://planoda.com/acme/issue/ENG-143"
}

PATCH /api/v1/issues/iss_9b71e4http

PATCH /api/v1/issues/iss_9b71e4
Authorization: Bearer $PLANODA_TOKEN
Content-Type: application/json

{ "stateId": "wfs_done", "assigneeId": "usr_31a" }

Error shape (422)json

{
  "error": {
    "code": "validation_failed",
    "message": "priority must be one of none|low|medium|high|urgent",
    "details": [{ "path": "priority", "issue": "invalid_enum" }],
    "requestId": "req_4c2f…"
  }
}

Rate limits

Enforced per token and per route. Inspect the headers on every response and back off on Retry-After when you see a 429.

Response headers

RateLimit-Limit: 600
RateLimit-Remaining: 581
RateLimit-Reset: 41
Retry-After: 41   # only on 429

Pagination

Cursor-based. Follow pageInfo.endCursor until hasNextPage is false — or let the SDK iterate for you.

@planoda/sdkts

for await (const issue of planoda.issues.listAll({
  team: "ENG",
})) {
  console.log(issue.identifier);
}

FAQ

API questions, answered

The public REST surface is generated from the same tRPC v11 routers the product runs on — when the product gets faster, your scripts get faster too.

Developer resources

Everything you need to build on Planoda.

API referenceREST + tRPC, OAuth, rate limits.TypeScript SDKTyped client, retries, webhooks.MCP serverAgents with propose/approve guardrails.WebhooksSigned events, at-least-once delivery.PluginsSandboxed extensions, marketplace.Full docsGuides, recipes, and the catalog.

Typed, predictable, versioned

Cursor-paginated list endpoints

Idempotency keys on writes

Per-token, per-route rate limits with `RateLimit-*` headers