Publish with a POST.
The whole page lifecycle over plain HTTP: publish, list, read stats, update, delete, and read form submissions. One token, curl-friendly, no SDK.
01 What this is
Everything you can do from a chat with the MCP connector, you can also do from a script. Same account, same plan limits, same URLs, just plain JSON over HTTPS.
Reach for the API when you want to publish from a backend, a CI job, a cron task, or a one-line curl. Reach for MCP instead when you want an AI assistant to build and publish pages for you in chat, or when you need the drag-and-drop photo upload slots (those need a browser).
02 Authenticate
Every request carries a Personal Access Token in the Authorization header.
- Sign in, then create a token in Settings, Connect AI clients. It's shown once, so copy it.
- Send it as a bearer token on every call:
Authorization: Bearer yapp_pat_…
- Call
curl.exe, notcurl. In PowerShell,curlis an alias for a different tool that does not accept-Xor-H. - Set the token with
$env:YAPP_TOKEN="…"in PowerShell, orset YAPP_TOKEN=…in the classic Command Prompt, and read it back as$env:YAPP_TOKENor%YAPP_TOKEN%. - Put the JSON body in a file and send
-d "@body.json". Do not paste JSON straight into the command: Command Prompt keeps the single quotes around-d '{"…"}', and Windows PowerShell 5.1 drops the inner double quotes, so either way the body arrives as invalid JSON. A file avoids both.
body.json next to you:
03 Base URL
All endpoints live under one versioned base.
Published pages get their own subdomain, so a page's live URL is https://<id>.yapp.page/, not a path under the API.
04 Endpoints
Seven calls cover the full lifecycle, including image upload. Responses are JSON.
Publish a new page. Send exactly one content source: html (inline), htmlUrl (a public https URL we fetch byte-for-byte, best for large files), or fileBase64 + mime (host a PDF, image, or ZIP as-is). Optional: filename, name, slug, expires (days), password.
Big document or one you already host? Skip inline HTML and let yapp fetch it:
Upload an image (or any static file) straight from disk. One multipart file field, no URL and no base64 needed. The name defaults to the uploaded filename, or set name to control the path (e.g. images/hero.jpg). Uploading a name that already exists replaces it. Reference the file from your HTML by that name.
Typical flow: publish the HTML that references hero.jpg, then upload the file. It appears on the live page instantly.
List your active pages, newest first.
Traffic stats for one page. Human traffic only, bot hits are filtered out. Detailed breakdowns (referrers, countries, devices) require the Pro plan.
Change any subset in one call. Replace content with html or htmlUrl. Set name, expires (a number of days or "forever"), password (a string to set, or null to remove), and slug (the page moves to the new URL, the old one stops working).
Password protection and custom expiry are Pro features. A few common single-field edits:
Delete a page permanently. The URL stops working and form submissions are removed. This cannot be undone.
Read form submissions captured from a page, newest first. yapp auto-captures any <form> on a page. Add ?limit= (1 to 200, default 50). A page keeps a rolling 10 messages on Free and 500 on Pro (unlimited on Team): once full, the oldest is dropped as new ones arrive.
POST /pages/:id/assets (shown above, the simplest), point your HTML at a public https URL, or bundle a whole site as a ZIP via fileBase64. The drag-and-drop drop-slots (for uploading a file from inside a chat) are the MCP connector's browser flow; over HTTP you just POST the file.05 Errors & limits
Errors return a JSON body: { "error": "message", "code": "PLAN_LIMIT" }. The code field is present on some errors (like plan limits) and absent on others.
| Status | Means |
|---|---|
| 400 | Bad request, invalid slug, missing content, or a malformed body. |
| 401 | Missing, invalid, or revoked token. |
| 402 | Plan limit reached (for example, password or extra pages on the free plan). Carries code. |
| 403 | The token's account does not own this page. |
| 404 | No such page. |
| 409 | That slug is already taken. |
| 413 | Content too large (12 MB max per request). |
| 415 | The body was not sent as JSON, so it was ignored. Add -H "Content-Type: application/json". |
| 429 | Rate limited. The API allows 60 requests per minute per IP. |
BAD_FIELD_TYPE means html or htmlUrl was sent as something other than a single JSON string, for example null, a list of lines, or a nested object. NO_CHANGES means the request contained no field the API recognises, so nothing was updated. Both usually mean a script or AI client built the request body wrong. The fix is the same in either case: send the entire document as one string in the html field, exactly as in the update example above.Prefer publishing from a chat? See Use with AI for the MCP connector.