Diff (and optionally apply) a plan document against the live board

POST

/board/sync-plan

curl --request POST \
  --url https://example.com/api/board/sync-plan \
  --header 'Content-Type: application/json' \
  --cookie sb-access-token=<sb-access-token> \
  --data '{ "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "mode": "dry_run", "plan": {} }'

• AppHandoff API

Parses a plan document, diffs it against the live board (programs, milestones, plan-managed tickets) for the target project, and either reports the diff (mode: dry_run, the default) or applies it (mode: apply). dry_run never touches the DB. apply is refused whole when the diff has conflicts (PLAN_CONFLICT) or when any op fails partway through (PLAN_PARTIAL) — both return the receipt so far for inspection. Board edits are protected (plan rule 11): a field changed on the board since the last sync is reported as a conflict board edit on <kind> <key>: <field> and never overwritten, unless that program, milestone or ticket carries force: true in the plan document (optional boolean per item), which overwrites it with a receipt warning.

Authorizations

• cookieAuth

Request Body ^required

Media type application/json

object

project_id

required

string format: uuid

mode

string

default: dry_run

Allowed values: dry_run apply

plan

required

The plan document (programs, milestones, tickets) to diff against the board.

object

Responses

200

Diff report (dry_run) or write receipt (apply)

Media type application/json

object

receipt

required

object

key

additional properties

any

diff_summary

required

object

key

additional properties

any

ops

Full op list — dry_run responses only.

Array<object>

object

key

additional properties

any

400

Plan failed schema validation

Media type application/json

object

error

required

string

code

required

string

Allowed values: PLAN_INVALID

issues

Array<object>

object

key

additional properties

any

401

Not authenticated

Media type application/json

object

error

required

Human-readable error message

string

code

Stable machine-readable error code for client branching

string

fieldErrors

First validation message per field path

object

key

additional properties

string

issues

Structured validation issues (Zod)

Array<object>

object

path

required

string

message

required

string

retryAfter

Seconds until rate limit resets (429 responses)

number

reconnect

True if re-linking GitHub may fix the issue

boolean

403

Forbidden

Media type application/json

object

error

required

Human-readable error message

string

code

Stable machine-readable error code for client branching

string

fieldErrors

First validation message per field path

object

key

additional properties

string

issues

Structured validation issues (Zod)

Array<object>

object

path

required

string

message

required

string

retryAfter

Seconds until rate limit resets (429 responses)

number

409

Apply blocked by board conflicts, or partially applied

Media type application/json

object

error

required

string

code

required

string

Allowed values: PLAN_CONFLICT PLAN_PARTIAL

receipt

required

object

key

additional properties

any

diff_summary

required

object

key

additional properties

any

429

Rate limited

Media type application/json

object

error

required

Human-readable error message

string

code

Stable machine-readable error code for client branching

string

fieldErrors

First validation message per field path

object

key

additional properties

string

issues

Structured validation issues (Zod)

Array<object>

object

path

required

string

message

required

string

retryAfter

Seconds until rate limit resets (429 responses)

number

retryAfter

Seconds until the rate limit resets

number

Headers

Retry-After

string