API Reference

curl -X POST "https://your-domain/api/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}'

Returns {"token": "eyJ..."} — a JWT valid for the duration configured in your secrets.php (JWT_TTL).

Requires a valid user JWT or PAT. Returns id, email, role, created_at, project_id, and project_name.

curl "https://your-domain/api/v1/auth/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns a raw token in the response. Deliver it to the user via your own email flow. Token expires in 1 hour. Always returns the same shape to prevent email enumeration.

curl -X POST "https://your-domain/api/v1/auth/forgot" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response: {"message": "...", "token": "abc123...", "expires_in": 3600}

curl -X POST "https://your-domain/api/v1/auth/reset" \
  -H "Content-Type: application/json" \
  -d '{"token": "abc123...", "password": "new-password"}'

On success returns a fresh JWT: {"message": "Password updated successfully.", "token": "eyJ..."}

curl -X POST "https://your-domain/api/v1/projects" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My App"}'

Response includes the new project's id, name, and service_key.

Drops all physical MySQL tables, removes all site directories and storage files from disk, then deletes the project row (cascades to all catalog rows).

curl -X DELETE "https://your-domain/api/v1/projects/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Generates a new service_key JWT and stores it in the database. The previous service_key stops working as soon as this is called — update any consumers before rotating.

curl -X POST "https://your-domain/api/v1/projects/1/rotate-service-key" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"service_key": "eyJ..."}.

GET /api/v1/overview summarizes every project you own (table counts, live sites). GET /api/v1/projects/:id/overview gives one project's tables, sites, and a recent-activity feed (deploys, project creation). Useful for a quick "what's already here" check before editing an existing project.

curl "https://your-domain/api/v1/projects/1/overview" \
  -H "Authorization: Bearer YOUR_TOKEN"

Removes only the rows that were inserted as seed/demo data (tracked separately from rows created afterward through normal use) — for clearing placeholder content before real users start using the app, without touching anything they've since added.

curl -X POST "https://your-domain/api/v1/projects/1/seed/clear" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Maintenance operation — drops orphaned physical tables no longer in the catalog, removes catalog rows for tables that no longer exist in MySQL, and clears stale deploy/directory records. Not something you'd normally need in regular use; useful if something got out of sync (e.g. a failed operation left partial state).

curl -X POST "https://your-domain/api/v1/projects/1/cleanup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://your-domain/api/v1/projects/1/tables" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "users"}'

Table names must match ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$. The physical MySQL table is named p{project_id}_{name}.

Three formats accepted: a shorthand object (fewest keystrokes), a JSON array of explicit objects, or a single explicit object.

## Shorthand (recommended) — list allowed ops, the rest are auto-denied
curl -X PUT "https://your-domain/api/v1/projects/1/tables/posts/policies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "api_role": "anon",          "allow": ["SELECT"] },
    { "api_role": "authenticated", "allow": ["SELECT", "INSERT", "UPDATE", "DELETE"] }
  ]'

## Explicit array — full control over each operation
curl -X PUT "https://your-domain/api/v1/projects/1/tables/posts/policies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "api_role": "anon",          "operation": "SELECT", "allowed": true  },
    { "api_role": "anon",          "operation": "INSERT", "allowed": false },
    { "api_role": "authenticated", "operation": "SELECT", "allowed": true  },
    { "api_role": "authenticated", "operation": "INSERT", "allowed": true  }
  ]'

## Single object — one policy per call
curl -X PUT "https://your-domain/api/v1/projects/1/tables/posts/policies" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "api_role": "anon", "operation": "SELECT", "allowed": true }'

constraint_sql is an optional WHERE clause appended to queries. Use :current_user_id as a placeholder for the authenticated user's ID (e.g. "user_id = :current_user_id"). Batch/shorthand response: {"updated": N, "policies": [...]}.

IDs in responses are numbers (integers), not strings.

The list response is a paginated envelope — always unwrap .data in client code:

# Anonymous (no auth header — subject to anon policy)
curl "https://your-domain/api/v1/data/1/users?limit=20&offset=0&status=active"

# Authenticated (service_key bypasses all policies)
curl "https://your-domain/api/v1/data/1/users?limit=20&offset=0&status=active" \
  -H "Authorization: Bearer <service_key>"

Returns: {"data": [{...}, ...], "count": N, "limit": N, "offset": N} — read rows from .data.

curl -X POST "https://your-domain/api/v1/data/1/users" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

Only fields that match defined columns are accepted. Extra fields are silently ignored.

If the table has a unique: true column and this insert's value for it already exists on another row, the request fails with 409 Conflict instead of creating a duplicate — check for that status rather than assuming any non-2xx means the same thing a validation error would.

Send a JSON array of objects. Each row is inserted individually and subject to the same INSERT policy as a single insert. Returns all inserted rows.

