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

# Plannotator local API

> The session-scoped HTTP API exposed by Plannotator plan, document annotation, and code review servers.

Each Plannotator session runs a temporary HTTP server for its browser UI and local integrations. The API is session-scoped, unauthenticated, and not a versioned public web API.

Use the URL printed in the terminal, such as `http://localhost:49152`. You can also find a running session with:

```bash theme={null}
plannotator sessions
```

## Security boundary

Local mode binds to `127.0.0.1`. Remote mode binds to `0.0.0.0` so SSH and development-container port forwarding can reach it. The API has no authentication in either mode.

Do not expose a remote Plannotator port to the public internet or an untrusted network. Forward it to your own machine through SSH or a trusted development environment. Enabling `PLANNOTATOR_AGENT_TERMINAL_REMOTE` expands the remote session's ability to run commands and should be treated with additional care.

## Stable integration surface

External tools should normally use `/api/external-annotations`. It is available in plan, document annotation, and code review sessions and has a tested schema. See [External annotations](/open-source/reference/external-annotations).

The remaining routes support the bundled browser UI. They can change with a Plannotator release, and the available set depends on the session mode.

## Common route families

Availability varies by session mode.

| Route                                  | Purpose                                                    |
| -------------------------------------- | ---------------------------------------------------------- |
| `GET /api/plan`                        | Current plan or document payload and session metadata      |
| `GET /api/config`                      | Settings shared with the server                            |
| `POST /api/config`                     | Persist supported UI settings to `config.json`             |
| `GET /api/external-annotations`        | Current external annotation snapshot                       |
| `POST /api/external-annotations`       | Add one or more external annotations                       |
| `GET /api/external-annotations/stream` | Stream external annotation updates with server-sent events |
| `POST /api/feedback`                   | Submit annotations from a document or review session       |
| `POST /api/exit`                       | Close a session without submitting feedback                |

Unknown `/api/*` routes return a JSON `404` response rather than the browser application HTML.

## Plan review routes

Plan sessions expose routes for the current plan, previous versions, approval or denial, draft annotations, references, uploaded images, saved notes, and plan history. The decision routes are called by the UI and return their result to the agent process that started the session.

## Document annotation routes

Document sessions expose routes for source content, versions, source-file saving, drafts, references, uploads, feedback, and sharing. Raw local HTML also uses a restricted asset route to load supported files from the HTML file's directory. Assets outside that directory are refused.

## Code review routes

Code review sessions expose routes for:

* diffs, commits, file contents, and diff-scope switching
* staging and viewed-file state when supported by the repository provider
* GitHub pull request and GitLab merge request context
* pull request comments, artifacts, stacks, and revision selection
* semantic diff and code navigation
* Ask AI sessions and launched review jobs
* review skills and capabilities

The exact payloads depend on Git, GitButler, Jujutsu, Perforce, GitHub, or GitLab state. Treat them as same-version UI contracts, not as long-lived automation contracts.

## AI routes

Sessions with AI support can expose `GET /api/ai/capabilities`, session management, a streaming query route, abort, and permission-response routes. Code review sessions can also expose job, job-event, review-skill, and capability routes.

These routes run local agent tools and may ask for permission. Do not proxy them to another user or network.

## Session lifetime

The server normally exits when you approve, send feedback, or close the session. A random local port can be different on every run. Do not store a session URL as durable configuration; discover it from the launching process or the session list.

Last verified against Plannotator OSS v0.23.1 on July 18, 2026. Maintained by the Plannotator project.