Scaup Custom API

Scaup improves your website every day: page titles, descriptions, text, links and new articles. If your site runs on a platform we do not connect to yet, build the endpoints on this page and Scaup will work through them.

General rules

• Use HTTPS and JSON. Use one base URL, for example https://yoursite.com/api/scaup/v1.
• Send one API key in the header Authorization: Bearer <key>. Give the key access to content only, not to users or orders.
• Give every page and post an id that never changes, even when its URL changes.
• Return the saved record after every write, so Scaup can check the result.
• On error, return a normal HTTP code and a short body, for example { "error": "not_found" }.

Required endpoints

These endpoints cover page titles, descriptions, text edits and new articles.

Lists every published page and post. Returns id, type (page or post), url, title, status and updated_at.

Returns one page with the fields Scaup can edit.

{
  "id": "abc123",
  "type": "post",
  "url": "https://yoursite.com/blog/my-post",
  "status": "published",
  "version": 17,
  "seo_title": "...",
  "meta_description": "...",
  "body_html": "<p>...</p>",
  "updated_at": "2026-11-04T10:00:00Z"
}

Changes only the fields that Scaup sends, then publishes the page.

{ "version": 17, "seo_title": "New title" }

1. version is required. It is the version Scaup read in the GET call.
2. If the page changed since then, return 409 Conflict and save nothing. This protects edits that your team made.
3. Do not change any field that Scaup did not send.

Creates a new article and publishes it. Also accept "status": "draft". Return the new id and url.

{
  "title": "...",
  "slug": "my-new-article",
  "body_html": "<h2>...</h2><p>...</p>",
  "seo_title": "...",
  "meta_description": "...",
  "featured_image_url": "https://...",
  "status": "published"
}

Unpublishes a page. Scaup uses this to undo an article it created. Scaup does not need a delete endpoint.

Recommended endpoints

Add these fields to GET and PATCH /pages/{id}:

• og_title and og_description. Printed in the page head as og:title and og:description. When empty, use the SEO title and meta description.
• schema_jsonld. A raw JSON-LD string, printed in the page head inside <script type="application/ld+json">.
• noindex (true or false). Optional.

Add these site files:

• GET and PUT /files/robots.txt, and the same for /files/llms.txt. Body: { "version": 3, "content": "..." }. Serve the stored text at /robots.txt and /llms.txt as text/plain.
• Generate sitemap.xml from your published pages, so new articles appear on their own. No endpoint is needed.

Optional: POST /media (multipart upload, returns a public URL). Without it, Scaup links only to images that already exist on your site.

Rules for your site

• Store body_html exactly as Scaup sends it. Scaup sends only p, a, strong, em, ul, ol, li, br, h2, h3, h4, img.
• Show each change on the live page within a few minutes. If you use a cache or CDN, clear the changed page after each write.
• Give us a staging copy or a test page first.

Security rules

Treat every request as untrusted, even when it comes from Scaup. If the key ever leaks, these checks keep your site safe. How Scaup handles your key is on the Security page.

Allow only the HTML that Scaup sends

Check body_html on your server before you save it. Reject the request if it has anything outside this list. Do not try to clean it; return 400 instead.

• Tags: p, a, strong, em, ul, ol, li, br, h2, h3, h4, img.
• Attributes: href on a, and src and alt on img. No other attributes.
• href: only https:// or a path that starts with /. Block javascript:, data: and //.
• src: only https://.
• Always block script, style, iframe, object, embed, form, svg, every on* attribute (for example onclick) and every style attribute.

Check the other fields

• seo_title, meta_description, og_title, og_description: plain text. HTML-encode them when you print them in the page head.
• schema_jsonld: must be valid JSON. Reject it if it contains </script.
• robots.txt and llms.txt: plain text only. Serve them as text/plain.

Protect the key

• Accept the key only over HTTPS.
• Limit the key to the endpoints on this page. It must not reach users, orders, settings or other files.
• Let us rotate the key. Keep the old one valid for one day after a new one is issued.
• Add a rate limit, for example 60 requests per minute.
• Log each write with the page id and the time, so you can see what changed.

Test your API

Your API is ready only when an acceptance check passes. The check is a small script that tests the API from the outside, over HTTP. Section 6 of the agent prompt lists every check it must run.

1. Build the check script, or let your coding agent build it from the prompt.
2. On staging, create one published test page. The script changes it and then puts it back.
3. Run the script on staging. Fix every line marked FAIL. SKIP is fine for recommended parts you did not build.
4. When the last line says RESULT: READY, send us the full output and tell us how to run the script.

We run our own checks on staging before we connect your site.

Checklist

1. Build the required endpoints.
2. Build the recommended endpoints if you can.
3. Add the security rules.
4. Run the acceptance check until it says RESULT: READY.
5. Send Scaup the base URL, the API key, the check output and a list of any field names that differ from this page.

Agent prompt

If you use an AI coding agent (Claude Code, Cursor, Copilot), paste this prompt into it. It asks the agent to build everything on this page, with the security checks and the acceptance check.

Loading the prompt. If it does not show, use "Open as Markdown".