API reference

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.

{
  "email": "maya@lumahair.test"
}

{
  "status": 200,
  "data": {
    "accept": true
  }
}

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.

{
  "kind": "password_reset",
  "to": "maya@lumahair.test",
  "path": "/account/reset?token=8f2c…",
  "expiresInMinutes": 30
}

{
  "status": 202,
  "message": "Email accepted for delivery.",
  "data": {
    "accepted": true
  }
}

{
  "status": 401,
  "errors": [
    {
      "message": "Invalid Site Key.",
      "code": "E_INVALID_SITE_KEY"
    }
  ]
}

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.

The file’s details (never its bytes: ask for a link).

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).

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).

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.

{
  "expiresIn": 600
}

{
  "status": 200,
  "data": {
    "url": "https://files.example/s42/live/01jbz3k8….pdf?token=…&expires=1793102400",
    "expiresAt": "2026-10-27T10:10:00.000Z"
  }
}

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/<token>): 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).

{
  "name": "cv.pdf",
  "contentType": "application/pdf",
  "size": 482113
}

{
  "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"
    }
  }
}

{
  "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"
    }
  ]
}

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.

{
  "status": 200,
  "data": {
    "usedBytes": 1288490188,
    "limitBytes": 5368709120,
    "onExceed": "block",
    "maxFileBytes": 104857600
  }
}

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=<unix>,v1=<HMAC-SHA256(SITE_JOBS_SECRET, "<t>.<body>")>), 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).

{
  "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"
}

{
  "status": 202,
  "message": "Job accepted.",
  "data": {
    "id": "job_abcdefghijklmnopqrstuvwxyz",
    "list": "booking-reminders",
    "runAt": "2026-11-01T09:00:00.000Z",
    "deduplicated": false
  }
}

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.

{
  "list": "booking-reminders",
  "key": "remind-42"
}

{
  "status": 200,
  "message": "Cancelled. It won't run.",
  "data": {
    "cancelled": true
  }
}

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.

{
  "ticket": "Qm9vay1hLXRpY2tldC1mb3ItdGhlLW93bmVyLXNpZ25pbg",
  "version": 2
}

{
  "status": 200,
  "data": {
    "ownerId": "b3duZXItaWQtZm9yLXRoaXMtc2l0ZS0wMDAwMDAwMDAwMA"
  }
}

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.

{
  "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
      }
    ]
  }
}

E_NO_SITE_KEY

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.

{
  "price": "pro-monthly",
  "successPath": "/thanks/",
  "cancelPath": "/pricing/",
  "idempotencyKey": "attempt_0123456789abcdef"
}

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.

E_NO_SITE_KEY

The payment providers the buyer may choose for this price: active, take its currency, and its free trial when it has one.

E_NO_SITE_KEY

The currencies a new price may use, from the site’s active payment providers.

E_NO_SITE_KEY

The subscriptions bought with this email. Access follows accessEndsAt (hasAccess), never status. Show them only to that buyer, once their email is verified.

E_NO_SITE_KEY

For the site’s own cancel button. atPeriodEnd keeps access until the period ends.

E_NO_SITE_KEY

Editor key only. The same key with the same terms answers 200 with created: false. 60 an hour per site.

E_NO_SITE_KEY

The plans an agency sells to its clients, for its own marketing website. Any other site gets 404. Editor or live key; never cached.

E_NO_SITE_KEY

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 <folder>. It holds no secrets.

E_NO_SITE_KEY

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).

# Site platform rules (vf2297aa7)

# Rules for AI agents working in this app
…

Markdown for one topic, e.g. site-api, security, auth, database (.md optional; core is the core doc).

{
  "status": 404,
  "errors": [
    {
      "message": "No such agent doc.",
      "code": "E_AGENT_DOC_NOT_FOUND"
    }
  ]
}

Same answer as GET /api/public/site/v1/site. This is the path the EzyStudio templates call.

The catalogue for a site’s Buy buttons. No credential: the site comes from the address it’s called on.

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. For a static site’s Buy button: no credential, the site comes from the address.

{status} only (open, paid, failed or expired), what the Buy button checks while the payment window is open. Nothing else about the buyer is shown.

As the Site API’s, for a static site’s Buy button.

On an agency's own marketing website (its house site): the plans and add-ons it sells, the same catalogue as GET /api/public/plans on its dashboard address, plus signupUrl (where Start / Buy buttons send visitors: {signupUrl}?plan=<code>&interval=month|year|lifetime) and checkoutOpen (false: the agency can't take payments yet, opensLaterReason payments_not_connected | agency_trial; show paid plans as coming soon, a $0 price stays startable while payments aren't connected). Same origin, so no CORS, key or cookies. Any other site: 404. Cache-Control: no-cache + ETag.

{
  "status": 404,
  "errors": [
    {
      "message": "Not found.",
      "code": "E_NOT_FOUND"
    }
  ]
}

