Pagepin Agent API — deploy pages & read review comments as JSON

A small HTTP API a coding agent can drive with plain curl — no CLI, no SDK. Deploy a page, read pin-point review comments as structured JSON, and hand out account-free share links. Everything authenticates with one Personal Access Token.

One base URL, one token, plain HTTP.

Every request goes to $PAGEPIN_BASE — the scheme and host of the pagepin instance, no trailing slash — and carries Authorization: Bearer $PP_TOKEN, a Personal Access Token. The token is SHA-256 hashed at rest and never needs to be pasted into chat: the skill obtains it through a browser device-login the first time. There is no bespoke client to install; the same calls work against the hosted instance or your own self-hosted one.

Authoritative quotas and your handle always come from GET /api/me. Deployed sites are private by default — reachable only after login — so make a site public or mint a share link before sending it to someone outside the instance.

bash · verify the token

curl -fsS "$PAGEPIN_BASE/api/me" -H "Authorization: Bearer $PP_TOKEN"
# → { "handle": "you", "content_base": "https://…", "limits": { … } }

Deploy · read comments · share

Deploy a page POST /api/sites/<slug>/deploy

A multipart/form-data upload. files (content) and paths (in-site relative path) come in pairs and may repeat for a multi-file site. Re-deploying the same slug appends a new version and flips the current pointer atomically. A single HTML file is safest as paths=index.html.

bash

curl -fsS -X POST "$PAGEPIN_BASE/api/sites/q1-report/deploy" \
  -H "Authorization: Bearer $PP_TOKEN" \
  -F "paths=index.html" \
  -F "[email protected];type=text/html" \
  -F "title=Q1 report"
# → { "url": "…/q1-report/", "visibility": "private", "version_count": 1 }

For sites over ~90MB there's a 3-step batched flow (deploys → …/files → …/commit); see the full reference. Visibility is controlled separately with PATCH /api/sites/<slug> — {"visibility":"public","public_hours":72} opens a bounded, auto-reverting public window.

Read review comments as JSON GET /api/sites/<slug>/comments

Returns open threads (add ?all=true to include resolved ones). Each thread carries a selector ("@page" means whole-page feedback), a kind (copy / style / question / bug, may be null), resolved and stale flags, the threaded comments with authors, and a deep-link url. This is the channel the agent reads, fixes against, and redeploys.

bash + response

curl -fsS "$PAGEPIN_BASE/api/sites/q1-report/comments" \
  -H "Authorization: Bearer $PP_TOKEN"

[
  {
    "id": "th_9f2a",
    "selector": "h1.title",
    "kind": "copy",
    "resolved": false,
    "stale": false,
    "url": "https://…/#pp-th_9f2a"
  }
]

Close the loop with POST /api/sites/<slug>/comments/<thread_id>/replies to reply and PATCH …/comments/<thread_id> with {"resolved":true}. A question the agent can't judge should be relayed to you, not resolved on your behalf.

Mint an account-free share link POST /api/sites/<slug>/share-link

Mints a short https://<content-host>/s/<code> URL. Anyone opening it can view the private site and pin comments as a guest — no account. Both fields are optional and links never expire by default; pass hours for a self-expiring link (server-capped, default 720h) or label to tell links apart. Revoke one link or all of them to cut guests off.

bash

curl -fsS -X POST "$PAGEPIN_BASE/api/sites/q1-report/share-link" \
  -H "Authorization: Bearer $PP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"for the design review"}'
# → { "url": "https://<host>/s/AbC123", "code": "AbC123", "expires_at": null }

The full surface

All endpoints authenticate the same way. See the API reference for request bodies, limits, and error codes.

Method & path	Purpose
`GET /api/me`	Verify the token; returns handle, content base, limits, quota
`GET /api/me/usage`	Current storage usage against the instance limits
`GET /api/sites`	List your sites
`POST /api/sites/<slug>/deploy`	Deploy / update — one atomic version (multipart)
`PATCH /api/sites/<slug>`	Set visibility & `public_hours`, title, or SPA fallback
`GET /api/sites/<slug>/versions`	Version list, including the current one
`POST /api/sites/<slug>/rollback`	Point the current version backward by `version_id`
`DELETE /api/sites/<slug>`	Delete the site
`GET /api/sites/<slug>/comments`	Review comments (unresolved by default; `?all=true` for all)
`POST /api/sites/<slug>/comments/<id>/replies`	Reply to a thread
`PATCH /api/sites/<slug>/comments/<id>`	Resolve or reopen a thread
`POST /api/sites/<slug>/share-link`	Mint a guest share link (never expires by default)
`GET /api/sites/<slug>/share-links`	List active share links
`DELETE /api/sites/<slug>/share-links/<code>`	Revoke one link (and kick its guest sessions)
`DELETE /api/sites/<slug>/share-link`	Revoke all outstanding share links for the site

Defaults you should know: single file ≤25MB, single site ≤200MB, ≤2000 files, plus a per-user storage quota — but always defer to the limits returned by GET /api/me. Error bodies are { "detail": "…", "code": "…" }; branch on the stable code, not the localized message.

Pagepin Agent API — deploy pages & read review comments as JSON

One base URL, one token, plain HTTP.

Deploy · read comments · share

The full surface

The living docs

Give your agent a place to deploy.