Site API

Where to call

Call the site's own address: EzyStudio answers /api/* on every site host (https://<slug>.ezystudio.app or the site's custom domain). A site reads it from SITE_URL. The public site endpoints work out which site you mean from that address.

A deployed site's server can reach only the EzyStudio platform host and its own database. Every other outbound call is blocked, which is why emails go through EzyStudio.

Authentication: the Site Key

• Every app site (a site with a server and a database) has a Site Key. EzyStudio sets it on the deployed site as the secret SITE_KEY; the editor's preview gets its own key. You never create or copy it by hand.
• Send it as Authorization: Bearer stk_…. The format is stk_, a 16-character public id, _, then a 43-character secret (letters and digits).
• Server to server only. A browser must never hold the key, so never send it from page code: a page on the site's own address reaches /api without any CORS check. Read it only in server code (in the templates, src/platform/config.ts).
• On a site's own address, the key must be that site's key.
• Someone allowed to manage the site's secrets can rotate or revoke a key. A rotated key stops working on the next request; the live site gets the new one when it is published again.
• Static websites have no Site Key and no Site API.

{"errors": [{"message": "Too many requests", "retryAfter": 60, "code": "E_TOO_MANY_REQUESTS"}]}

Send an account email

Asks EzyStudio to send one of the site's account emails. You send no HTML, sender or full URL, and no subject except for a notification: EzyStudio renders each kind with the site's name and brand, and builds the link on the site's own address from the path you send, so a forged Host header can never point a reset link somewhere else.

Request body

POST https://luma-hair-x7k2p.ezystudio.app/api/site/v1/emails
Authorization: Bearer stk_…
Content-Type: application/json

{"kind": "password_reset", "to": "maya@lumahair.test",
 "path": "/account/reset?token=8f2c…", "expiresInMinutes": 30}

{"status": 202, "message": "Email accepted for delivery.", "data": {"accepted": true}}

The answer is the same whether the email went out or was dropped because that address got too many emails: nobody can use it to find out who has an account.

Limits

Check a sign-up address

Asks whether an address looks like a real inbox, before the site creates an account or changes a user's email. Send {"email": "…"}; the answer is only yes or no, never the reason. An address that isn't an email at all fails validation (422). The template calls it from src/platform/auth/email-check.ts.

{"status": 200, "data": {"accept": true}}

Other Site API calls

• POST /api/site/v1/jobs and /jobs/cancel: background jobs. See Background jobs.
• POST /api/site/v1/files/uploads and the other /files calls: uploads, signed links and deletes. See File storage.
• POST /api/site/v1/owner-sign-in: the site's owner opening the admin with View as admin spends its ticket here. You don't call it yourself.

Public site endpoints

No credential. Read only, cached, and limited to 300 requests a minute per caller.

The public brand of the site on this address. Both paths answer the same; the templates call /initial-data. Cached for 60 seconds. It never includes the account, the owner or any setting. On an address with no site: 404 E_SITE_NOT_FOUND.

{"status": 200, "data": {"id": 4, "name": "Luma Hair", "slug": "luma-hair-x7k2p", "kind": "app",
  "template": "astro-app", "url": "https://luma-hair-x7k2p.ezystudio.app",
  "logo": null, "favIcon": null, "brandColor": null}}

Rules for coding agents

Markdown, not JSON: the platform rules every AI agent follows when it works on an EzyStudio site (Claude Code, Codex, Gemini, Cursor). The core doc lists the topics; read the one that fits before that kind of work. Inside the EzyStudio editor the same docs are already on disk.

• Which template: ?template=astro-app or ?template=astro-static, else the template of the site on this address, else astro-app.
• .md on the topic is optional; core is the core doc.
• Cached 5 minutes with an ETag: send If-None-Match to get a 304. The X-Agent-Docs-Template header names the template.
• Unknown topic: 404 E_AGENT_DOC_NOT_FOUND. If the docs can't be rendered: 503 E_AGENT_DOCS_UNAVAILABLE.

Every endpoint with full request and response schemas is in the API reference.