API Reference

Creates a new user account with the free tier. Sends a verification email with a 24-hour token. The account cannot log in until email is verified.

Authenticates the user and sets an HttpOnly session cookie. Sessions expire after 90 days (configurable). Email must be verified.

Invalidates the current session (deletes the DB row) and clears the session cookie. Redirects to / with a 302. Safe to call even when unauthenticated.

Returns the authenticated user's profile. Works with both session cookie and Bearer token.

Verifies the user's email using the token from the verification email. Token is valid for 24 hours. On success, redirects to /login.

Sends a password reset link to the given email if an account exists. Always returns 200 to prevent email enumeration. A random delay is added when the email is not found. Max 3 active reset tokens per user; oldest are pruned if exceeded. Reset links expire after 15 minutes (configurable).

Resets the user's password using the token from the reset email. On success, the token is consumed, all active sessions are deleted, and the session cookie is cleared.

Returns all non-expired sessions for the authenticated user. The current session is identified with isCurrent: true. Token hashes are never returned.

Revokes a session by ID. If the revoked session is the current one, the session cookie is also cleared. Only the owner can revoke their own sessions.

Revokes all sessions except the current one ("log out everywhere else"). The current session remains active.

Revokes ALL sessions for the user, including the current one. The session cookie is cleared. The user must log in again.

Creates a new API token for the authenticated user. Requires session-cookie authentication — an existing API token cannot create another one (prevents token escalation). The raw token is returned once; it cannot be retrieved again.

Returns all API tokens for the user — both active and revoked. Token hashes are never included. Use revoked_at to distinguish active from revoked tokens. Ordered by created_at DESC.

Soft-revokes the token by setting revoked_at. The token immediately stops working for authentication. The row is retained for audit purposes and is physically purged after 365 days. Only the token owner can revoke it.

Creates a new site from an uploaded file. Accepts multipart/form-data. The file must be either index.html (single file) or a .zip archive containing index.html at its root. ZIP uploads undergo bomb-protection checks (compression ratio, file count, total size).

Returns a paginated list of sites owned by the authenticated user.

Returns a single site by ID. Returns 404 if not found, 410 if expired. Only the owner can retrieve it.

Updates one or more metadata fields. Changing or removing the site password immediately revokes all active visitor access sessions. Sending only the fields you want to change — absent fields are not touched.

Country restrictions apply to every hosted page and asset, linked form embeds and submissions, and visitor password authentication. Unknown locations are denied while a rule is enabled. The signed-in site owner can preview from any country; passwords, share tokens, and temporary password overrides do not bypass country rules. Restricted responses use Cache-Control: private, no-store. Location is based on IP address, so VPNs and proxies can change the detected country. The returned site object includes countryRestriction.

Soft-deletes the site by setting status: deleted. This is one-way for users: no restore endpoint exists. Physical file deletion happens after the configured retention period.

Replaces the site's content with a new upload. The old active folder is asynchronously deleted after the transaction commits.

Recursively returns files and directories from the active site folder. Optional query parameter path selects a subtree. The response includes byte/file totals, configured limits, MIME types, timestamps, and contentRevision.

Accepts multipart files, optional JSON-array paths, optional destination, and optional boolean overwrite. Matching paths preserve a dragged folder hierarchy. The mutation publishes directly to the active folder and advances its content revision.

JSON body: { "path": "assets/images" }. The immediate parent must already exist.

JSON body: { "sourcePath": "assets/old.png", "destinationPath": "images/new.png" }. The destination parent must exist and the destination must not.

JSON body: { "paths": ["unused.css", "images/old"] }. Accepts up to 100 paths. Root index.html cannot be deleted, moved, or renamed.

Returns the site's current active folder as a ZIP archive. Response has Content-Type: application/zip and Content-Disposition: attachment; filename="subdomain.zip".

Replaces all tags on the site. This is a full replacement (not an append). Max 5 tags, each max 30 characters. Duplicates are deduplicated. Empty strings are ignored.

Changes the site's subdomain. The new subdomain must be unique. Old subdomain ceases to work immediately. Valid format: lowercase letters, numbers, and hyphens; max 63 chars; not reserved.

Enables or disables maintenance mode. When enabled, visitors see a maintenance page unless they have a site token with canBypassMaintenance: true or are the site owner.

Creates a new site access token. Returns the raw token and a ready-to-share URL (appends ?token=… to the site URL). The raw token is returned only at creation time.

Returns all tokens for the site. Raw token values are never returned — only metadata.

Updates a non-revoked token's label or maintenance-bypass flag. At least one field must be provided.

Marks the token as revoked. The token cache is invalidated immediately — the token stops working within milliseconds.

Revokes all non-expired, non-revoked tokens for the site. The full token cache for the site is invalidated immediately.

Returns visitor sessions for the site. These are created when a visitor successfully enters the site password. Note: revoked is not a valid status filter here (sessions are hard-deleted on revoke).

Hard-deletes a visitor session. The cache is invalidated immediately — the visitor is kicked out within milliseconds.

Hard-deletes all non-expired visitor sessions. All visitors will need to re-enter the site password. Cache is invalidated immediately.

