Mutations

All writes go through a single endpoint. The action field determines the operation.

POST /api/v1/mutate

Add a Node

Creates a new node with an auto-generated ID.

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "projectId": "my-project",
    "node": {
      "type": "job",
      "parentId": "approach-1",
      "data": {
        "label": "Upload progress bar reaches 100% for a 500MB file",
        "maturity": "mvp",
        "iteration": "MVP"
      }
    }
  }'

Response:

{
  "success": true,
  "node": {
    "id": "job-199",
    "type": "job",
    "parentId": "approach-1",
    "data": {
      "label": "Upload progress bar reaches 100% for a 500MB file",
      "maturity": "mvp",
      "iteration": "MVP"
    }
  }
}

Parent rules

Type	Parent required	Parent type
Goal	No	None
Need	Yes	Goal
Approach	Yes	Need
Job	Yes	Approach
Task	No	None

Update a Node

PATCH semantics. Only include fields you want to change. Existing fields are preserved.

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update",
    "projectId": "my-project",
    "nodeId": "job-45",
    "data": { "status": "done" }
  }'

To mark a job as not done, set status to null.

Delete a Node

Hard delete. The node is removed from the table, but the full node is kept in the changelog, so a delete is recoverable with restore (below).

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "delete",
    "projectId": "my-project",
    "nodeId": "job-99"
  }'

Restore a Node

Recover a hard-deleted node from the changelog. It returns with its original id, type, parentId, and data. Identify it by nodeId (restores the most recent deletion of that node) or by a specific changelogId.

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "restore",
    "projectId": "my-project",
    "nodeId": "job-99"
  }'

409 if a node with that id already exists (nothing to restore). 404 if no deletion is on record.
If the node’s original parent was also deleted, it comes back orphaned (dangling parentId). Restore the parent too, or reparent. The response _meta._tip flags this.
Restore does not cascade. It brings back the single node, not its former children.

Batch Mutations

Multiple operations in a single request. All-or-nothing. If any mutation fails validation, the entire batch is rejected.

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "batch",
    "projectId": "my-project",
    "mutations": [
      {
        "action": "add",
        "node": {
          "type": "job",
          "parentId": "approach-1",
          "data": { "label": "First checkpoint", "iteration": "MVP" }
        }
      },
      {
        "action": "update",
        "nodeId": "job-100",
        "data": { "status": "done" }
      }
    ]
  }'

Idempotency

Make any mutate call (single or batch) safe to retry by sending an Idempotency-Key header. An opaque per-operation string (a UUID is ideal):

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Idempotency-Key: 7b1f2c84-...-your-uuid" \
  -H "Content-Type: application/json" \
  -d '{ "action": "add", "projectId": "my-project", "node": { "type": "goal", "data": { "label": "..." } } }'

Replay. A second request with the same key and the same body returns the original response unchanged (with an Idempotent-Replayed: true header) instead of applying again. An agent that retries after a timeout never double-creates.
Conflict. The same key with a different body returns 409 (you reused a key for a new operation. Generate a fresh one).
In flight. If the first request is still running, a retry returns 409 (“in progress, retry shortly”).
Window. Keys are remembered for 24 hours, then expire. Scope is per user.

Without an Idempotency-Key, retries are not deduplicated, re-read with GET /api/v1/nodes or search and re-submit only what’s missing.

Validation

The API validates all mutations before applying them:

Label is required on all nodes
Parent must exist and be the correct type (need under goal, approach under need, etc.)
Fields must match node type, setting iteration on a goal or maturity on a task is rejected
Kano values: must-have, performance, delighter
Size values: skateboard, vespa, car, truck, antonov
Maturity values: mvp, releasable
Approach status values: development, validation, resolved, retired

Validation errors return { "success": false, "errors": ["..."] }.

Overview

Endpoints

Add a Node

Parent rules

Update a Node

Delete a Node

Restore a Node

Batch Mutations

Idempotency

Validation

​Add a Node

​Parent rules

​Update a Node

​Delete a Node

​Restore a Node

​Batch Mutations

​Idempotency

​Validation

Add a Node

Parent rules

Update a Node

Delete a Node

Restore a Node

Batch Mutations

Idempotency

Validation