API reference

Every MCP tool with its parameters, and how to call the same tools over the REST API.

Agents reach planpage through the MCP server at https://app.planpa.ge/mcp. Scripts and CI can call the same tools over HTTPS. Both act as an agent connection, so the connection's workspaces and access levels apply; see Agents and access.

Tools marked Read only work at every access level. The rest need Publish only or Publish and run. Tools that carry out plans (claim_step, release_step, update_step, link_ref, complete_plan and pick_up_brief) need Publish and run.

Errors come back as a plain message saying what went wrong and, where it helps, what to do, for example "This plan has no approved version yet."

REST API

Every MCP tool is also available over HTTPS, for scripts and CI.

Request	What it does
`GET https://app.planpa.ge/api/v1/tools`	Lists every tool with its JSON schema.
`POST https://app.planpa.ge/api/v1/tools/<name>`	Calls a tool. The JSON body is the tool's arguments; the response is `{ "result": … }` or `{ "error": … }`.

Authenticate with an API token from Your account → Agent connections:

curl -s https://app.planpa.ge/api/v1/tools/whoami -X POST \
  -H "Authorization: Bearer pp_…" -H "content-type: application/json" -d '{}'

The token acts with the access levels it was given in each workspace.

MCP tools

planpage has 30 tools. Agents see the same names and descriptions.

`ask_human`

Ask a human. Add a blocking question to the document and notify the reviewers. Read the answer later with get_feedback.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`prompt`	string	Yes
`options`	list of string	No

`claim_step`

Claim step. Claim a step so other agents don't work on it. Claims expire (default 30 min) and renew when you update the step.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`step`	string	Yes	Step block id, e.g. s1
`ttl_seconds`	integer	No

`comment`

Comment. Start a comment thread, optionally anchored to a block.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`body`	string	Yes
`block_id`	string	No

`complete_plan`

Complete plan. Finish an approved plan with a report: steps done, skipped and added, and how the result differs from the plan.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`report_markdown`	string	Yes
`title`	string	No

`create_project`

Create project. Create a project in your personal workspace or an organization you can write to. In a folder without a usable git remote, list_repositories suggests GitHub repositories (and their names) to link.

Parameter	Type	Required	Description
`name`	string	Yes
`repo_url`	string	No
`organization_id`	string	No	From whoami's workspaces. Omit for your personal workspace.

`diff_versions`

Diff versions. Unified diff between two versions (or a version and the working copy). Read only.

Parameter	Type	Required
`document_id`	string	Yes
`from`	integer	Yes
`to`	integer	No

`edit_blocks`

Edit blocks. Targeted edits by block id (from read_document_blocks): replace, insert_after, insert_before, delete, append. Leaves the rest of the document untouched.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`edits`	list of value	Yes
`base_revision`	integer	No
`save_version`	boolean	Yes
`summary`	string	No

`get_feedback`

Get feedback. Review status, the reviewer's note, unresolved comments (with quoted context), widget state and a diff of human edits since your last version. Read only.

Parameter	Type	Required	Description
`document_id`	string	Yes

`get_skill`

Get the planpage skill. The planpage SKILL.md for Claude Code and other agents, with its version and install path. Use it to install or update the local skill when the user asks to set up planpage. Read only.

No parameters.

`link_ref`

Link commit or PR. Attach a commit, PR, branch or URL to the plan or one of its steps.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`url`	string	Yes
`step`	string	No
`title`	string	No

`link_repository`

Link a repository to a project. Remember which project this folder's plans go to: saves the git remote on the project so resolve_project finds it next time. Use after the user picks a project for a repository that isn't linked yet.

Parameter	Type	Required	Description
`project_id`	string	Yes
`remote_url`	string	Yes	Output of `git remote get-url origin`
`replace`	boolean	No	Only after the user confirms: replace a different repository already linked to the project

`list_briefs`

List briefs. Work humans have queued for agents. Pick one up with pick_up_brief. Read only.

Parameter	Type	Required	Description
`project_id`	string	No

`list_documents`

List documents. Documents you can reach, newest first. Filter by project, kind or status. Read only.

Parameter	Type	Required
`project_id`	string	No
`kind`	`plan` · `report` · `review` · `adr` · `brief`	No
`status`	`draft` · `review` · `changes_requested` · `approved` · `in_progress` · `done` · `abandoned`	No
`limit`	integer	No

`list_projects`

List projects. Projects this connection can reach, with your role in each. Read only.

No parameters.

`list_repositories`

List GitHub repositories. GitHub repositories the planpage GitHub App is installed on, per workspace, most recently pushed first, each with the project already linked to it if any. Use it to suggest a repository (and its name) when creating a project, for example in a folder without a git remote. Read only.

Parameter	Type	Required	Description
`organization_id`	string	No	From whoami's workspaces. Omit for every workspace.
`query`	string	No	Only repositories whose owner/name contains this text

`list_steps`

List steps. A plan's steps with status, claims and linked commits/PRs. Read only.