Returns comprehensive analytics for the site within a date range. All 15 analytics dimensions are returned in a single response. The from date is clamped to the user's analytics retention window (90 days by default for registered users). Soft-deleted analytics rows are excluded.

Creates a standalone builder form. Send the definition properties at the top level of the request. The response nests them under form.definition, with title on the form itself.

400 for an invalid definition; 429 when the active-form allowance is exhausted.

Lists your active builder and AI-generated forms, newest first. Each item includes the form properties shown in Create a form, plus responseCount, siteSubdomain, and siteTitle. AI-generated forms have definition: null; standalone forms have no linked site.

Returns your active-form count, account-wide submissions this calendar month (UTC), and effective limits. Submissions retained for deleted forms still count toward monthly usage. Paid-account numeric overrides may change the example limits below.

Returns an active form you own, including its definition. AI-generated forms have definition: null. Returns 404 for a missing, deleted, or other user's form. The response does not include a response count; use the list endpoint for counts.

Accepts the same top-level JSON body as Create a form. Send title and the full fields array; omitted optional properties reset to their defaults. Array order sets field order. To pause submissions, send settings.acceptingResponses: false with the full definition. Existing responses are retained.

Updates only the title of a builder or AI-generated form you own. title must be a string; it is trimmed and truncated to 255 characters. An empty string clears the title to null. Other properties are ignored.

Soft-deletes an active form you own. It stops accepting responses and no longer counts toward the active-form limit. Stored responses remain, including their contribution to monthly usage. Returns 404 for a missing, already deleted, or other user's form.

Returns responses newest first, with the form metadata. Returns 404 for a missing form and 403 if you do not own it.

Downloads all matching responses, newest first. Optional search uses the same filtering as List form responses; pagination parameters do not apply. Columns include Submitted At, Email, First Name, Last Name, Full Name, Phone, Input Text, sorted extra-field names, and IP Address. Spreadsheet formula prefixes are escaped. Returns 404 for a missing form or 403 for another user's form.

Returns the rendered builder form with its configured fields, styles, and settings. It can be embedded on any website, including sites hosted outside Pagey Site. Requires an active builder form and the owner's canUseForms feature. Missing, deleted, or AI-generated forms return 404.

Accepts application/json, application/x-www-form-urlencoded, or field-only multipart/form-data. File uploads are rejected. Cross-origin requests are supported without credentials; preflight OPTIONS requests return 204. Send Accept: application/json to receive JSON for both success and validation errors.

Send a flat object with at most 30 fields. Builder form values must be strings keyed by the configured field names; required fields, field lengths, and types are validated, and undeclared fields are not stored. Send numbers as strings, dates as YYYY-MM-DD, URLs with http: or https:, and a checked checkbox as "yes" (unchecked: empty or omitted). Select/radio values must match a configured option. Keep the honeypot _pagey_website empty or omit it.

For AI-generated forms, string, number, and boolean values are accepted. The names email, first_name, last_name, full_name, phone, and input_text map to dedicated response properties; other ordinary names become extraFields. Fields beginning with _ are not stored. Dedicated field limits are 320 characters for email, 255 for each name, 50 for phone, and 2,000 for input text; custom values are limited to 2,000 characters.

Without Accept: application/json, builder submissions return the rendered form with a success message (201), or inline validation errors. AI-generated forms redirect with 303 to an absolute HTTP(S) URL supplied in _redirect or _next, or return an HTML thank-you page (201).

Creates a site without a user account. Anonymous creation is limited to 10 new sites per UTC day per browser or network, with no total site cap and no custom subdomains. Registered accounts can create 25 new sites per UTC day. To update the site later, the site must be password-protected (password is used as the auth credential).

Returns basic public metadata for a site by subdomain. Does not include sensitive fields. Returns 404 for deleted/expired sites.

Replaces content for a password-protected anonymous site. The site's password is used as the authentication credential. Only works for sites that have a password set.

Verifies the site password and creates a visitor access session (24-hour cookie). Accepts both JSON and HTML form submissions (application/x-www-form-urlencoded). For form submissions, redirects to returnPath on success or back with an auth_error query param on failure. Visitor session limits are enforced against the site owner's tier.

Returns usage stats for the current calendar month. Use this to check remaining capacity before creating a session.

Creates a new AI Builder session. Enforces the monthly session limit (counting both active and deleted sessions created this month).

Returns the session object plus all messages in chronological order. Message contentType is one of text (plain chat), html (generated HTML), or question (LLM clarifying question JSON).

Soft-deletes the session (sets status: deleted). The session still counts toward the monthly limit since LLM costs have already been incurred.

Sends a message to the LLM and gets back generated HTML, a clarifying question, or a text response. Message history is automatically maintained in the session. If the last assistant message was a question, the user's reply does not count toward the per-session prompt limit.

Takes the session's lastGeneratedHtml and creates a new hosted site from it using the normal site creation pipeline. The site is linked back to the session via deployedSiteId. Requires lastGeneratedHtml to be non-null (i.e. at least one successful generate call).