Skip to main content
The ProductBrain API lets LLM agents and scripts read, search, and modify your project. It’s 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 complete, machine-readable contract, every endpoint, field, validation rule, and worked example. Give your agent that one URL and your API key and it has everything. This page is the human tour of the same surface.

​
Base URL

https://productbrain.com/api/v1

​
Authentication

All requests require a Bearer token. A per-user API key generated from 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 can be generated from Settings → API Keys. See Authentication for details.

​
Endpoints at a Glance

​
Search nodes by meaning

GET /api/v1/search?projectId=my-project&q=onboarding+flow&limit=3
# → { results: [{ node: { id, type, data }, similarity: 0.85, ancestors: [...] }] }

​
List nodes (with filters)

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

​
Create a node

POST /api/v1/mutate
{ "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", ... } }

​
Update a node

POST /api/v1/mutate
{ "action": "update", "projectId": "my-project",
  "nodeId": "job-42", "data": { "status": "done" } }

​
Get current iteration

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

GET /api/v1/tree?projectId=my-project&nodeId=approach-1&direction=context
# → { ancestors: [...], siblings: [...], children: [...] }
Full details for these: Nodes · Search · Mutations · Iterations.

​
The full surface an agent can operate

  • Plan the tree, read, semantic-search, and mutate (/nodes, /search, /mutate, /tree), with batch all-or-nothing writes and re-embedding on change.
  • Drive the live view, switch tree/matrix, select a phase, expand, focus, and zoom the canvas in real time (/view-command), and read back exactly what the user is looking at (/view-state).
  • Run the methodology, drive ProductBrain’s planning state machine with your own LLM, consuming zero AI credits (/workflow).
  • Manage lifecycle, share links mint / list / revoke / expire (/share). Webhooks register / update / rotate with HMAC signing (/webhooks).
  • Self-coaching responses, calls carry a _meta block: next-step hints, wrong-endpoint redirects, and a read-back of what each call did.
The LLM Guide is the complete, current reference for all of it. The canonical contract your agent reads.

​
Key Principles

Search first

Use /api/v1/search?q=... to find nodes by meaning. Don’t 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 determines the operation: add, update, delete, restore, or batch.

​
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 are no client-side dependencies to maintain, no SDK to update, no webhooks to rewire, no version pinning. Changes to the API are reflected in the documentation immediately. Your agent picks them up on the next session. The LLM Operations Guide is the canonical reference for any AI agent operating on ProductBrain. It covers the data model, hierarchy rules, field validation, placement workflow, and worked examples for generating a brain from a codebase or artifact. Give your agent this URL and your API key. It has everything it needs to get started.

​
Rate limits

The API is rate-limited per IP address, currently around 100 requests per minute. Exceed it and you get an HTTP 429. Back off and retry after about a minute. It’s a coarse, infrastructure-level guard against abuse, not a fine-grained per-key quota. Two honest caveats:
  • The limit is per IP, not per API key (for now). If you drive the API from several clients behind one IP, an office network, a shared CI runner, a serverless platform that reuses egress IPs. They share one budget and can throttle each other. A per-key limit is on the roadmap. Until it ships, give a heavy workload its own IP.
  • Prefer one batch over many calls. POST /api/v1/mutate takes a batch of mutations in a single request. It’s faster and stays well under the limit.
Rate limits are about request volume, not cost: the API surface is credit-free.

​
Versioning & 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.
Older unversioned paths (/api/nodes,…) keep working indefinitely and return a Deprecation: true header plus a Link header pointing at the /api/v1 successor. If your client sees those headers, switch the base URL to /api/v1, nothing else changes. 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 as JSON at any time, every goal, need, approach, job, task, and phase. No export restrictions, no premium-only data access, no lock-in. The API that your agents use to read and write the tree is the same API you use to export everything. 
# Download your full project
curl -s "https://productbrain.com/api/v1/nodes?projectId=my-project" \
  -H "Authorization: Bearer pb_..." > my-project-backup.json
This is a commitment, not a feature. We believe a product should compete on the value it creates, not the cost of leaving. If ProductBrain stops being useful, your data leaves with you in one command.

​
Pricing

API access is included on the Builder (39/mo)and∗∗Team∗∗(39/mo) and **Team** (99/mo) plans. Free and Strategist plans use AI features through the app UI. Sign up at app.productbrain.com.