Add external annotations to Plannotator

External annotations let a local tool add findings to an open Plannotator session. The user sees them immediately and they are included when Plannotator exports feedback.

Keep this unauthenticated endpoint on a local or forwarded trusted connection. Do not expose it to an untrusted network.

Copy the active session URL from the terminal or plannotator sessions. Then replace PORT in the examples below.

Add a plan or document comment

A sidebar comment needs source and text. Its default type is GLOBAL_COMMENT.

curl -X POST http://localhost:PORT/api/external-annotations \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "style-checker",
    "type": "GLOBAL_COMMENT",
    "text": "Define the rollback condition before implementation.",
    "author": "Docs check"
  }'

To pin a comment or deletion to existing text, use COMMENT or DELETION and include the exact phrase in originalText:

curl -X POST http://localhost:PORT/api/external-annotations \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "policy-checker",
    "type": "COMMENT",
    "originalText": "Deploy immediately after merge",
    "text": "Add the verification and rollback steps first."
  }'

Plan and document fields:

Field	Requirement
`source`	Required, non-empty string identifying the tool
`text`	Required, non-empty annotation text
`type`	Optional: `GLOBAL_COMMENT`, `COMMENT`, or `DELETION`; defaults to `GLOBAL_COMMENT`
`originalText`	Required and non-empty for `COMMENT` and `DELETION`
`author`	Optional display name

Plannotator creates the annotation ID and placement metadata. Do not send a blockId.

Add a code review finding

This example creates a line-level concern on the new side of a diff:

curl -X POST http://localhost:PORT/api/external-annotations \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "eslint",
    "scope": "line",
    "type": "concern",
    "filePath": "src/session.ts",
    "lineStart": 48,
    "lineEnd": 48,
    "side": "new",
    "text": "This timer is not cleared when the request is aborted.",
    "author": "eslint bridge"
  }'

For a suggestion, include replacement code:

{
  "source": "refactor-checker",
  "scope": "line",
  "type": "suggestion",
  "filePath": "src/math.ts",
  "lineStart": 12,
  "lineEnd": 12,
  "side": "new",
  "text": "Avoid mutating the input.",
  "originalCode": "items.sort()",
  "suggestedCode": "items.toSorted()"
}

Review fields:

Field	Requirement
`source`	Required, non-empty string identifying the tool
`scope`	`line`, `file`, or `general`; defaults to `line`
`filePath`	Required for `line` and `file`; omitted for `general`
`lineStart`, `lineEnd`	Both required numbers for `line`
`side`	`new` or `old`; defaults to `new`
`type`	`comment`, `suggestion`, or `concern`; defaults to `comment`
`text`, `suggestedCode`	At least one must be a string
`originalCode`, `author`	Optional strings

Add a batch

Wrap multiple valid objects in annotations. The request succeeds with 201 and returns the generated IDs.

curl -X POST http://localhost:PORT/api/external-annotations \
  -H 'Content-Type: application/json' \
  -d '{
    "annotations": [
      { "source": "audit", "scope": "file", "filePath": "src/a.ts", "text": "Add a test for the error path." },
      { "source": "audit", "scope": "general", "text": "The migration needs a rollback command." }
    ]
  }'

An empty batch or one invalid object returns 400 and adds nothing.

Read, update, and remove annotations

Request	Result
`GET /api/external-annotations`	`{ "annotations": [...], "version": N }`
`GET /api/external-annotations?since=N`	`304 Not Modified` when the version is unchanged
`GET /api/external-annotations/stream`	Server-sent event snapshot followed by add, update, remove, and clear events
`PATCH /api/external-annotations?id=UUID`	Merge JSON fields into one annotation; the ID cannot be changed
`DELETE /api/external-annotations?id=UUID`	Remove one annotation
`DELETE /api/external-annotations?source=NAME`	Remove every annotation from one source
`DELETE /api/external-annotations`	Clear all external annotations

The event stream sends a heartbeat every 30 seconds. Use the snapshot endpoint with since as a polling fallback. External annotations live only for the current session. Persist findings in your own tool if they must survive after the Plannotator server closes. Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.

Start

Plans and documents

Code review

Reference

Agents

Editors and notes

Troubleshooting

Related project

Add external annotations to Plannotator

Add a plan or document comment

Add a code review finding

Add a batch

Read, update, and remove annotations

​Add a plan or document comment

​Add a code review finding

​Add a batch

​Read, update, and remove annotations

Add a plan or document comment

Add a code review finding

Add a batch

Read, update, and remove annotations