curl -X POST "https://your-domain/api/v1/data/1/skills/batch" \
  -H "Authorization: Bearer <service_key>" \
  -H "Content-Type: application/json" \
  -d '[
    {"name": "PHP",        "category": "Backend",  "level": 5},
    {"name": "JavaScript", "category": "Frontend", "level": 4},
    {"name": "MySQL",      "category": "Database", "level": 5}
  ]'

Returns: {"inserted": 3, "rows": [{...}, {...}, {...}]}. Max 500 rows per request.

The table must have exactly one PASSWORD-type column. Provide a column that identifies the user (e.g. email) and the plaintext password. If the credentials match, a project_user JWT (role: authenticated) is returned and can be passed as Authorization: Bearer in subsequent data API calls.

curl -X POST "https://your-domain/api/v1/data/1/users/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "secret123"}'

Returns {"token": "eyJ...", "user": {...}} — user is the matched row (password field masked). The JWT carries sub (row id), pid (project id), type: "project_user" and auth: "password". Use it as Bearer auth in subsequent data API calls to get the authenticated role.

"Continue with Google" for your app's end users. Your page gets an ID token from Google Identity Services (the credential in its callback) and posts it here. SupaBein verifies it itself (RS256 signature against Google's published keys, issuer, audience = one of your client_ids, not expired with 60 s clock-skew allowance, email_verified), then signs the person in to the matching row, or creates one, and returns the same token as /login. Policies, Functions (user, sb.auth.getUser()) and end-user storage all work unchanged. Turn it on first with PUT /projects/:id/auth/google.

curl -X POST "https://your-domain/api/v1/data/1/users/google" \
  -H "Content-Type: application/json" \
  -d '{"id_token": "eyJhbGciOiJSUzI1NiIs..."}'

Returns 200 {"token": "eyJ...", "user": {...}, "created": false}: user is the row (password masked) and created is true when this sign-in made a new account. The token's auth claim is "google"; a Function can read it with sb.auth.method().

The ID token is never stored or logged.

curl -X PUT "https://your-domain/api/v1/projects/1/auth/google" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "client_ids": ["1234-abc.apps.googleusercontent.com"],
    "table": "users",
    "email_column": "email",
    "auto_create": true,
    "map": { "name": "name", "picture": "avatar_url" },
    "defaults": { "role": "learner", "onboarded": false },
    "sub_column": "google_sub",
    "provider_column": "auth_provider"
  }'

Every column is checked against the table when you save (422 with the reason otherwise). GET on the same path returns the settings plus the endpoint to call. A project-scoped PAT can use both.

In the browser, the button from Google Identity Services gives you the token:

<script src="https://accounts.google.com/gsi/client" async></script>
<div id="g_id_onload" data-client_id="1234-abc.apps.googleusercontent.com" data-callback="onGoogle"></div>
<div class="g_id_signin" data-type="standard"></div>
<script>
  async function onGoogle({ credential }) {
    const res = await fetch('/api/v1/data/1/users/google', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ id_token: credential }),
    })
    const { token, user, created } = await res.json()   // store token like a /login token
  }
</script>

curl -X POST "https://your-domain/api/v1/data/1/users/forgot" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com"}'

Same identifier auto-detection as /login — whichever non-PASSWORD column you send becomes the lookup key. Always returns the same generic {"message": "..."} regardless of whether it matched a row, whether an auth email provider is registered, or whether sending succeeded — this is deliberate, it's what stops the endpoint being used to check which addresses have accounts.

The token isn't emailed unless you register an auth email provider for this project. Without one, this endpoint still generates and stores the token (so your own project can email it another way if you build that), but nothing is sent automatically.

curl -X POST "https://your-domain/api/v1/data/1/users/reset" \
  -H "Content-Type: application/json" \
  -d '{"token": "<from the emailed link>", "password": "newSecret123"}'

Token expires 1 hour after /forgot generated it, and is single-use. On success, returns {"message": "...", "token": "eyJ..."} — the same project_user JWT shape as /login, so you can log the user straight in.

Send as multipart/form-data with field name file. The bucket is created automatically if it doesn't exist.

curl -X POST "https://your-domain/api/v1/projects/1/storage/avatars" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@photo.jpg"

Returns {"name": "photo.jpg", "bucket": "avatars", "size": 24580, "url": "/api/v1/storage/1/avatars/photo.jpg"}

curl "https://your-domain/api/v1/projects/1/storage/avatars" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"files": [{name, size, last_modified, url}, ...], "count": N}

Use the url value returned by upload or list. This URL is public — link to it directly from your frontend.

curl "https://your-domain/api/v1/storage/1/avatars/photo.jpg"

Returns the file with correct Content-Type (video, audio, images and PDFs are typed by extension so they play/display inline) and cache headers (Cache-Control: public, max-age=86400, ETag, Last-Modified — repeat visits get a cheap 304).

