{ "openapi": "3.1.0", "info": { "title": "EzyStudio public and Site API", "version": "0.0.1", "description": "Generated from the API’s routes and Vine validators by `api/tools/openapi/generate.ts`. Do not edit by hand: change api/tools/openapi/operations.ts and run `node --import @poppinss/ts-exec tools/openapi/generate.ts` in api/." }, "servers": [ { "url": "https://ezystudio.com", "description": "EzyStudio API" } ], "tags": [ { "name": "Site API", "description": "What a deployed site’s server calls as the site, with its Site Key (`Authorization: Bearer `). Server to server only: never from a browser." }, { "name": "Public site", "description": "No credential. The site is the one whose address (Host) the request arrives on. Read only." }, { "name": "App Store", "description": "The public App Store catalogue. No sign-in." }, { "name": "Plans", "description": "Public plan catalogue (the pricing page)." }, { "name": "Partners", "description": "Public partner directory and “Hire an expert” leads." }, { "name": "Platform", "description": "Other public reads: brand, email assets, app media files, the visitor’s default language." } ], "paths": { "/api/site/v1/email-check": { "post": { "tags": [ "Site API" ], "summary": "Check that an address is a real inbox", "description": "Before sign-up or an email change, the site asks whether an address can receive mail (no throwaway domain, a mail server exists). The answer is `{accept}`, never a validation error, so the site decides what to show.", "x-source": "site_api.controller.ts", "operationId": "postSiteEmailCheck", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "example": { "email": "maya@lumahair.test" } } } }, "responses": { "200": { "description": "Whether to accept the address.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "accept": { "type": "boolean" } } } } } ] }, "example": { "status": 200, "data": { "accept": true } } } } }, "401": { "description": "`E_NO_SITE_KEY`, `E_BAD_SITE_KEY`, `E_INVALID_SITE_KEY`, `E_SITE_KEY_REVOKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/email-check" } }, "/api/site/v1/emails": { "post": { "tags": [ "Site API" ], "summary": "Relay an account email", "description": "Ask EzyStudio to send one of the site’s account emails (sites cannot reach a mail provider). There is no HTML, subject or sender: the platform renders each kind with the site’s name and brand and builds the link on the site’s own address from `path`. `path` is required for `password_reset`, `verify_email` and `confirm_email_change`; `code` (6 digits) is required for `sign_in_code`; `subject` and `text` are required for `notification`, which may only go to one of the site’s owners (`SITE_OWNER_EMAILS`). The answer is the same whether the email went out or was dropped by the per-recipient limit.", "x-source": "site_api.controller.ts, site_email.service.ts", "operationId": "postSiteEmails", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "password_reset", "verify_email", "password_changed", "account_exists", "notification", "confirm_email_change", "email_changed", "sign_in_code" ], "description": "`notification` is plain text to one of the site’s owners only." }, "to": { "type": "string", "maxLength": 254, "format": "email", "description": "The recipient." }, "path": { "type": "string", "maxLength": 512, "pattern": "^\\/(?![/\\\\])[^\\s\\\\\\u0000-\\u001f\\u007f]*$", "description": "Site-relative link (`/account/reset?token=…`): one leading `/`, never `//` or `\\`. Required for `password_reset`, `verify_email` and `confirm_email_change`." }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 10080, "description": "Shown in the email (“this link expires in …”). Up to one week." }, "subject": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Required for `notification`." }, "text": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Plain text, escaped when rendered. Required for `notification`." }, "code": { "type": "string", "pattern": "^\\d{6}$", "description": "`sign_in_code` only: exactly 6 digits, shown in the email." } }, "required": [ "kind" ] }, "example": { "kind": "password_reset", "to": "maya@lumahair.test", "path": "/account/reset?token=8f2c…", "expiresInMinutes": 30 } } } }, "responses": { "202": { "description": "Accepted (queued, or dropped by the per-recipient limit: same answer).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "accepted": { "const": true } } } } } ] }, "example": { "status": 202, "message": "Email accepted for delivery.", "data": { "accepted": true } } } } }, "401": { "description": "`E_NO_SITE_KEY` (no header), `E_BAD_SITE_KEY` (not a Site Key), `E_INVALID_SITE_KEY` (unknown, wrong secret, deleted site, inactive account, or another site’s host), `E_SITE_KEY_REVOKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "errors": [ { "message": "Invalid Site Key.", "code": "E_INVALID_SITE_KEY" } ] } } } }, "409": { "description": "`E_SITE_HAS_NO_HOST`: the site has no address to build the link on.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed, or `E_SITE_EMAIL_RECIPIENT` (a `notification` to someone other than the site owner).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationError" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-rate-limit": "600 calls a minute per site and key kind; 120 emails an hour per site and key kind; 1,000 emails and 100 notifications in any 24 hours per site; 5 an hour per recipient per site and 15 an hour per recipient across sites.", "x-adonis-route": "POST /api/site/v1/emails" } }, "/api/site/v1/files": { "get": { "tags": [ "Site API" ], "summary": "List files", "description": "Ready files of this site, newest first, for the key’s environment (live key: live files; editor key: staging files). Page with `before` = the `next` of the previous page.", "x-source": "site_files.service.ts `list`", "operationId": "getSiteFiles", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "before", "in": "query", "required": false, "description": "The `next` value of the previous page.", "schema": { "type": "string", "maxLength": 40 } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 100. Default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "`{files, next}`; `next` is null on the last page.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "Site Key errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "GET /api/site/v1/files" } }, "/api/site/v1/files/{fileId}": { "get": { "tags": [ "Site API" ], "summary": "Get one file", "description": "The file’s details (never its bytes: ask for a link).", "x-source": "site_files.service.ts `show`", "operationId": "getSiteFilesFileId", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "description": "The file id (`file_…`).", "schema": { "type": "string", "pattern": "^file_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "`{file}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "Site Key errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`E_FILE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "GET /api/site/v1/files/:fileId" } }, "/api/site/v1/files/{fileId}/complete": { "post": { "tags": [ "Site API" ], "summary": "Complete a file upload", "description": "Step 3 of 3, after the PUT: confirms the file is `ready` (the PUT already stored and checked it) and returns it; only ready files are listed and linkable. Call it from the backend after the browser says the upload finished, so your own records only point at stored files. A file still `pending` is checked in storage: exactly the declared size, or it is deleted (`E_FILE_SIZE_MISMATCH`). Not uploaded yet: 409, the grant stays until it expires (1 hour).", "x-source": "site_files.service.ts `complete`", "operationId": "postSiteFilesFileIdComplete", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "description": "The file id (`file_…`).", "schema": { "type": "string", "pattern": "^file_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "The file, now `ready`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "Site Key errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`E_STORAGE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`E_FILE_NOT_FOUND`: no such file on this site (and key kind).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`E_FILE_NOT_UPLOADED`: nothing stored yet. PUT the file, then call again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "`E_UPLOAD_EXPIRED`: the grant expired (1 hour). Ask for a new upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`E_FILE_SIZE_MISMATCH`: the stored file was not the declared size and was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/files/:fileId/complete" } }, "/api/site/v1/files/{fileId}/delete": { "post": { "tags": [ "Site API" ], "summary": "Delete a file", "description": "Deletes the file and its stored bytes; it stops counting at once. Links already handed out stop working when they expire (at most the `expiresIn` they were made with).", "x-source": "site_files.service.ts `remove`", "operationId": "postSiteFilesFileIdDelete", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "description": "The file id (`file_…`).", "schema": { "type": "string", "pattern": "^file_[0-9a-z]{26}$" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "deleted": { "const": true } } } } } ] } } } }, "401": { "description": "Site Key errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`E_FILE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/files/:fileId/delete" } }, "/api/site/v1/files/{fileId}/url": { "post": { "tags": [ "Site API" ], "summary": "Get a signed link to a file", "description": "A link to a ready file that works until `expiresAt` (default 1 hour, 60 seconds to 7 days), then stops. Hand it to the browser to show or download the file. `download: true` makes the browser save it; images, PDF, audio, video and plain text are otherwise shown, everything else is always downloaded (SVG too). Ask for a new link each time a page needs one rather than storing links.", "x-source": "site_files.service.ts `signedUrl`", "operationId": "postSiteFilesFileIdUrl", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "description": "The file id (`file_…`).", "schema": { "type": "string", "pattern": "^file_[0-9a-z]{26}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresIn": { "type": "integer", "minimum": 1, "maximum": 604800, "description": "Seconds the link works: 60 to 604800 (7 days). Default 3600." }, "download": { "type": "boolean", "description": "true = the browser saves the file instead of showing it." } } }, "example": { "expiresIn": 600 } } } }, "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } ] }, "example": { "status": 200, "data": { "url": "https://files.example/s42/live/01jbz3k8….pdf?token=…&expires=1793102400", "expiresAt": "2026-10-27T10:10:00.000Z" } } } } }, "401": { "description": "Site Key errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`E_STORAGE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`E_FILE_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`E_FILE_NOT_READY`: call complete first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/files/:fileId/url" } }, "/api/site/v1/files/uploads": { "post": { "tags": [ "Site API" ], "summary": "Start a file upload", "description": "Step 1 of 3. The site’s backend asks for a short-lived upload URL for one file (step 1); the browser (or the backend) PUTs the bytes to it (step 2); the backend calls `complete` (step 3). `upload.url` is a path on the site’s OWN address (`/__platform/files/uploads/`): the browser sends it to the same origin as the page, so the site’s CSP and any bucket need no change; from server code prefix it with `SITE_URL`. The platform counts every byte and stores exactly the declared size; the PUT answers `200 {file}` with the file `ready`, `413 E_BODY_TOO_LARGE` (larger than declared: nothing stored, the URL still works), `422 E_FILE_SIZE_MISMATCH` (shorter: nothing stored, ask again), `409 E_UPLOAD_TOKEN` (already used), `410 E_UPLOAD_EXPIRED`. Checks, in order: Storage is on for this site (the owner turns it on in the dashboard), the account has storage (an agency account needs its agency’s bucket), the type is on the allow-list (images, PDF, text, CSV, JSON, ZIP, audio, video, Office documents; never HTML or JavaScript), the size is 1 byte to 100 MB, and there is room. Storage is sold only as add-on packs: without one the answer is 402 `E_STORAGE_NEEDS_PACK`; a file that would not fit in the packs’ total is refused (402 `E_STORAGE_LIMIT`) before anything is stored, on every plan. On an agency’s own bucket the agency decides what its clients get. The file starts `pending` and counts against the limit until it is completed or the grant expires (1 hour). Send `upload.headers` exactly as given with the PUT; the URL works for 15 minutes and once. `name` is only a display name (any path is dropped); the storage key is built by the platform. Files are private unless `visibility` is `public`. The editor key works too: its files are separate (staging).", "x-source": "site_files.service.ts `createUpload`", "operationId": "postSiteFilesUploads", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Display name, e.g. `cv.pdf`. Paths and control characters are removed; up to 200 characters are kept." }, "contentType": { "type": "string", "minLength": 3, "maxLength": 127, "description": "The file’s MIME type, e.g. `image/jpeg`. Must be on the allow-list." }, "size": { "type": "integer", "minimum": 0, "description": "Exact size in bytes. The stored file must match it exactly." }, "visibility": { "enum": [ "private", "public" ], "description": "`private` (default): only signed links. `public`: also a stable link on the site’s own address, `/__platform/files//`." } }, "required": [ "name", "contentType", "size" ] }, "example": { "name": "cv.pdf", "contentType": "application/pdf", "size": 482113 } } } }, "responses": { "201": { "description": "Granted: PUT the file’s bytes to `upload.url` (on the site’s own address) with `upload.headers`, then call complete.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] }, "example": { "status": 201, "message": "Upload the file with a PUT to the URL, then call complete.", "data": { "file": { "id": "file_01jbz3k8x2m4n6p8q0r2s4t6v8", "name": "cv.pdf", "contentType": "application/pdf", "size": 482113, "visibility": "private", "status": "pending", "environment": "production", "createdAt": "2026-10-27T10:00:00.000Z", "completedAt": null }, "upload": { "method": "PUT", "url": "/__platform/files/uploads/eyJtZXNzYWdlIjoi…", "headers": { "Content-Type": "application/octet-stream" }, "expiresAt": "2026-10-27T10:15:00.000Z" } } } } } }, "401": { "description": "`E_NO_SITE_KEY`, `E_BAD_SITE_KEY`, `E_INVALID_SITE_KEY`, `E_SITE_KEY_REVOKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`E_STORAGE_NEEDS_PACK`: no storage pack (the owner adds one in the dashboard). `E_STORAGE_LIMIT`: the file does not fit in the storage left (delete files or add a bigger pack). Also the account’s usage hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 402, "errors": [ { "message": "There isn’t room for this file: 4.9 GB of 5 GB used. Delete files or add storage in the dashboard.", "code": "E_STORAGE_LIMIT" } ] } } } }, "403": { "description": "`E_STORAGE_OFF` (turned off for this site) or `E_STORAGE_UNAVAILABLE` (no storage for this account).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`E_FILE_TYPE`, `E_FILE_EMPTY`, `E_FILE_TOO_LARGE` (over 100 MB), or validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-site rate limit, or too many failed keys from this IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": "300 upload grants a minute per site; 600 calls a minute per site and key kind.", "x-adonis-route": "POST /api/site/v1/files/uploads" } }, "/api/site/v1/files/usage": { "get": { "tags": [ "Site API" ], "summary": "Storage used and the limit", "description": "The account’s uploaded files against its storage packs (all its apps together). `limitBytes` 0 = no pack, null = no limit (possible on an agency’s bucket). `onExceed` is `block`: uploads stop at the limit. Show it before a large upload to tell the visitor early.", "x-source": "site_files.service.ts `usage`", "operationId": "getSiteFilesUsage", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "responses": { "200": { "description": "Usage.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] }, "example": { "status": 200, "data": { "usedBytes": 1288490188, "limitBytes": 5368709120, "onExceed": "block", "maxFileBytes": 104857600 } } } } }, "401": { "description": "Site Key errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`E_STORAGE_OFF` or `E_STORAGE_UNAVAILABLE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "GET /api/site/v1/files/usage" } }, "/api/site/v1/jobs": { "post": { "tags": [ "Site API" ], "summary": "Send background jobs", "description": "Send one job (`{list, data, delay | at, key, label, group}`) or up to 100 (`{jobs: [...]}`). EzyStudio keeps each job and delivers it when due to the site’s own `POST /site-api/_platform/jobs` (body `{id, list, attempt, maxAttempts, scheduledFor, group, data}`), signed (`x-site-signature: t=,v1=.\")>`), within about 1–2 seconds when due now. The site answers 2xx (done), 5xx / 408 / 429 / no answer within 60 s (tried again after 1 min, 2 min, 10 min, 1 h, honouring `Retry-After`), another 4xx (failed now, its `{error}` shown to the owner), or 404 `{code: \"no_handler\"}`. `key` dedupes for 24 h (a second send returns the first job, `deduplicated: true`). `group` matters on ordered lists (`background.json` `\"ordered\": true`): one job at a time per group, in send order. Live key only: an editor key gets 403 `E_JOBS_EDITOR_KEY` (the editor runs jobs in its own process).", "x-source": "site_jobs.service.ts, site_jobs.dispatcher.ts", "operationId": "postSiteJobs", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "list": "booking-reminders", "data": { "bookingId": 42 }, "at": "2026-11-01T09:00:00.000Z", "key": "remind-42", "label": "Reminder · Cut, Sat 10:00", "group": "customer-9" } } } }, "responses": { "202": { "description": "Accepted. One job → the job; a batch → `{jobs: [...]}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] }, "example": { "status": 202, "message": "Job accepted.", "data": { "id": "job_abcdefghijklmnopqrstuvwxyz", "list": "booking-reminders", "runAt": "2026-11-01T09:00:00.000Z", "deduplicated": false } } } } }, "401": { "description": "`E_NO_SITE_KEY`, `E_BAD_SITE_KEY`, `E_INVALID_SITE_KEY`, `E_SITE_KEY_REVOKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`E_JOBS_EDITOR_KEY`: jobs are not sent from the editor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`E_JOBS_NOT_AN_APP`: a website (static) has no background jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`E_JOBS_PAYLOAD_TOO_LARGE`: data over 32 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`E_JOBS_BAD_LIST`, `E_JOBS_BAD_TIME`, `E_JOBS_TOO_FAR` (over 1 year), `E_JOBS_LABEL`, `E_JOBS_KEY`, `E_JOBS_GROUP`, `E_JOBS_BATCH_TOO_LARGE`, or validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`E_JOBS_BACKLOG` (the list has 50,000 waiting), the per-site rate limit, or too many failed keys from this IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": "600 calls a minute per site and key kind; 50,000 waiting jobs per list.", "x-adonis-route": "POST /api/site/v1/jobs" } }, "/api/site/v1/jobs/cancel": { "post": { "tags": [ "Site API" ], "summary": "Cancel a waiting job", "description": "Cancel a job that has not run yet, by `{id}` or by the `{list, key}` it was sent with. An already cancelled job answers `cancelled: true`; one that is running or finished answers 409.", "x-source": "site_jobs.service.ts", "operationId": "postSiteJobsCancel", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "list": "booking-reminders", "key": "remind-42" } } } }, "responses": { "200": { "description": "`cancelled`: false when no such job exists.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "cancelled": { "type": "boolean" } } } } } ] }, "example": { "status": 200, "message": "Cancelled. It won't run.", "data": { "cancelled": true } } } } }, "401": { "description": "`E_NO_SITE_KEY`, `E_BAD_SITE_KEY`, `E_INVALID_SITE_KEY`, `E_SITE_KEY_REVOKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`E_JOBS_EDITOR_KEY`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`E_JOBS_NOT_CANCELLABLE`: it is running or finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/jobs/cancel" } }, "/api/site/v1/owner-sign-in": { "post": { "tags": [ "Site API" ], "summary": "Spend a one-click owner sign-in ticket", "description": "The site’s server spends the one-use, 2-minute ticket from “Log in to live admin” (the live key) or the editor Preview’s portal button (the editor key), and gets the owner address to sign in, with the current owner list. A ticket only works for its own site and for the key kind it was made for.", "x-source": "owner_sign_in.controller.ts, owner_sign_in.service.ts", "operationId": "postSiteOwnerSignIn", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket" ], "properties": { "ticket": { "type": "string" }, "version": { "type": "integer", "enum": [ 2 ] } } }, "example": { "ticket": "Qm9vay1hLXRpY2tldC1mb3ItdGhlLW93bmVyLXNpZ25pbg", "version": 2 } } } }, "responses": { "200": { "description": "An opaque id for the account owner. Never an email or name.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "ownerId": { "type": "string" } } } } } ] }, "example": { "status": 200, "data": { "ownerId": "b3duZXItaWQtZm9yLXRoaXMtc2l0ZS0wMDAwMDAwMDAwMA" } } } } }, "401": { "description": "`E_NO_SITE_KEY`, `E_BAD_SITE_KEY`, `E_INVALID_SITE_KEY`, `E_SITE_KEY_REVOKED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`E_OWNER_TICKET_INVALID`: unknown, spent, expired, another site’s, for the other key kind, or no longer an owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/owner-sign-in" } }, "/api/site/v1/payments": { "get": { "tags": [ "Site API" ], "summary": "The site’s prices", "description": "The mode (`test` or `live`, decided by the key and the account, never the site), whether the site can take payments, and its active prices.", "operationId": "getSitePayments", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] }, "example": { "status": 200, "data": { "mode": "test", "ready": true, "prices": [ { "key": "pro-monthly", "name": "Pro", "description": null, "amountCents": 1500, "currency": "USD", "interval": "month", "intervalCount": 1, "trialDays": 7 } ] } } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } } }, "x-adonis-route": "GET /api/site/v1/payments" } }, "/api/site/v1/payments/checkout": { "post": { "tags": [ "Site API" ], "summary": "Start a checkout", "description": "Starts a checkout for one price and answers how the buyer pays (`embedded`). The amount is the catalogue’s. Send an `idempotencyKey`, one per purchase attempt and the same on every retry: the same key answers the same checkout, or `{id, paid: true, embedded: null}` once it’s paid, so a double click or a retry never starts a second one. A declined or expired checkout frees the key. 120 a minute per site and key kind.", "operationId": "postSitePaymentsCheckout", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 99 }, "email": { "type": "string", "maxLength": 191, "format": "email" }, "name": { "type": "string", "maxLength": 191 }, "successPath": { "type": "string", "maxLength": 400, "pattern": "^\\/(?![/\\\\])[^\\s\\\\\\u0000-\\u001f\\u007f]*$" }, "cancelPath": { "type": "string", "maxLength": 400, "pattern": "^\\/(?![/\\\\])[^\\s\\\\\\u0000-\\u001f\\u007f]*$" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "customerRef": { "type": "string", "maxLength": 128 }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,64}$" }, "gateway": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,39}$" }, "noTrial": { "type": "boolean" } }, "required": [ "price", "successPath", "cancelPath" ] }, "example": { "price": "pro-monthly", "successPath": "/thanks/", "cancelPath": "/pricing/", "idempotencyKey": "attempt_0123456789abcdef" } } } }, "responses": { "201": { "description": "`{id, mode, embedded}`, or `{id, mode, embedded: null, paid: true}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "404": { "description": "No such price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`E_SITE_PAYMENTS_IN_PROGRESS` (the first request is still starting: keep the key and try again), `E_SITE_PAYMENTS_IDEMPOTENCY_CONFLICT` (the key was used for a different purchase), `E_SITE_PAYMENTS_TRIAL_USED` (ask the buyer, then `noTrial: true`) or `E_PAYMENTS_NOT_READY`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is not valid, or `E_SITE_PAYMENTS_EMAIL_REQUIRED`, `E_SITE_PAYMENTS_GATEWAY_UNAVAILABLE`, `E_SITE_PAYMENTS_QUANTITY`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`E_SITE_PAYMENTS_UNAVAILABLE`: the same key again is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/payments/checkout" } }, "/api/site/v1/payments/checkout/{id}": { "get": { "tags": [ "Site API" ], "summary": "What happened to a checkout", "description": "Status, amount, buyer and subscription. While it’s open, the payment is re-read from the provider, so `paid` shows at once. An editor key reads test checkouts only.", "operationId": "getSitePaymentsCheckoutId", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The checkout id (`pcs_…`).", "schema": { "type": "string", "pattern": "^pcs_[a-f0-9]{24}$" } } ], "responses": { "200": { "description": "The checkout.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } }, "404": { "description": "No such checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "GET /api/site/v1/payments/checkout/:id" } }, "/api/site/v1/payments/checkout/gateways": { "get": { "tags": [ "Site API" ], "summary": "The ways to pay a price", "description": "The payment providers the buyer may choose for this price: active, take its currency, and its free trial when it has one.", "operationId": "getSitePaymentsCheckoutGateways", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "price", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" } } ], "responses": { "200": { "description": "`{mode, gateways: [{slug, name}]}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } }, "404": { "description": "No such price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "GET /api/site/v1/payments/checkout/gateways" } }, "/api/site/v1/payments/currencies": { "get": { "tags": [ "Site API" ], "summary": "The currencies this site can charge in", "description": "The currencies a new price may use, from the site’s active payment providers.", "operationId": "getSitePaymentsCurrencies", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "responses": { "200": { "description": "The currencies.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } } }, "x-adonis-route": "GET /api/site/v1/payments/currencies" } }, "/api/site/v1/payments/memberships": { "get": { "tags": [ "Site API" ], "summary": "A buyer’s memberships", "description": "The subscriptions bought with this email. Access follows `accessEndsAt` (`hasAccess`), never `status`. Show them only to that buyer, once their email is verified.", "operationId": "getSitePaymentsMemberships", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 191, "format": "email" } } ], "responses": { "200": { "description": "`{mode, memberships}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } } }, "x-adonis-route": "GET /api/site/v1/payments/memberships" } }, "/api/site/v1/payments/memberships/{id}/cancel": { "post": { "tags": [ "Site API" ], "summary": "Cancel a membership", "description": "For the site’s own cancel button. `atPeriodEnd` keeps access until the period ends.", "operationId": "postSitePaymentsMembershipsIdCancel", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The membership: its subscription id, or our `mem_…` id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "atPeriodEnd": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "`{membership}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } }, "404": { "description": "No such membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/payments/memberships/:id/cancel" } }, "/api/site/v1/payments/prices": { "post": { "tags": [ "Site API" ], "summary": "Add a price", "description": "Editor key only. The same key with the same terms answers 200 with `created: false`. 60 an hour per site.", "operationId": "postSitePaymentsPrices", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,62}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "amountCents": { "type": "integer", "minimum": 1, "maximum": 99999999 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "interval": { "enum": [ "one_time", "month", "year" ] }, "intervalCount": { "type": "integer", "minimum": 1, "maximum": 12 }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 365 } }, "required": [ "key", "name", "amountCents", "currency", "interval" ] } } } }, "responses": { "200": { "description": "That price already exists: `{price, created: false}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "201": { "description": "`{price, created: true}`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } }, "403": { "description": "`E_SITE_PAYMENTS_EDITOR_ONLY`: a price is added with the editor key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`E_PRICE_KEY_TAKEN`: the key exists with other terms, or the owner archived it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "POST /api/site/v1/payments/prices" } }, "/api/site/v1/plans": { "get": { "tags": [ "Site API" ], "summary": "The agency’s client plans (house website)", "description": "The plans an agency sells to its clients, for its own marketing website. Any other site gets 404. Editor or live key; never cached.", "operationId": "getSitePlans", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "responses": { "200": { "description": "The plans.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } }, "404": { "description": "Not an agency’s house website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-adonis-route": "GET /api/site/v1/plans" } }, "/api/site/v1/template/download": { "get": { "tags": [ "Site API" ], "summary": "Download this site’s template", "description": "The template this site is built from, at its current version, as a zip. It’s how a site upgrades: unzip it and run `npm run platform -- upgrade --from `. It holds no secrets.", "operationId": "getSiteTemplateDownload", "security": [ { "siteKey": [] } ], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "responses": { "200": { "description": "The template as a zip." }, "401": { "description": "The Site Key is missing or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": "E_NO_SITE_KEY" } } } }, "x-adonis-route": "GET /api/site/v1/template/download" } }, "/api/public/site/v1/agent-docs": { "get": { "tags": [ "Public site" ], "summary": "Get the platform rules for coding agents", "description": "Markdown, not JSON: the core rules every AI agent follows in an EzyStudio site (it lists the topic docs). The template is `?template=`, else the template of the site on this host, else `astro-app`. Cached 5 minutes with an ETag (`If-None-Match` → 304).", "x-source": "agent_docs.controller.ts", "operationId": "getPublicSiteAgentDocs", "security": [], "servers": [ { "url": "{siteUrl}", "description": "The site’s own address (`SITE_URL`): EzyStudio answers `/api/*` there.", "variables": { "siteUrl": { "default": "https://your-site.ezystudio.app" } } } ], "parameters": [ { "name": "template", "in": "query", "required": false, "description": "`astro-app` or `astro-static`. Anything else answers 404.", "schema": { "type": "string", "maxLength": 32 } } ], "responses": { "200": { "description": "The core doc (`X-Agent-Docs-Template` names the template).", "content": { "text/markdown": { "schema": { "type": "string" }, "example": "# Site platform rules (vf2297aa7)\n\n# Rules for AI agents working in this app\n…" } } }, "304": { "description": "Not modified (ETag matched)." }, "404": { "description": "Unknown template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`E_AGENT_DOCS_UNAVAILABLE`: the docs could not be rendered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-rate-limit": "300 a minute per caller.", "x-adonis-route": "GET /api/public/site/v1/agent-docs" } }, "/api/public/site/v1/agent-docs/{topic}": { "get": { "tags": [ "Public site" ], "summary": "Get one agent topic doc", "description": "Markdown for one topic, e.g. `site-api`, `security`, `auth`, `database` (`.md` optional; `core` is the core doc).", "x-source": "agent_docs.controller.ts, templates/