API Reference

Signs in and sets the deploro_session cookie. Use credentials: "include" from a browser.

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

Body: { banned, reason?, expiresAt? }. auth-guard checks banned/banExpires on every request, so a ban blocks the next request immediately.

curl -X PATCH https://api.deploro.com/api/auth/users/USER_ID/ban \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"banned":true,"reason":"abuse","days":7}'

Body fields (Zod-validated): name (1-50 chars), slug (2-30 chars, lowercase alphanumeric + hyphens), optional git_repo_url, git_branch.

curl -X POST https://api.deploro.com/api/projects \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","slug":"my-app"}'

Provisions the project's isolated Postgres database, idempotently. Until this runs, every /api/db/* route for the project returns 409 {"code":"NO_DATABASE"}.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/database \
  -H "Authorization: Bearer deploro_pat_..."

Body: { sql: string, params?: (string | number | boolean | null)[] }. One read-only statement starting with SELECT, WITH, VALUES or TABLE; it runs in a read-only transaction, so writes and DDL fail. Use migrations for schema changes.

Pass values as params and refer to them as $1, $2, and so on, rather than writing them into the SQL. Quoted values and comments never trip the check, so a search for '%do%' works. Functions that reach other sessions or run SQL held in a string (pg_terminate_backend, pg_stat_activity, set_config, query_to_xml, advisory locks) and U&"..." identifiers are refused. A rejected statement returns 400 with the reason in detail.

curl -X POST https://api.deploro.com/api/db/query \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "x-project-id: <project id>" \
  -H "Content-Type: application/json" \
  -d '{"sql":"select id, full_name from student where full_name ilike $1 limit 10","params":["%do%"]}'

Body: { data: { ...columns } }.

curl -X POST https://api.deploro.com/api/db/rows/todos \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"data":{"title":"Ship the docs site","done":false}}'

Unauthenticated inline read of one object, granted one of three ways, checked in order: a valid ?sig=&exp= signed-URL token (bypasses everything else); the key's first path segment matching a registered bucket, governed by that bucket's own public flag; or, failing both, the project-wide public_storage_enabled flag. Anything else answers 404, indistinguishable from a project that does not exist. Supports HEAD, ETag/If-None-Match revalidation, and Range requests. There is no public listing form; objects are reachable by exact key only.

# turn on the project-wide root flag (project admin)
curl -X PATCH https://api.deploro.com/api/projects/PROJECT_ID   -H "Authorization: Bearer $DEPLORO_TOKEN"   -H "Content-Type: application/json"   -d '{"public_storage_enabled": true}'

# then anyone can read a stored object inline
<img src="https://api.deploro.com/files/my-project/vehicle-images/4/11.png">

HMAC-signed and stateless. There's no token table, so nothing can be revoked early short of rotating the platform's own signing secret. Works on a private root file or a private bucket's file alike.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/storage/signed-url \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"key": "invoices/2026-03.pdf", "expiresIn": 3600}'
# => { "url": "https://api.deploro.com/files/my-project/invoices/2026-03.pdf?exp=...&sig=...", "expiresAt": "..." }

Body: { hostname: "app.example.com" }. Returns the CNAME (sites.deploro.online) and TXT verification record to create at your DNS provider, then poll /status or call /verify once they propagate.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/domains \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.example.com"}'

Body: { from, to, cc?, bcc?, reply_to?, from_name?, subject, html?, text? }. from must be one of the project's sender addresses on a verified domain. to, cc and bcc take one address or a list, 50 recipients per message in total. Give html, text, or both (both is better for deliverability). Other fields, including custom headers, are refused. Returns { delivered, queued, permanent_bounces }.

Call it from your server with a personal access token (write scope, limited to this project) kept in an environment variable. Never from browser code: anyone holding the token could send mail as your domain.

Limits: each project can send to 100 recipients a day by default (429 DAILY_LIMIT). App mail also shares a platform-wide daily quota that is kept partly free for sign-in emails (429 PLATFORM_QUOTA). An address that isn't a verified sender returns 403 SENDER_NOT_ALLOWED.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/email/send   -H "Authorization: Bearer deploro_pat_..."   -H "Content-Type: application/json"   -d '{"from":"hello@example.com","to":"customer@example.org","subject":"Your order shipped","text":"It is on the way.","html":"<p>It is on the way.</p>"}'

Headers: X-Deploro-Server-Token (required: a personal access token with write scope, limited to this project) and X-Deploro-Client-IP (optional: the visitor's IP, passed to Cloudflare). Body: { token, expected_action?, sitekey? }, where token is the form's cf-turnstile-response field. sitekey is only needed if the project has more than one widget.

Three outcomes, which your app should handle differently:

• Passed: 200 { success: true, hostname, action, challenge_ts }.
• Failed (the visitor failed, or the token is missing, expired, already used, from a hostname that isn't the project's, or for a different action): 200 { success: false, error_codes: [...] }. Ask the visitor to try again.
• Couldn't check (Cloudflare or Deploro unreachable, or the widget isn't set up): 503 { success: false, code: "TURNSTILE_UNAVAILABLE" | "TURNSTILE_NOT_CONFIGURED", error }. Tell the visitor the form is unavailable rather than that they failed, and don't accept the submission.