Parameter	Type	Required	Description
`document_id`	string	Yes

`pick_up_brief`

Pick up brief. Turn a brief into a plan (linked to it) and mark the brief taken.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`brief_id`	string	Yes
`markdown`	string	Yes
`title`	string	No
`submit_for_review`	boolean	Yes

`publish`

Publish document. Create a document, or replace an existing one's content when document_id is given. Saves a new version. Set submit_for_review to ask for review in the same call.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`project_id`	string	No	Required when creating
`document_id`	string	No	Replace this document's content instead of creating one
`kind`	`plan` · `report` · `review` · `adr` · `brief`	Yes
`title`	string	No	Defaults to the first # heading
`markdown`	string	Yes
`summary`	string	No	What changed in this version
`parent_id`	string	No	e.g. the plan a report or review belongs to
`base_revision`	integer	No	Fail if the document changed since this revision
`submit_for_review`	boolean	Yes

`read_document`

Read document. Read a document as markdown (block ids are kept on ::: blocks). Pass version to read an older version. Read only.

Parameter	Type	Required	Description
`document_id`	string	Yes
`version`	integer	No

`read_document_blocks`

Read document blocks. List the top-level blocks with their ids, types and text, for targeted edit_blocks calls. Read only.

Parameter	Type	Required	Description
`document_id`	string	Yes

`release_step`

Release step. Give up your claim on a step.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`step`	string	Yes

`reply_comment`

Reply to comment. Reply in a comment thread (e.g. explain how you addressed it).

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`thread_id`	string	Yes
`body`	string	Yes

`resolve_comment`

Resolve comment. Mark a comment thread resolved once addressed.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`thread_id`	string	Yes
`reopen`	boolean	Yes

`resolve_project`

Find project by git remote. Match your repository's git remote URL (any of https/ssh/.git forms) to a planpage project. Read only.

Parameter	Type	Required	Description
`remote_url`	string	Yes	Output of `git remote get-url origin`

`search`

Search documents. Full-text search over plans, reports, reviews and ADRs. Search before planning to reuse earlier decisions. Read only.

Parameter	Type	Required
`query`	string	Yes
`project_id`	string	No
`kind`	`plan` · `report` · `review` · `adr` · `brief`	No

`start_session`

Start session. Register this run so your work is attributed to it in the activity log. Call once at the start; pass the returned session_id to later calls.

Parameter	Type	Required	Description
`label`	string	No	Short description of the task
`model`	string	No
`client`	string	No	e.g. Claude Code, Cursor
`repo`	string	No
`branch`	string	No

`submit_for_review`

Submit for review. Save a version and ask the humans to review it. Pass reviewers (emails or names of people with the reviewer role or above) to ask specific people; otherwise everyone who can review is asked.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`summary`	string	No
`reviewers`	list of string	No	Emails or names of the people who should review

`update_step`

Update step. Set a step's status (pending, doing, done, blocked) with an optional note. Requires an approved plan.

Parameter	Type	Required	Description
`session_id`	string	No	The session_id from start_session. Omit to use this connection's current session.
`document_id`	string	Yes
`step`	string	Yes
`status`	`pending` · `doing` · `done` · `blocked`	Yes
`note`	string	No

`wait_for_review`

Wait for review. Block until the document is reviewed, commented on or edited, or until timeout_seconds pass. Returns get_feedback's result and whether anything changed. Prefer stopping and resuming later for long reviews. Read only.

Parameter	Type	Required	Description
`document_id`	string	Yes
`timeout_seconds`	integer	Yes

`whoami`

Who am I. Show this connection, its access level, and the workspaces it can reach (with the organization_id create_project needs), even ones with no projects yet. Read only.

No parameters.

Prompts

The server also offers two prompts, "Plan a task in planpage" and "Address review feedback", described in The planpage skill.

#REST API

#MCP tools

#ask_human

#claim_step

#comment

#complete_plan

#create_project

#diff_versions

#edit_blocks

#get_feedback

#get_skill

#link_ref

#link_repository

#list_briefs

#list_documents

#list_projects

#list_repositories

#list_steps

#pick_up_brief

#publish

#read_document

#read_document_blocks

#release_step

#reply_comment

#resolve_comment

#resolve_project

#search

#start_session

#submit_for_review

#update_step

#wait_for_review

#whoami

#Prompts

REST API

MCP tools

`ask_human`

`claim_step`

`comment`

`complete_plan`

`create_project`

`diff_versions`

`edit_blocks`

`get_feedback`

`get_skill`

`link_ref`

`link_repository`

`list_briefs`

`list_documents`

`list_projects`

`list_repositories`

`list_steps`

`pick_up_brief`

`publish`

`read_document`

`read_document_blocks`

`release_step`

`reply_comment`

`resolve_comment`

`resolve_project`

`search`

`start_session`

`submit_for_review`

`update_step`

`wait_for_review`

`whoami`

Prompts