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.

1

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.

2

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.

3

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.

4

Read it from your site

Reads need only the App ID. Replace YOUR_APP_ID with yours.

JavaScript
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));
5

Let visitors write

Writes come from signed-in visitors (AppUsers), who then own what they create.

JavaScript
// 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.

POST /auth/register
POST /auth/verify-email
POST /auth/resend-verification
POST /auth/login
POST /auth/refresh
POST /auth/logout
POST /auth/logout-all
POST /auth/forgot-password
POST /auth/reset-password
GET /auth/me
PUT /auth/me
POST /auth/change-password
DELETE /auth/me
GET /collections/:collection/items
POST /collections/:collection/items
GET /collections/:collection/items/:id
PUT /collections/:collection/items/:id
DELETE /collections/:collection/items/:id
GET /collections/:collection/items/:id/attachments
POST /collections/:collection/items/:id/attachments
GET /collections/:collection/items/:id/attachments/:attachment_id
DELETE /collections/:collection/items/:id/attachments/:attachment_id

Platform API

What the dashboard uses, with your dashboard sign-in. Listed so you know what exists; build sites against the Client API.

GET /api/auth/me
GET /api/apps
POST /api/apps
GET /api/apps/:app_slug
PUT /api/apps/:app_slug
DELETE /api/apps/:app_slug
POST /api/apps/:app_slug/api-key/regenerate
GET /api/apps/:app_slug/collections
POST /api/apps/:app_slug/collections
GET /api/apps/:app_slug/collections/:slug
PUT /api/apps/:app_slug/collections/:slug
DELETE /api/apps/:app_slug/collections/:slug
GET /api/apps/:app_slug/collections/:collection/items
POST /api/apps/:app_slug/collections/:collection/items
GET /api/apps/:app_slug/collections/:collection/items/:id
PUT /api/apps/:app_slug/collections/:collection/items/:id
GET /api/apps/:app_slug/appusers
GET /api/apps/:app_slug/collaborators
POST /api/apps/:app_slug/collaborators
PUT /api/apps/:app_slug/collaborators/:id/role
DELETE /api/apps/:app_slug/collaborators/:id
POST /api/apps/:app_slug/collaborators/accept
GET /api/apps/:app_slug/webhooks
POST /api/apps/:app_slug/webhooks
GET /api/apps/:app_slug/webhooks/:id
PUT /api/apps/:app_slug/webhooks/:id
DELETE /api/apps/:app_slug/webhooks/:id
GET /api/apps/:app_slug/webhooks/:id/logs
POST /api/apps/:app_slug/webhooks/:id/logs/:log_id/retrigger
GET /api/webhook-events
GET /api/apps/:app_slug/features
PUT /api/apps/:app_slug/features/:key
DELETE /api/apps/:app_slug/features/:key
GET /api/account/tokens
POST /api/account/tokens
DELETE /api/account/tokens/:id

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.

Connect an assistant →