A token can be checked once and expires after 5 minutes. Test widgets add test: true to every answer and skip the hostname check. Call this from your server, never from the browser. Through the DEPLORO_API binding, call env.DEPLORO_API.fetch("https://api.deploro.com/turnstile/SLUG/verify", ...).

The widget itself can't go through Deploro: the page has to load https://challenges.cloudflare.com/turnstile/v0/api.js straight from Cloudflare (it can't be proxied or cached), and the challenge runs between the visitor's browser and Cloudflare. If your site sends a Content-Security-Policy, allow https://challenges.cloudflare.com in script-src and frame-src. On a Worker deploy, Deploro sets TURNSTILE_SITE_KEY as a plain variable (and in the build environment, with NEXT_PUBLIC_TURNSTILE_SITE_KEY) unless your config sets it.

curl -X POST https://api.deploro.com/turnstile/my-project/verify   -H "X-Deploro-Server-Token: deploro_pat_..."   -H "X-Deploro-Client-IP: 203.0.113.9"   -H "Content-Type: application/json"   -d '{"token":"0.abc...","expected_action":"register"}'

Body: { url, events: string[], secret? }. url must be a public HTTP(S) URL with no embedded credentials. secret, if given, is 16-256 chars and used to HMAC-sign deliveries.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/webhooks \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/deploro","events":["row.insert","deploy.success"]}'

The connection string is returned once, in the response body. Store it immediately.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/vps/database \
  -H "Authorization: Bearer deploro_pat_..."

Body: { cidr, label? }, for example 203.0.113.4 or 203.0.113.0/24.

curl -X POST https://api.deploro.com/api/projects/PROJECT_ID/vps/allowlist \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"cidr":"203.0.113.4","label":"my laptop"}'

Silently no-ops for disposable email domains. Requires the email provider to be enabled for the project.

The email uses the project's otp template (Auth page, Email templates), with the variables {{code}}, {{project_name}} and {{copy_code_url}}. Email can't copy anything to the clipboard by itself, so a "Copy code" button links to {{copy_code_url}}: a Deploro page that shows the code with a working Copy button. In the template editor, set a button's When clicked to Copy the code to do this, or to Open a link for any other address. Gmail and iPhones also offer their own copy control on the code itself.

curl -X POST https://api.deploro.com/auth/my-app/email/request-otp \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

Requires the email provider, and works only for users who have already confirmed their email (via /email/signup or an admin invite). At most one link per user per minute. The email uses the project's magic_link template.

curl -X POST https://api.deploro.com/auth/my-app/email/request-magic-link \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","redirect_to":"/dashboard"}'

Two-factor sign-in with an authenticator app (Google Authenticator, 1Password, Authy and others). Every sign-in method first gives a one-factor session (aal1). For a user who has two-factor on, the sign-in response and GET /auth/:slug/session say "mfa_required": true: ask for the 6-digit code and send it here with the factor's id (from GET /auth/:slug/mfa/factors). Until then /data/:slug answers 401 with "code":"MFA_REQUIRED".

No screens of your own? Send the browser to /auth/:slug/mfa/setup?return_to=/settings to turn it on, and to /auth/:slug/mfa/challenge?return_to=/dashboard when mfa_required is true. These Deploro-hosted pages use the session cookie and return to your Site URL. Magic-link and social sign-ins already go to the challenge page on their own.

Your own screens: POST /mfa/enroll, show totp.qr_code as an image (and totp.secret for people who can't scan), then send the first code to /mfa/verify. That response has the user's 10 recovery codes; show them once and ask the user to keep them. A user who already has two-factor on must complete it in the current session before adding an app, removing one or replacing recovery codes.

Completing the step replaces the session token. Cookie sessions get the new cookie; callers using Authorization: Bearer get it back as session_token and must use it from then on. Each code works once, and 10 wrong codes in 15 minutes lock the step for that user. Signing in with a recovery code emails the user, so they notice if it wasn't them.

curl -X POST https://api.deploro.com/auth/my-app/mfa/verify \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"factor_id":"FACTOR_ID","code":"123456"}'

Body: { client_id, client_secret, enabled, extra_config? }. Apple additionally needs extra_config.team_id and extra_config.key_id, with the .p8 private key contents as client_secret.

curl -X PUT https://api.deploro.com/api/projects/PROJECT_ID/auth/providers/google \
  -H "Authorization: Bearer deploro_pat_..." \
  -H "Content-Type: application/json" \
  -d '{"client_id":"...","client_secret":"...","enabled":true}'