Video and audio stream properly: byte-range requests are supported (Accept-Ranges: bytes, 206 Partial Content, HEAD), so a plain <video src="…/lesson.mp4" controls preload="none"> can seek, iPhone Safari plays it, and a viewer who stops watching stops downloading. Media is sent in slices of at most 8 MB per request, which players fetch as they need them. This works the same on a site's own domain (/api/v1/storage/… is proxied through to SupaBein without buffering).

curl -X POST "https://your-domain/api/v1/projects/1/storage/lessons/uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"filename": "lesson-1.mp4", "size": 73400320}'

Returns 201 {"upload_id", "bucket", "name", "size", "received": 0, "chunk_size": 8388608, "complete": false, "expires_at"}. 413 if size is over the bucket's limit.

Raw bytes as the body (up to chunk_size), and the chunk's starting position in an Upload-Offset header — which must equal received. Returns the updated status; the chunk that completes the file returns 201 {"complete": true, "name", "bucket", "size", "url"}, like a normal upload.

curl -X PUT "https://your-domain/api/v1/projects/1/storage/lessons/uploads/UPLOAD_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/octet-stream" \
  -H "Upload-Offset: 0" --data-binary @chunk-0.bin

409 {"received": N} if the offset is wrong (continue from N); 413 if the chunk is too big.

Returns the same status object; continue sending from received. DELETE on the same path abandons the upload. 404 once it has completed or expired.

curl -X PUT "https://your-domain/api/v1/projects/1/storage/avatars/policy" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"authenticated_upload": true}'

Returns {"project_id", "bucket", "allow_authenticated_upload", "max_file_size", "effective_max_file_size"}. Settings you leave out keep their current value (authenticated_upload and max_file_size can be sent together or separately). There's a matching GET on the same path to check the current settings.

curl "https://your-domain/api/v1/projects/1/sites" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns an array of site objects including id, subdomain, spa_mode, current_deploy_id, and created_at. Each project supports one site.

curl -X DELETE "https://your-domain/api/v1/projects/1/sites/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Permanently deletes the site record and all associated deploy records. The deployed files on disk are also removed.

curl -X POST "https://your-domain/api/v1/projects/1/sites" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "myapp", "spa_mode": false}'

subdomain must be 2–63 lowercase alphanumeric characters or hyphens (e.g. "my-app"). name is accepted as an alias for subdomain. Set spa_mode: true for single-page apps — unknown paths will serve index.html instead of 404. Each project supports one site.

curl -X PATCH "https://your-domain/api/v1/projects/1/sites/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "new-name", "custom_domain": "www.example.com"}'

Both fields are optional — omit one to leave it unchanged. Send custom_domain: "" to remove a custom domain. Changing the subdomain does not free it up for anyone else to reuse until the change is saved. Also settable from the dashboard's project page, under the Domain tab.

This is separate from registering a hostname below — a site's own subdomain/custom_domain is the one canonical domain shown in the dashboard, whereas hostname registration lets a project claim any number of additional hostnames (e.g. one per end-user storefront in a multi-tenant app). Setting either field here automatically keeps the registration in sync — nothing else needs to be called for a site's own subdomain to start resolving.

curl -X POST "https://your-domain/api/v1/projects/1/hostnames" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "joes-store.your-domain"}'

