# HTTP API

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

Documentation index: https://appnotes.dev/docs/llms.txt

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](/docs/agents). MCP credentials are for `/mcp`, not the HTTP API.

```http
Authorization: Bearer YOUR_APPNOTES_API_KEY
```

## Register a Site

```sh
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:

```http
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.