How do I authenticate?

Send an Authorization: Bearer ttm_ _ header, using a scoped API key minted (and revocable) from Settings → API keys. Keys carry per-namespace scopes (issues:read, issues:write, …). The REST API does not support OAuth; the separate MCP server supports OAuth 2.1 for agent clients.

Is there a command-line client?

@planoda/cli. Run npx @planoda/cli triage "Fix the flaky login test" and get AI-triaged priorities back with no account and no API key — it hits the same public triage endpoint the /tools/triage web demo uses. Authenticated commands (issue create, issue list, whoami) talk to this same v1 REST API with an API key from Settings → API keys, exported as PLANODA_API_KEY.

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, read nextCursor from the response, and pass it back as ?cursor= until it is absent. 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.

Issues, projects, boards, cycles, and automations — every resource the app uses, exposed as a typed, versioned REST API with scoped API keys 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

Scoped API keys

Authenticate with a static API key — `Authorization: Bearer ttm_<prefix>_<secret>` — minted and revoked in Settings → API keys. Keys are scoped (`issues:read`, `issues:write`, …), on the same Clerk-backed identity that protects the product UI. The REST API does not support OAuth; the separate MCP server supports OAuth 2.1 for agent clients.

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

A CLI for your terminal and CI

`@planoda/cli` wraps this same REST API for scripting. `npx @planoda/cli triage "…"` AI-triages a backlog with no account — it calls the public triage endpoint directly, no key required. Authenticated commands (`issue create`, `issue list`, `whoami`) use the identical bearer-token API key as the REST calls above.

No-account `triage` command — public AI backlog triage
`issue create` / `issue list` / `whoami` on the same v1 API
`--json` for CI; zero runtime dependencies

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 '{
    "teamId": "<team-uuid>",
    "title": "Auth fails on Safari 17",
    "priority": 2
  }'

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 ttm_<prefix>_<secret> — a scoped API key minted in Settings → API keys. The REST API does not support OAuth.
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.
npx @planoda/cli triage "…" AI-triages a backlog from the terminal with no account and no API key, wrapping this same API.

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?teamId=…&limit=2http

GET /api/v1/issues?teamId=<team-uuid>&limit=2
Authorization: Bearer ttm_<prefix>_<secret>

200 OKjson

{
  "data": [
    {
      "id": "019f8b13-6c44-7a7f-aa3f-a466b099eaca",
      "number": 142,
      "title": "Auth fails on Safari 17",
      "teamId": "019f8611-375b-793f-9ea5-eef5a0a2bf44",
      "workflowStateId": "019f8611-3a02-7c31-9f0e-2b7c4d1e5a90",
      "priority": 2,
      "assigneeId": "019f8611-38dd-7932-bf4d-74796dc113ed",
      "createdAt": "2026-06-17T09:24:00.000Z"
    }
  ],
  "nextCursor": "eyJyYW5rIjoiMTQyIn0"
}

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

{ "workflowStateId": "<workflow-state-uuid>" }

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. Read nextCursor from the response and pass it back as ?cursor= until it is absent — or let the SDK iterate for you.

@planoda/sdkts

for await (const issue of planoda.issues.listAll({
  teamId: "<team-uuid>",
})) {
  console.log(issue.number);
}

Command-line client

@planoda/cli wraps this same REST API for scripting. Its triage command needs no account at all — the fastest way to feel the product before you ever create a workspace.

npx @planoda/cli triageno signup

$ npx @planoda/cli triage "Fix the flaky login test" "Add dark mode" "Typo in footer"

urgent   Bug       3pt Fix the flaky login test
medium   Feature   5pt Add dark mode
low      Chore     1pt Typo in footer

Pipe a backlog file in instead: cat backlog.txt | npx @planoda/cli triage -

Installbash

npm i -g @planoda/cli
# or run ad-hoc: npx @planoda/cli <command>

Authenticated commandsbash

export PLANODA_API_KEY=<your_api_key>   # Settings → API keys

planoda whoami
planoda issue create --team <teamId> --title "Ship the CLI" --priority 2
planoda issue list --limit 10 --json

Commands

triage [tasks...]AI-triage a backlog — no account, reads stdin when piped with -
issue create--team <id> --title <t> [--description <md>] [--priority 0-4] [--project <id>]
issue list[--team <id>] [--limit <n>]
whoamiShow the authenticated user
help · versionHelp / version

Global options

--api-key <key>API key (or env PLANODA_API_KEY)
--base-url <origin>API origin (or env PLANODA_BASE_URL, default https://planoda.com)
--jsonEmit raw JSON for scripting / CI

Need more than the CLI covers? @planoda/sdk is the same API as a typed TypeScript client.

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.CLINo-signup AI triage, issues from a shell.MCP serverAgents with propose/approve guardrails.WebhooksSigned events, at-least-once delivery.PluginsSandboxed extensions, marketplace.Templates10 importable work-template packs.Full docsGuides, recipes, and the catalog.