For apps that serve many end-user-facing sites from a single deploy — e.g. a store-builder project where every merchant gets their own storefront address. Register a hostname (a subdomain of the platform's own domain, or a fully external domain you control) and it immediately starts serving this project's current deploy, no redeploy needed.

The target is always this project's own current deploy — there is no way to point a hostname at another project's files, and no docroot/path parameter is accepted. One project can register any number of hostnames this way; there's no fixed limit.

Accepts a project_user token, not just an owner JWT or PAT — this is what makes fully automatic registration practical: call this endpoint using the end-user's own session token, right at signup/onboarding time (e.g. the moment a merchant finishes creating their store), and their subdomain goes live with no separate owner-level credential involved. A project-user token is only ever trusted for the one project it was issued from — it can't be used to register a hostname for, or otherwise touch, any other project.

Each hostname remembers which specific end-user registered it, not just which project — a second merchant's project_user token in the same app can't reassign or delete a hostname registered by a different merchant's token, even though both belong to the same project. A hostname registered by the project's own owner JWT or a PAT (e.g. the project's own default subdomain) can never be touched by any project_user at all, only by the owner. This exists specifically to stop one end-user from griefing another's storefront address — it's an availability protection, not a data one; your own row-level policies are still what protect the underlying business data.

Your app is responsible for reading window.location.hostname client-side and rendering the right content for it (e.g. looking up a merchant by slug) — registering the hostname only makes it resolve to your deploy, it doesn't change what your app renders.

curl -X DELETE "https://your-domain/api/v1/projects/1/hostnames/joes-store.your-domain" \
  -H "Authorization: Bearer YOUR_TOKEN"

An owner JWT or PAT can remove any hostname belonging to its project. A project_user token can only remove a hostname it registered itself — see the per-registrant note above. Do this whenever whatever the hostname pointed at (a merchant, a business, a tenant) is deleted or renamed — an unregistered hostname is freed up for anyone to claim.

curl "https://your-domain/api/v1/projects/1/sites/1/deploys" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns deploys newest-first with id, version_label, status (pending / processing / ready / failed), size_bytes, and uploaded_at.

Upload a zip archive (multipart/form-data, field name zipfile, max 50 MB). The zip must not contain .php, .sh, or other server-executable files. If the zip has a single wrapper folder, it's automatically unwrapped.

cd dist && zip -r ../deploy.zip . && cd ..
curl -X POST "https://your-domain/api/v1/projects/1/sites/1/deploys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "zipfile=@./deploy.zip" \
  -F "label=v1.0.0"

After a successful upload, the deploy lands in staging (not live yet).
Preview at: https://your-domain/sites/s{site_id}/staging/
Then call Publish to live to make it the active version.

Copies staging/ to current/, sets current_deploy_id, and clears staging_deploy_id on the site. The deploy must be the current staging deploy (its ID must match site.staging_deploy_id). Returns the updated site object including live_url and staging_url.

curl -X POST "https://your-domain/api/v1/projects/1/sites/1/deploys/5/publish" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response includes live_url (the public URL) and staging_url for immediate use — no need to construct URLs manually.

Creates an empty staging directory and returns a deploy record with status: "pending". Optionally accepts a label for version tracking. Use the returned id in subsequent file upload calls.

curl -X POST "https://your-domain/api/v1/projects/1/sites/1/deploys/open" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"v2.1.0"}'

Returns: { id, site_id, version_label, status: "pending", staged_dir, uploaded_at }

Send the raw file bytes as the request body. The ?path= query parameter specifies where the file goes relative to the site root. Subdirectories are created automatically. Blocked extensions (.php, .sh, etc.) return 403.

curl -X POST "https://your-domain/api/v1/projects/1/sites/1/deploys/7/files?path=assets/app.js" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --data-binary "@./dist/assets/app.js"

Returns: { path, size }

curl "https://your-domain/api/v1/projects/1/sites/1/deploys/7/files" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns: { deploy_id, status, files: [{ path, size }, ...] }

Only works while the deploy is still in pending status.

curl -X DELETE "https://your-domain/api/v1/projects/1/sites/1/deploys/7/files?path=old-page.html" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns: { deleted: true, path }

Writes the hardening .htaccess, moves files to the staging directory, and marks the deploy ready. Returns 422 if no files were uploaded (empty deploy). The site is not live yet — call Publish to live to promote it.

curl -X POST "https://your-domain/api/v1/projects/1/sites/1/deploys/7/finalize" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns the updated deploy record with status: "ready" and staging_url.

Compares the file tree of :deploy_id against ?vs=:other_id using SHA-256 hashes. Both deploys must be in ready status. Files in added are present in :deploy_id but not in vs; removed is the inverse.

curl "https://your-domain/api/v1/projects/1/sites/1/deploys/7/diff?vs=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "deploy_id": 7,
  "vs": 5,
  "added":    ["assets/new-logo.svg"],
  "removed":  ["old-page.html"],
  "modified": ["index.html", "assets/app.js"],
  "unchanged": 12
}

This is how you read the actual source of an already-deployed app — the deploy-list and diff endpoints only ever give you file names and sizes, never content. Omit path (or use /) to list the site root; point path at a file to read it.

## List a directory
curl "https://your-domain/api/v1/projects/1/sites/1/browse?path=core" \
  -H "Authorization: Bearer YOUR_TOKEN"

## Read a file's content
curl "https://your-domain/api/v1/projects/1/sites/1/browse?path=core/router.js" \
  -H "Authorization: Bearer YOUR_TOKEN"

Directory response: {"path", "type": "dir", "items": [{"name", "type", "size"}, ...]}. File response: {"path", "type": "file", "size", "content", "truncated"} — content is the raw file text, null with truncated: true for files over 512 KB.

Faster than browsing file-by-file when you need the whole app at once — e.g. before editing an existing project. Works on any past deploy, not just the live one.

curl "https://your-domain/api/v1/projects/1/sites/1/deploys/7/download" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o deploy.zip

Returns the zip as a binary response (Content-Type: application/zip), not JSON.

Returns the resolved current/ directory path, whether it exists, and its top-level file listing. Useful when a deploy reports success but the live site doesn't reflect it — diagnoses that class of problem directly instead of guessing from the outside.

curl "https://your-domain/api/v1/projects/1/sites/1/debug" \
  -H "Authorization: Bearer YOUR_TOKEN"

Errors are deduplicated server-side by a fingerprint of type+message+stack — repeated occurrences of the same error increment occurrences and last_seen_at rather than creating duplicate rows.

