API Overview

The ProductBrain API lets LLM agents and scripts read, search, and modify your project. It is the same API that Claude Code, Cursor, and other AI agents use to operate on your planning tree.

Agents and LLMs: the LLM Guide is the canonical contract: every endpoint, field, validation rule, and worked example. Give your agent that one URL and your API key and it has everything. These pages are the human tour of the same surface. Where a page and the guide differ, the guide wins, except where a page says it documents observed behaviour.

Base URL

https://productbrain.com/api/v1

Authentication

Every request carries a Bearer token: a per-user API key generated in the app.

curl -H "Authorization: Bearer pb_your_api_key" \
  "https://productbrain.com/api/v1/nodes?projectId=your-project"

Keys start with pb_, are scoped to your projects, and are generated from Settings → API Keys. See Authentication.

Endpoints at a glance

Search nodes by meaning

GET /api/v1/search?projectId=my-project&q=onboarding+flow&limit=3
# → { results: [{ node: { id, type, parentId, data, createdAt }, similarity: 0.85, ancestors: [...] }],
#     _meta: { query, result_count, applied_limit, applied_type, truncated, weak_match } }

List nodes (with filters)

GET /api/v1/nodes?projectId=my-project&type=job&iteration=MVP
# → { nodes: [{ id, type, parentId, data, createdAt }], _meta: { currentIteration, iterations, nodeCounts } }

Create a node

POST /api/v1/mutate
Idempotency-Key: 7b1f2c84-...
{ "action": "add", "projectId": "my-project",
  "node": { "type": "job", "parentId": "approach-1",
    "data": { "label": "Upload progress reaches 100%", "iteration": "MVP" } } }
# → { success: true, node: { id: "job-42", ... }, _meta: { focus: { nodeId, viewCommand } } }

Update a node

POST /api/v1/mutate
{ "action": "update", "projectId": "my-project",
  "nodeId": "job-42", "data": { "status": "done" } }
# → { success: true, node: { id: "job-42", type, parentId, data } }

Get the current phase

GET /api/v1/iterations?projectId=my-project&current=true
# → { iteration: { name: "MVP", status: "active", system: false, sortOrder: 1, createdAt } }

Navigate the tree

GET /api/v1/tree?projectId=my-project&nodeId=approach-1&direction=context
# → { ancestors: [approach-1, need-3, goal-1], path: [...], siblings: [...], children: [...] }

ancestors starts with the node itself and walks to the root. children is the whole subtree beneath the node, each entry carrying a depth. See Tree.

The full surface

Area	Endpoints	Page
The plan	`GET /nodes`, `GET /search`, `GET /tree`, `POST /mutate`, `GET /iterations`	Nodes, Search, Tree, Mutations, Iterations
The methodology	`GET /workflow`, `POST /workflow`	Workflow
The live view	`POST /view-command`, `GET /view-state`	View control
Projects and access	`GET /projects`, `PATCH /projects`, `GET/POST/DELETE /members`, `GET /tier-status`	Projects, Members, Tier status
Sharing and integrations	`POST/GET/DELETE /share`, `GET/POST/PATCH/DELETE /webhooks`, `GET /export-okf`	Share links, Webhooks, Export
MCP	25 tools, one per endpoint	MCP server

Batches on /mutate are validated as a whole before anything is written. Apply is sequential, and a failure part-way is compensated where that is safe; the Mutations page explains the rolledBack and partial fields.

The `_meta` block

Every endpoint can add a _meta object next to its data. It is advisory and forward-compatible:

_meta._tip: a next-step or recovery hint (what to do on an empty search, why a view command did not apply, that a secret is shown once).
_meta.advisory: structured backpressure, for example { type: "inbox_overflow", memos, threshold, suggestedFlow }.
_meta.focus: { nodeId, viewCommand } after a write, ready to pass to POST /view-command.
_meta.guide: on a 400, 401 or 403 from mutate, search, nodes, tree, iterations and workflow, the URL of the LLM guide.

Read it and adjust. It is there so an agent rarely has to come back to the docs mid-run.

Key principles

Search first

Use /api/v1/search?q=... to find nodes by meaning. Do not pull all nodes and filter. Search uses vector embeddings and returns ranked results with ancestor paths.

One write endpoint