The site whose address this request arrived on: name, address, logo, favicon and brand colour. Cached for 60 seconds (Cache-Control: public, max-age=60, Vary: Host).

{
  "status": 200,
  "data": {
    "id": 5,
    "name": "Luma Hair",
    "slug": "luma-hair",
    "kind": "app",
    "template": "astro-app",
    "url": "https://luma-hair.ezystudio.app",
    "logo": null,
    "favIcon": null,
    "brandColor": null
  }
}

{
  "status": 404,
  "errors": [
    {
      "message": "No site is served on this host.",
      "code": "E_SITE_NOT_FOUND"
    }
  ]
}

Live apps only. q searches names and descriptions (unmatched searches are counted as requests for new apps).

{
  "status": 200,
  "data": {
    "data": [
      {
        "id": 1,
        "slug": "salon-booking",
        "name": "Salon Booking",
        "kind": "app",
        "tagline": "Stylists, time slots, deposits and text reminders.",
        "category": {
          "slug": "bookings",
          "name": "Bookings",
          "tone": "bookings"
        },
        "developer": {
          "name": "EzyStudio",
          "slug": "ezystudio"
        },
        "icon": {
          "url": "https://ezystudio.com/api/public/app-media/v1/apps/1/demo/icon.svg",
          "alt": "Salon Booking icon"
        },
        "pricing": {
          "model": "included",
          "priceCents": null,
          "currency": "USD"
        },
        "rating": {
          "average": 4.4,
          "count": 7
        },
        "installsCount": 44451,
        "isFeatured": true,
        "isFirstParty": true
      }
    ],
    "meta": {
      "nextCursor": "eyJpZCI6MX0",
      "hasNextPage": true,
      "query": null,
      "total": 18
    }
  }
}

Everything on a listing page: the card fields plus version, description, data note, support email, customization, included, features, setup steps, made for, try saying, demo URL, compatible plans and media.

{
  "status": 404,
  "errors": [
    {
      "message": "We couldn't find that app.",
      "code": "APP_NOT_FOUND"
    }
  ]
}

Published reviews from verified buyers, with the developer’s reply.

{
  "status": 200,
  "data": {
    "data": [
      {
        "id": 1,
        "rating": 5,
        "body": "Since we started taking a $10 deposit, no-shows have almost stopped.",
        "authorName": "Maya",
        "businessName": "Luma Hair",
        "city": "Portland",
        "developerReply": null,
        "repliedAt": null,
        "createdAt": "2026-09-18T12:00:00.000Z"
      }
    ],
    "meta": {
      "sort": "recent",
      "nextCursor": null,
      "hasNextPage": false
    }
  }
}

Store categories with live app counts. Cached 60 seconds with an ETag.

{
  "status": 200,
  "data": [
    {
      "slug": "bookings",
      "name": "Bookings",
      "icon": "calendar-check",
      "tone": "bookings",
      "appsCount": 8
    }
  ]
}

The store’s collections (a title, a subtitle and the category they show).

{
  "status": 200,
  "data": [
    {
      "key": "bookings",
      "categorySlug": "bookings",
      "icon": "calendar-days",
      "tone": "a",
      "title": "Take bookings",
      "subtitle": "Salons, clinics, spas, tutors, hotels and more"
    }
  ]
}

App of the week and the featured apps.

{
  "status": 200,
  "data": {
    "appOfTheWeek": {
      "id": 1,
      "slug": "salon-booking",
      "name": "Salon Booking",
      "kind": "app",
      "tagline": "Stylists, time slots, deposits and text reminders.",
      "category": {
        "slug": "bookings",
        "name": "Bookings",
        "tone": "bookings"
      },
      "developer": {
        "name": "EzyStudio",
        "slug": "ezystudio"
      },
      "icon": {
        "url": "https://ezystudio.com/api/public/app-media/v1/apps/1/demo/icon.svg",
        "alt": "Salon Booking icon"
      },
      "pricing": {
        "model": "included",
        "priceCents": null,
        "currency": "USD"
      },
      "rating": {
        "average": 4.4,
        "count": 7
      },
      "installsCount": 44451,
      "isFeatured": true,
      "isFirstParty": true
    },
    "featured": [
      {
        "id": 1,
        "slug": "salon-booking",
        "name": "Salon Booking",
        "kind": "app",
        "tagline": "Stylists, time slots, deposits and text reminders.",
        "category": {
          "slug": "bookings",
          "name": "Bookings",
          "tone": "bookings"
        },
        "developer": {
          "name": "EzyStudio",
          "slug": "ezystudio"
        },
        "icon": {
          "url": "https://ezystudio.com/api/public/app-media/v1/apps/1/demo/icon.svg",
          "alt": "Salon Booking icon"
        },
        "pricing": {
          "model": "included",
          "priceCents": null,
          "currency": "USD"
        },
        "rating": {
          "average": 4.4,
          "count": 7
        },
        "installsCount": 44451,
        "isFeatured": true,
        "isFirstParty": true
      }
    ]
  }
}