curl "https://your-domain/api/v1/projects/1/errors" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"errors": [{id, type, message, stack, url, user_agent, meta, occurrences, first_seen_at, last_seen_at}, ...]}. type is one of js_error, promise_rejection, api_error, console_error.

Housekeeping once triaged — there's no per-error delete, only clear-all.

curl -X DELETE "https://your-domain/api/v1/projects/1/errors" \
  -H "Authorization: Bearer YOUR_TOKEN"

curl -X POST "https://your-domain/api/v1/projects/1/integrations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "paystack",
    "base_url": "https://api.paystack.co/",
    "secret": "sk_live_...",
    "auth_style": "bearer",
    "allowed_project_user_paths": ["bank/resolve"]
  }'

Owner JWT or PAT only — never a project_user token. base_url must be https:// and is a hard prefix: the proxy only ever forwards requests whose resolved URL stays under it, and both registration and every call re-check that the host doesn't resolve to a private/internal address (blocks pointing an integration at your own infrastructure).

auth_style is one of bearer (Authorization: Bearer <secret>), header:X-Api-Key (a literal header name of your choice), or query:api_key (a literal query param name) — enough to cover Paystack, most SMS/WhatsApp providers, and Meta's Graph API without needing arbitrary request-shaping logic.

allowed_project_user_paths is optional and defaults to null, meaning no project_user may ever call this integration's proxy — only the project's own owner JWT/PAT can. List specific request paths (exact match, or ending in / to match everything under that prefix) to let any authenticated end-user trigger just those calls — e.g. letting a business owner resolve their own bank account before you save their payout details, without giving them the secret itself.

curl -X POST "https://your-domain/api/v1/projects/1/integrations/paystack/proxy" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "path": "subaccount",
    "body": {"business_name": "Lois Stores", "settlement_bank": "058", "account_number": "0123456789", "percentage_charge": 2}
  }'

SupaBein resolves base_url + path, injects the stored secret per auth_style, makes the request server-side, and returns {"status": <upstream HTTP status>, "body": <upstream response, parsed if JSON>}. The caller never sees the secret. Redirects are never followed. Authorization accepts the project's own owner JWT/PAT, or a project_user token if this integration's allowed_project_user_paths opts the requested path in — otherwise a project_user call is rejected with 403.

curl -X POST "https://your-domain/api/v1/projects/1/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "paystack-charge-success",
    "signature_header": "x-paystack-signature",
    "signature_algorithm": "hmac-sha512",
    "signature_secret": "sk_live_...",
    "match": { "event": "charge.success" },
    "write": {
      "table": "orders",
      "match_column": "payment_reference",
      "match_value_path": "data.reference",
      "set": {
        "payment_status": { "literal": "paid" },
        "amount_confirmed_kobo": { "path": "data.amount" }
      }
    }
  }'

Owner JWT or PAT only. signature_algorithm is hmac-sha256 or hmac-sha512. match is optional — if set, a delivery whose payload doesn't match every key (resolved as a dot-path, e.g. "event" or "data.event") is a no-op, not an error. write.table/match_column/every key in write.set are validated against your project's real columns at registration time, so a typo fails loudly here instead of silently on every real delivery.

Each write.set value is either {"literal": ...} (a fixed value) or {"path": "a.b"} (pulled from the payload via dot-path) — never an expression. The write is idempotent: if every target column already holds the value the write would set, it's skipped — safe against the at-least-once redelivery every real webhook sender (Paystack included) does.

No Authorization header — the sender proves itself via the signature header you configured, verified over the exact raw request body. An invalid or missing signature gets 401 and no write is attempted. Anything else — including a payload match didn't match, or a row that couldn't be found — returns 200 with {"received": true, "applied": <bool>, ...}, by design: most senders retry aggressively on a non-2xx response, and a slow/erroring receiver causes duplicate-delivery storms, not safety. Check the response body (or your project's Error Logs) to see what actually happened, don't infer it from the status code.

curl -X PUT "https://your-domain/api/v1/projects/1/repo" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your-name/your-repo",
    "token": "github_pat_...",
    "branch": "main",
    "path_prefix": "supabein",
    "auto_push": false
  }'

token is required the first time and optional afterwards (leave it out to keep the stored one). branch must already exist; leave it out for the repository's default branch. path_prefix puts everything in a subfolder instead of the repository root. auto_push lets a scheduled job (scripts/repo_push.php, run from cron) push whenever the project has changed. GET on the same path returns the link and the last push result; DELETE disconnects it (the repository is left as it is).

