Skip to content

REST API ​

Everything the admin does is also available as JSON below <APP_URL>/api: sites, projects, files and visits. Use it from scripts, CI pipelines or anything that isn't an MCP client.

Authentication ​

The API uses the same tokens as MCP. Create one in the admin under API & MCP and send it as a bearer token:

bash
curl -H "Authorization: Bearer <token>" https://preview.example.com/api/sites

A token has the same rights as the admin login. Without a valid token every request gets 401.

Endpoints ​

MethodPathWhat it does
GET/api/sitesList sites
POST/api/sitesCreate a site: name, optional password, project_id
GET/api/sites/{id}One site
PATCH/api/sites/{id}Change name, password, clear_password: true, project_id (null takes it out of its project)
DELETE/api/sites/{id}Delete the site with all files
GET/api/sites/{id}/filesRelative paths of all files
POST/api/sites/{id}/filesUpload one file or zip (multipart file, optional path, replace)
DELETE/api/sites/{id}/files/{path}Delete one file
DELETE/api/sites/{id}/filesDelete all files, the site stays
GET/api/projectsList projects
POST/api/projectsCreate a project: name, optional password
GET/api/projects/{id}One project with its sites
PATCH/api/projects/{id}Change name, password, clear_password: true
DELETE/api/projects/{id}Delete the project, its sites stay
GET/api/visitsPage views and password attempts, see Visits

Request bodies are JSON (Content-Type: application/json), except file uploads. Passwords are never returned, only has_password.

A site looks like this:

json
{
  "data": {
    "id": 3,
    "name": "Relaunch v2",
    "url": "https://preview.example.com/s/k3j9x0aq1b/",
    "has_password": true,
    "project_id": 1,
    "file_count": 14,
    "has_html": true,
    "updated_at": "2026-10-28T13:12:00+00:00",
    "view_count": 4,
    "last_viewed_at": "2026-10-28T14:32:10+00:00"
  }
}

Uploading ​

One file per request, up to 100 MB. A zip is unpacked, a single wrapping folder is dropped. path defaults to the file name. With replace=1 the upload replaces the whole site in one step: the live site is never empty in between.

bash
curl -H "Authorization: Bearer <token>" \
  -F file=@dist.zip -F replace=1 \
  https://preview.example.com/api/sites/3/files

Check the draft against What works first.

Filtering, sorting, pages ​

Lists take query parameters:

ParameterExampleWorks on
filter[name]filter[name]=relaunch (part of the name)sites, projects
filter[project_id]filter[project_id]=1sites, visits
filter[site_id], filter[kind], filter[visitor]filter[kind]=unlock_failedvisits
filter[since], filter[until]filter[since]=2026-10-01visits
sortsort=name, sort=-updated_at (- = descending)all
includeinclude=sitesprojects
page, per_pageper_page=100 (default 30, max 100)all

Sites sort by name, created_at, updated_at, view_count or last_viewed_at; the default is -updated_at. Lists return data, links and meta (with total, last_page).

Errors ​

Errors follow RFC 9457 (Content-Type: application/problem+json):

json
{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The request data is invalid.",
  "violations": [{ "path": "name", "message": "The name field is required." }]
}
StatusWhen
400Unknown filter, sort or include
401Missing or revoked token
404No such site, project or file
422Invalid data, violations says which field
429More than 120 requests per minute with one token. Retry-After says when to try again