All writes go through /api/v1/mutate. The action field selects the operation: add, update, delete, restore, batch, classify, the phase actions, and the project actions.

For LLM agents

This API is designed as a session contract for LLM agents. Your agent reads the documentation, operates the tree, and the session ends. There is no SDK to update and no version to pin. Changes to the API are reflected in the documentation, and your agent picks them up on the next session. The LLM Guide covers the data model, hierarchy rules, field validation, placement workflow, and worked examples for generating a brain from a codebase or artifact. It is also served as llms.txt and as one plain-text file at llms-full.txt.

Rate limits

The API is rate-limited per IP address, currently 100 requests per 60 seconds. Exceed it and you get an HTTP 429. Back off and retry after about a minute. This is a coarse guard against abuse, not a per-key quota.

The limit is per IP, not per API key. Several clients behind one IP (an office network, a shared CI runner, a serverless platform that reuses egress IPs) share one budget.
Prefer one batch over many calls. POST /api/v1/mutate takes a batch of mutations in a single request.

Rate limits are about request volume, not cost. The whole API surface is credit-free.

Versioning and stability

The API is versioned in the URL path. https://productbrain.com/api/v1 is the current version. The commitment:

We will not break your integration without warning. Breaking changes (removed or renamed fields, endpoints or actions; tightened validation; changed error shapes) only ship in a new version (/api/v2/...).
The previous version keeps working for at least 6 months after a new version ships.
Breaking changes are announced in the changelog at least 30 days before the new version goes live.
Additive changes (new endpoints, new optional fields, new actions) ship on the current version without notice. Write your integration to tolerate unknown fields.

The older unversioned paths keep working and return a Deprecation: true header plus a Link header pointing at the /api/v1 successor. Those headers are stamped on /api/nodes, /api/mutate, /api/search, /api/tree, /api/iterations, /api/projects, /api/view-command, /api/view-state, /api/share and /api/webhooks. /api/workflow, /api/export-okf, /api/tier-status and /api/members also answer on their unversioned paths but carry no headers today. Use /api/v1 for all of them. An unknown or mistyped /api/* path returns 404 with Content-Type: application/json and the body { "error": "unknown_endpoint", ... }, whose _meta._tip lists the valid v1 endpoints. That includes any /api/v2/... path while v2 does not exist, so probing for a version that has not shipped gets a clear answer rather than HTML. Key off error. A client should never see HTML from /api/*; if it does, that is a bug, not a signal about the API. This contract is enforced mechanically: a frozen contract test suite runs in CI against every release candidate, and a breaking change blocks the deploy.

Your data is yours

You can download your entire project at any time: every goal, need, bet, job, task, and phase. No export restrictions and no premium-only data access. The API your agents use to read and write the tree is the same API you use to export everything, as JSON or as an OKF bundle.

# Download your full project
curl -s "https://productbrain.com/api/v1/nodes?projectId=my-project" \
  -H "Authorization: Bearer pb_..." > my-project-backup.json

If ProductBrain stops being useful, your data leaves with you in one command.

Pricing

API access is included on the Builder (

19/mo) and **Team** (

99/mo) plans. The free Builder tier also includes the API, with a per-project node cap. Read the live cap from /tier-status (limits.node_cap) rather than hard-coding a number. Strategist plans use AI features through the app UI instead. Sign up at app.productbrain.com.

Overview

The plan

The view

Projects and access

Integrations

Base URL

Authentication

Endpoints at a glance

Search nodes by meaning

List nodes (with filters)

Create a node

Update a node

Get the current phase

Navigate the tree

The full surface

The `_meta` block

Key principles

Search first

One write endpoint

For LLM agents

Rate limits

Versioning and stability

Your data is yours

Pricing

​Base URL

​Authentication

​Endpoints at a glance

​Search nodes by meaning

​List nodes (with filters)

​Create a node

​Update a node

​Get the current phase

​Navigate the tree

​The full surface

​The _meta block

​Key principles

Search first

One write endpoint

​For LLM agents

​Rate limits

​Versioning and stability

​Your data is yours

​Pricing

Base URL

Authentication

Endpoints at a glance

Search nodes by meaning

List nodes (with filters)

Create a node

Update a node

Get the current phase

Navigate the tree

The full surface

The `_meta` block

Key principles

For LLM agents

Rate limits

Versioning and stability

Your data is yours

Pricing