curl "https://your-domain/api/v1/projects/1/repo" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"connected": false} when no repository is linked. Otherwise {"connected": true, "repo", "url", "branch" (null = the repository's default branch), "path_prefix", "auto_push", "last_status" ("pushed" | "unchanged" | "error"), "last_commit", "last_error", "last_pushed_at"}. The token is never returned.

curl -X POST "https://your-domain/api/v1/projects/1/repo/push" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"status": "pushed" | "unchanged", "commit": "...", "url": "...", "added": n, "changed": n, "deleted": n, "skipped": [...]}. Nothing is committed when nothing changed. The push never forces: if the branch moved on GitHub in the meantime it fails and can simply be run again. GET /api/v1/projects/:id/repo/preview lists the files a push would send.

curl "https://your-domain/api/v1/projects/1/repo/preview" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"files": [{"path", "bytes"}, ...], "skipped": [...]}: everything that would be exported, and the site files left out (over 5 MB, or past the 500-file / 40 MB limit). Nothing is sent to GitHub and no repository needs to be connected.

curl -X DELETE "https://your-domain/api/v1/projects/1/repo" \
  -H "Authorization: Bearer YOUR_TOKEN"

Removes the link and the stored token. The repository and everything already pushed to it stay as they are. 404 if nothing was connected.

supabein.json                manifest: project name, stack, sites
schema/tables.json           tables, columns, policies
functions/NAME.js            the function's draft code
functions/NAME.json          method, path, auth, enabled, live version
functions/NAME.live.js       only when the published code differs from the draft
config/assistants.json  webhooks.json  triggers.json  meta-resolvers.json
config/integrations.json     names and base URLs, never the secrets
config/function-env.json     names, and values of non-secret variables
sites/SUBDOMAIN/...          the files of each site's live version

Never exported: table rows, uploaded files, service keys, tokens, integration secrets, webhook signing secrets, secret function variables and end-user data. Only the folders above are managed: SupaBein adds, updates and removes files there, and leaves everything else in the repository (a README, other folders) alone. Site files over 5 MB, and anything beyond 500 files or 40 MB of site files, are skipped and listed in the push result.

curl -X POST "https://your-domain/api/v1/projects/1/auth-email-provider" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "resend",
    "forgot_password": {
      "path": "emails",
      "from": "no-reply@your-domain",
      "subject": { "literal": "Reset your password" },
      "text": { "template": "Reset it here: https://your-app/#/reset-password?token={{token}}" }
    }
  }'

integration must already be registered (see Integrations) — this only stores routing + a template, not a secret. subject/text are declarative value specs — {"literal": ...} or {"template": "...{{token}}..."} — resolved against exactly two variables: email (whatever identifier /forgot was called with) and token (the raw reset token). The outbound request body is {"to": [email], "subject": ..., "text": ..., "from": ...} — matches Resend's API shape; any provider that accepts a similar JSON body works.

curl -X POST "https://your-domain/api/v1/projects/1/triggers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "notify-new-lead",
    "table": "leads",
    "event": "insert",
    "integration": "resend",
    "request": {
      "method": "POST",
      "path": "emails",
      "body": {
        "to": { "literal": "owner@example.com" },
        "subject": { "template": "New lead: {{row.name}}" },
        "text": { "template": "{{row.name}} ({{row.email}}) says: {{row.message}}" }
      }
    }
  }'

event only supports "insert" today. integration must already be registered. Every value in request.body is a declarative spec — {"literal": ...}, {"path": "row.x"}, or {"template": "...{{row.x}}..."} — resolved against {"row": <the inserted row>} (password columns already masked). Multiple triggers can target the same table/event — all of them fire.

curl -X POST "https://your-domain/api/v1/projects/1/meta-resolvers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "storefront",
    "path_pattern": "/store/:slug/*",
    "lookup": { "table": "businesses", "match_column": "slug", "match_value_path": "params.slug" },
    "meta": {
      "title": { "path": "row.name" },
      "og:description": { "path": "row.home_tagline", "fallback": { "path": "row.about_text" } },
      "og:image": { "path": "row.logo_url", "fallback": { "path": "row.hero_image_url" } }
    }
  }'

