Documentation
Get up and running in minutes.
Everything you need to add a real backend to your static site — no server required.
Quickstart
Read and write Items from a plain HTML page in a few minutes.
Create an App
Sign in at app.extatic.io, click New App, and choose a name and slug. Copy the App ID (it starts with app_). The secret API key shown with it is for servers only; you don't need it here.
Allow your site's origin
In the App's Settings, add each origin your site is served from under Allowed Origins, for example https://example.com and http://localhost:8080. Use the exact scheme, host, and port, with no path or trailing slash.
Create a Collection and an Item
Click New Collection and give it the slug messages. Leave the schema empty for now. Then add an Item with {"text": "Hello"} as its data.
Read it from your site
Reads need only the App ID. Replace YOUR_APP_ID with yours.
const API = 'https://app.extatic.io/api/YOUR_APP_ID';
const res = await fetch(`${API}/collections/messages/items?page=1&page_size=20`);
if (!res.ok) throw new Error(`Extatic ${res.status}`);
const { items, total } = await res.json();
items.forEach(i => console.log(i.data.text));
Let visitors write
Writes come from signed-in visitors (AppUsers), who then own what they create.
// 1. Sign the visitor in (register first with POST /auth/register)
const session = await fetch(`${API}/auth/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password }),
}).then(r => r.json());
// 2. Create an Item they own
const res = await fetch(`${API}/collections/messages/items`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${session.access_token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ data: { text: 'Hello, Extatic!' } }),
});
const item = await res.json();
console.log(item.id); // → UUID
Using an AI assistant? The AI quickstart connects it to Extatic's MCP server so it can set this up for you.
Authentication
How a request authenticates depends on who is calling.
Your site's visitors (Client API)
Every Client API URL starts with the App ID, which is public and safe in browser code. Reads need nothing else.
Writes need a signed-in AppUser's access token from POST /auth/login. Refresh it with
POST /auth/refresh before expires_in runs out.
POST https://app.extatic.io/api/app_3f9a1c7d2b8e4f60/collections/messages/items
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Your team (dashboard)
Developers sign in to the dashboard with GitHub. The dashboard calls the Platform API under
/api/apps/… with that sign-in; it doesn't accept API keys or tokens.
Your AI assistant (MCP)
The MCP server at https://app.extatic.io/mcp accepts only a personal access token
(Authorization: Bearer ext_pat_…), created under Access tokens
in the dashboard. See the AI quickstart.
Your servers
Some feature endpoints, such as search indexing, take the App's secret API key as
X-Extatic-Secret-Key: exk_…. Never put it in browser code. The App owner can regenerate it in Settings.
Errors
Errors are JSON Problem Details. Validation failures add an errors array with a JSON Pointer to each bad field.
{
"title": "Validation Failed",
"status": 422,
"detail": "Item data does not match collection schema",
"instance": "/api/app_3f9a1c7d2b8e4f60/collections/reviews/items",
"errors": [
{ "pointer": "/rating", "message": "Value should be at most 5" }
]
}
| Status | Meaning |
|---|---|
| 400 | Bad request: malformed JSON or invalid paging |
| 401 | Missing, invalid, or expired token: refresh it or sign in again |
| 403 | Not allowed. feature_not_enabled: the App can't use that feature. feature_unavailable: it's switched off for everyone for now |
| 404 | Unknown App ID, Collection, or Item |
| 409 | Conflict, such as a slug that is already taken or an Item that changed since you loaded it |
| 413 | File exceeds the App's size limit |
| 422 | Validation failed; see errors |
| 429 | Rate limited; wait for Retry-After seconds |
| 500 | Something went wrong on our side |
A 403 for a feature also carries code and feature fields, such as "feature": "forms".
Client API
For your site's browser code. Paths are relative to https://app.extatic.io/api/<app_id>.
Feature modules add their own routes; see the
feature guides.
Platform API
What the dashboard uses, with your dashboard sign-in. Listed so you know what exists; build sites against the Client API.
MCP server
One endpoint, https://app.extatic.io/mcp (Streamable HTTP), for AI assistants. It authenticates with a
personal access token and has tools to set up Apps, Collections, and Items. It has no delete tools and never returns the secret API key.