The sale banner to show on a marketing page (or in the customer app): headline, countdown end, the public promo code while it is live, and where the button goes. banner is null when nothing shows. Cached 60 s.

The plan catalogue with prices and resources (plans + add-ons). On an agency's dashboard address: that agency's own plans, and browsers may read it from the agency's own website domains (CORS, never with credentials).

Each plan's card content (description, badge, call to action, highlights rendered from its live limits and prices) and the comparison table, per audience and locale (English fallback). ETag + 60 s cache.

One approved, listed expert (card + bio).

A SaaS-mode agency's sale link (or one client's pay link), on the agency's own host: {status (open|expired|used_up|disabled), agency {name, brand}, plan {id, name, description, resources}, price {id, amount, currency, interval, trialDays}, snapshot, forAccount, account, signedIn, cardRequired}. Joining and paying need a session (POST /api/join/:token/start, /checkout).

{
  "status": 402,
  "errors": [
    {
      "message": "This feature is not included in your plan.",
      "code": "E_RESOURCE_LIMIT_EXCEEDED"
    }
  ]
}

{
  "status": 404,
  "errors": [
    {
      "message": "This link doesn’t exist.",
      "code": "E_NOT_FOUND"
    }
  ]
}

“Hire an expert”: matches up to 3 partners. Anonymous or signed in.

{
  "need": "finish_app",
  "budgetBand": "500_1500",
  "timeline": "month",
  "language": "en"
}

The requester’s lead and its matches.

Offers the lead to one of its matched partners.

{
  "partner": "casa-pixel"
}

Ladder tiers (Starter → Rising → Pro → Elite, Founding): points floor, referral %, perks, and founding spots left.

The expert directory.

An agency's own client referral programme, on the agency's host (404 on the platform's host): a ?ref=CODE landing (landing path + salted IP hash, no other PII). {recorded} is false for an unknown, paused or inactive code, or while the agency's programme is off.

{
  "code": "MAYA-7K2Q",
  "path": "/pricing"
}

An agency's own client referral programme, on the agency's host: {valid, reason (not_found|inactive|self), discountPercent, referrer}. 404 on the platform's host or while the agency has no live programme.

A ?ref=CODE landing (landing path + salted IP hash, no other PII).

{
  "code": "MAYA-7K2Q",
  "path": "/pricing"
}

{valid, reason (not_found|inactive|self), referrer, perk}.

Tiers, commission months, the welcome perk and the points rules.

Listing images while EzyStudio stores media itself (with object storage, media URLs point at the bucket). Bundles are never served.

The agency whose dashboard host this is: EzyStudio itself, or a white-label partner’s brand.

{
  "status": 200,
  "data": {
    "isMaster": true,
    "name": "EzyStudio",
    "brand": null,
    "clientSitePattern": null
  }
}

Images used in EzyStudio emails (brand-mark.png).

The link in the “your data export is ready” email: the ZIP of a person’s own data. No session; the token is the authorization, and it only works on the host of the agency that sent it.

The “Download source” link of the staff review screen: a signed token, valid 5 minutes, minted for staff holding platform:review:source (POST /api/staff/v1/review/:id/source) or an admin holding app_versions.source (POST /api/admin/v1/developers/submissions/:id/source). Answers the exact bytes of the frozen bundle (sha256-checked), as an attachment, never cached. Expired, tampered or superseded links are 404.

The 5-minute link from POST …/sites/:siteId/database/v1/backups/download (owner or admin, site_database:update): the backup as a pg_dump custom-format file (pg_restore reads it). No session; the sealed ticket is the authorization. It works once, only on the host of the agency that issued it, and only while the backup is ready and not expired. Sent with Cache-Control: no-store and Content-Disposition: attachment.

Where a signed link points when the platform stores files on its own disk (local development). Use the url from “Get a signed link to a file”.

The language a first-time visitor sees, from their country (Cloudflare CF-IPCountry): {locale, country}. English when the country has no translated language or is unknown. Not cached in shared caches (Cache-Control: private, no-store); the browser keeps the answer in a cookie for 30 days.

{
  "locale": "de",
  "country": "DE"
}

Envelope

Every JSON success answer: {status, data}, plus message on writes (start/macros/response.ts sendFormatted).

Error

Every error answer: {status, errors: [{message, code}]} (sendError). Branch on code, never on message.

ValidationError

422 from a Vine validator: one entry per failed rule (no status key in this shape).

CursorMeta

Keyset pages: pass nextCursor back as cursor. There are no totals.

PublicSite

The public projection of a site (site_public.controller.ts publicSiteProjection). Never the account, the owner or a setting.

AppManifest