path_pattern uses the same :name capture syntax as everything else on the platform, plus an optional trailing /* to match (and ignore) anything after that point — e.g. /store/:slug/* matches /store/lois-stores/products/42 with params.slug = "lois-stores". Each meta value is a declarative spec resolved against {"row": <looked-up row>, "params": {...}}, with an optional same-shaped fallback tried if the primary resolves empty. The key "title" is special-cased into <title>; keys starting with og: or twitter: become <meta property="...">; anything else becomes <meta name="..."> (e.g. "description").

Only ever runs for a request from a known crawler UA (WhatsApp, facebookexternalhit, Twitterbot, Slackbot, Discordbot, LinkedInBot, and a handful of others) landing on an HTML document — a real visitor's browser, and every asset request, is completely unaffected.

lookup.match_value_path is normally "params.<name>" — a value captured from path_pattern. It can also be one of two reserved values that read the request's Host header instead, for the case where there's no path segment to capture from at all — e.g. a business's own <slug>.your-domain subdomain, whose bare root (GET /) is the natural URL to share:

curl -X POST "https://your-domain/api/v1/projects/1/meta-resolvers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "storefront-subdomain",
    "path_pattern": "/*",
    "lookup": { "table": "businesses", "match_column": "subdomain", "match_value_path": "host.label" },
    "meta": {
      "title": { "path": "row.name" },
      "og:description": { "path": "row.home_tagline" }
    }
  }'

The two lookup sources compose — register both a path-based resolver (for a shared domain serving many tenants under one path prefix) and a hostname-based one (for per-tenant subdomains) on the same project.

curl "https://your-domain/api/v1/ai/models" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns {"models": [{"label": "...", "provider": "...", "model": "...", "badge": "..."}, ...]} — the exact provider/model values are what you pass in a chat assistant's models field below. This list is text-chat providers/models only; there's no separate discovery endpoint for image providers/models yet — see Generate an image for the current image registry. Deliberately dynamic rather than a hardcoded list here in the docs — a provider with no configured API key on this server is already filtered out, so everything returned is guaranteed callable right now, not aspirational.

The default model. On a server whose models come from Bein, this list is Bein's own model list, in Bein's order (provider is always "bein", model is the name Bein gives it). When a call names no model, SupaBein tries them in that order and the first one that answers is used, so the first entry is the default and whoever runs Bein sets it by reordering Bein's configuration. A model you name explicitly is the only one tried: if it fails, the call fails with that model's own error rather than quietly switching. A model that is listed can still fail when its provider account is out of credit, so check a model with a short test call before relying on it.

curl -X POST "https://your-domain/api/v1/projects/1/ai-assistants" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "kind": "chat",
    "system_prompt": "You are Lois Stores'"'"' support assistant. Be concise and friendly.",
    "allow_project_user": true,
    "models": [
      {"provider": "zhipu", "model": "glm-4.5-flash"},
      {"provider": "groq", "model": "llama-3.3-70b-versatile"}
    ],
    "json_mode": false
  }'

kind is optional, defaulting to "chat" — a conversational assistant called via POST .../chat. Set it to "image" to register an image-generation assistant instead, called via POST .../image; its models (if given) is validated against the separate image provider/model registry rather than the text one, and system_prompt/json_mode are ignored.

system_prompt is optional (omit for a generic assistant with no special instructions) and locked — end users can never see or override it. allow_project_user defaults to false (owner/PAT-only); set it to let any authenticated end user of your project (a project_user token) call it directly — the natural setting for a customer-facing support/chat feature or an in-app image tool.

models is optional — omit it entirely to use the platform's own default model selection (on a Bein server: the first model in Bein's list that answers; no code change needed if you never touch this). When set, it's an ordered list of {"provider", "model"} pairs (see Available models for valid chat values) this assistant tries in turn: on a hard provider failure (rate limit exhausted, no credit, invalid key) it automatically moves to the next candidate, so a call only ever fails outright if every candidate in your list is currently unavailable. Each pair is validated against the server's real, currently-configured models at registration time — an unrecognized provider or model returns 422 with the actual valid options for that provider, rather than silently storing something that would fail later.

json_mode (chat assistants only) defaults to false — the right setting for a normal conversational bot; the model replies in plain language, and forcing JSON syntax on that would either mangle a reply into a stray wrapped value or get the request outright rejected by some providers. Set it true only if this assistant's own system_prompt instructs the model to output structured JSON and your own code parses reply as JSON afterward — a one-shot content/config generator reusing this chat endpoint rather than a real back-and-forth conversation.

curl -X POST "https://your-domain/api/v1/projects/1/ai-assistants/support-bot/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What are your store hours?"}
    ]
  }'

messages is the full conversation so far (send prior turns back each time — there's no server-side session) — each item is {"role": "user"|"assistant", "content": "..."}. The final item must be a user turn. Returns {"reply": "...", "provider": "...", "model": "...", "usage": {...}, "cost_micro_usd": N}. cost_micro_usd is what this one call was billed (1,000,000 = $1.00) — useful for your own usage display, though the source of truth is always the account's actual balance.

Attachments (optional). Add "attachments": [{"filename": "menu.pdf", "mime_type": "application/pdf", "data_base64": "..."}] to send documents or images with the last user message — PNG/JPEG/WEBP/GIF images, PDF, .docx, and text/Markdown/HTML/CSV/JSON. Up to 8 files, 15 MB each, 40 MB in total; a bad file is a 422, never silently dropped. From a Function use sb.ai.chat(name, message, { attachments }) (see Functions).

reply's format follows the assistant's own json_mode setting (see Register an assistant) — plain conversational text by default, regardless of which candidate in a models fallback chain actually answered, or strict JSON if the assistant was registered with json_mode: true. There's no per-call override here; the setting is fixed at registration time for the assistant as a whole.

Callable by the project's own owner/PAT, or by a project_user token if the assistant's allow_project_user is set. 402 if the owning account is out of AI credit and not on an unlimited grant. 400 if this assistant's kind isn't "chat".

curl -X POST "https://your-domain/api/v1/projects/1/ai-assistants/icon-generator/image" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "3D clay render icon of a potted cactus, isolated, plain background"
  }'

Image-generation counterpart to the chat endpoint above, callable only on a "kind": "image" assistant — same allow_project_user auth posture. prompt is a single plain-text description; there's no conversation history or system prompt for image assistants. Returns {"image_base64": "...", "provider": "...", "model": "...", "cost_micro_usd": N} — image_base64 is a PNG, base64-encoded.

If this assistant's models was left unset at registration, every currently-configured image provider/model on the server is tried in turn on failure, same fallback posture as chat assistants. 402 if the owning account is out of AI credit and not on an unlimited grant. 400 if this assistant's kind isn't "image".

curl "https://your-domain/api/v1/projects/1/functions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns { base_url, functions: [...] }. Each function has name, description, method, path, auth, enabled, live_version, published_at, has_unpublished_changes, url (code bodies are left out of the list).

curl -X POST "https://your-domain/api/v1/projects/1/functions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cancel-order",
    "method": "POST",
    "path": "/orders/:id/cancel",
    "auth": "user",
    "description": "Customer cancels their own pending order",
    "code": "...",
    "publish": false
  }'

Returns the function including draft_code, live_code and syntax_error (null or { message, line, column }). 409 if the name or route is taken.

curl "https://your-domain/api/v1/projects/1/functions/cancel-order" \
  -H "Authorization: Bearer YOUR_TOKEN"

Includes draft_code, live_code, syntax_error for the draft, and versions ([{ version, size, created_at }], newest first).

curl -X PATCH "https://your-domain/api/v1/projects/1/functions/cancel-order" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "...", "publish": true }'

Any of code (updates the draft only), method, path, auth, description, enabled, publish. Routing fields apply immediately. A draft with a syntax error is still saved — check syntax_error in the response.

curl -X DELETE "https://your-domain/api/v1/projects/1/functions/cancel-order" \
  -H "Authorization: Bearer YOUR_TOKEN"

Its URL stops working immediately; versions and logs are deleted with it.

curl -X POST "https://your-domain/api/v1/projects/1/functions/cancel-order/publish" \
  -H "Authorization: Bearer YOUR_TOKEN"

Copies the draft to live as the next version number. 422 with syntax_error if the draft doesn't parse — live keeps serving the previous version.

curl -X POST "https://your-domain/api/v1/projects/1/functions/cancel-order/rollback" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "version": 3 }'

Points live at a previously published version. The draft is not changed. To bring an old version back into the editor, fetch its code (below) and PATCH it as the draft.

curl "https://your-domain/api/v1/projects/1/functions/cancel-order/versions/3" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns { version, code }.

curl -X POST "https://your-domain/api/v1/projects/1/functions/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "return {" }'

Always 200: { "ok": false, "error": { "message": "…", "line": 1, "column": 9 } } or { "ok": true, "error": null }.

curl -X POST "https://your-domain/api/v1/projects/1/functions/cancel-order/test" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "draft",
    "method": "POST",
    "path": "/orders/42/cancel",
    "query": {},
    "headers": {},
    "body": {},
    "as": { "user_id": 7, "table": "users" }
  }'

Always answers 200 with the function's own response inside: { status, headers, body, error, logs, ops, duration_ms, log_id }. Unlike live calls, error contains the full error message and line.

curl "https://your-domain/api/v1/projects/1/functions/cancel-order/logs?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Newest first: { logs: [{ id, stage, version, method, path, status, duration_ms, ops, error, logs: [{ level, message, line }], created_at }] }. id is the request_id a failed call returned. Page with ?before=<id>. Request bodies and headers are never stored. The most recent 1,000 invocations per project are kept. GET /api/v1/projects/:id/function-logs gives the same list across all functions (with function_name), and DELETE …/functions/:name/logs clears one function's logs.

curl "https://your-domain/api/v1/projects/1/function-env" \
  -H "Authorization: Bearer YOUR_TOKEN"

{ env: [{ name, value, secret, updated_at }] }. value is null for secrets.

curl -X PUT "https://your-domain/api/v1/projects/1/function-env/PAYSTACK_SECRET" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk_live_...", "secret": true }'

Names start with a letter or _ and contain letters, digits and _ (max 64). Values up to 10,000 bytes.

curl "https://your-domain/api/v1/auth/tokens" \
  -H "Authorization: Bearer YOUR_TOKEN"

Token values are never returned after creation. Only id, name, project_id (null for account-wide), created_at, and last_used_at are shown.

## Account-wide (default)
curl -X POST "https://your-domain/api/v1/auth/tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI deploy"}'

## Scoped to one project — e.g. handing this to an external AI builder
curl -X POST "https://your-domain/api/v1/auth/tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "AI builder — project 12", "project_id": 12}'

Returns {"token": "sb_pat_...", "project_id": 12 | null}. The raw token value is shown only once — store it immediately.