> ## Documentation Index
> Fetch the complete documentation index at: https://docs.productbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Read, search, and mutate your ProductBrain project programmatically.

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.

<Note>
  **Agents and LLMs:** the [LLM Guide](https://productbrain.com/docs/llm-guide.md) 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.
</Note>

## Base URL

```
https://productbrain.com/api/v1
```

## Authentication

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

```bash theme={null}
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](/api-reference/authentication).

## Endpoints at a glance

### Search nodes by meaning

```bash theme={null}
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)

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

### Create a node

```bash theme={null}
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

```bash theme={null}
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

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

### Navigate the tree

```bash theme={null}
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](/api-reference/tree).

## The full surface

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

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](/api-reference/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

<CardGroup cols={2}>
  <Card title="Search first" icon="magnifying-glass" href="/api-reference/search">
    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.
  </Card>

  <Card title="One write endpoint" icon="bolt" href="/api-reference/mutations">
    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.
  </Card>
</CardGroup>

## 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](https://productbrain.com/docs/llm-guide.md) 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`](https://productbrain.com/llms.txt) and as one plain-text file at [`llms-full.txt`](https://productbrain.com/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](/changelog/2026-09-11) 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](/api-reference/export-okf).

```bash theme={null}
# 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`](/api-reference/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](https://app.productbrain.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.