HTTP API | Plannotator AppNotes

Use the AppNotes API for Sites, notes, replies, guest access, and organization agent credentials.

The AppNotes service exposes its OpenAPI 3.1 contract at /v1/openapi.yaml. Generate clients from the document served by the environment you use so authentication, routes, and schemas stay aligned with that deployment.

Authentication

Human web operations use an AppNotes session cookie and an X-AppNotes-CSRF header for mutations. HTTP automation uses an organization API key as a bearer credential. Interactive coding agents can use MCP with browser sign-in. MCP credentials are for /mcp, not the HTTP API.

Authorization: Bearer YOUR_APPNOTES_API_KEY

Register a Site

curl --request POST \
  "$APPNOTES_ORIGIN/v1/orgs/$APPNOTES_ORG_ID/appnotes/sites" \
  --header "Authorization: Bearer $APPNOTES_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $APPNOTES_OPERATION_ID" \
  --data '{
    "name": "Checkout",
    "origin": "https://checkout.example.com",
    "primary_url": "https://checkout.example.com/cart"
  }'

The response includes the Site ID needed by the connected SDK.

Generate one operation ID for the intended creation. Reuse it and the exact request body if the response is lost. Do not generate a new ID for a retry. Check the served contract for creation retry headers and Note version preconditions on your deployment.

Core resources

Resource	Representative operations
Sites	Register, list, inspect, update, delete, mint a launch session
Notes	List, create, inspect, update state and content, delete
Replies	List, create, update, delete
Note images	Attach, read, or remove the note’s private screenshot
Guest links	Create, list, and revoke Site-scoped guest access
API keys	Create, list metadata, and revoke organization agent credentials

List endpoints use cursor pagination. Notes can be filtered by Site, page URL, and state. Error responses use a stable envelope with code, message, and optional details fields.

Note images

Each note can have zero or one image. The API retains the name screenshot for this resource:

GET /v1/appnotes/sites/{siteId}/notes/{noteId}/screenshot

The response contains image bytes and requires authorized access to the note. It uses Cache-Control: private, no-store, not a public storage URL. POST attaches an image; DELETE removes it without deleting the note.

Screenshot metadata can include an optional capture object. It describes the method, renderer, scope, timestamps, crop, target bounds, and warnings. SDK-generated images use method: "dom-reconstruction". The scope is selection or viewport, not a full scrollable page.

Older images can omit capture. Readers must accept those images without inventing capture details. Notes can also have no image. Use the served OpenAPI contract for field schemas, upload limits, and retry requirements.

Site sessions

POST /v1/appnotes/sites/{siteId}/token mints a short-lived exact-origin launch session and returns a launch URL. Treat the token as a browser launch credential, not an API key. Do not log it or place it in a query string.