Create projects through the API: idempotency, templates, labels, expiry (TTL), regions, bulk creation, capacity, pause, restore, delete, key rotation and Auth settings.
#Create
| Field | Meaning |
|---|---|
name | Required, up to 64 characters |
region | Optional; default: the closest region with room |
organization_id | Optional for personal credentials (default: your own organization); organization tokens always use theirs |
labels | Up to 20 key: value pairs (keys: lowercase, digits, _ . : / -) |
limits | Per-project caps, see Limits per customer |
ttl_seconds or expires_at | Delete automatically (5 minutes to 365 days) |
template | One of sql, migrations ([{ version, name, sql }]) or from_project (an existing project of the same organization: its migrations, or its schema if it has none), plus an optional seed. With from_project, data copies its rows too: masked or full (see below) |
Send an Idempotency-Key header (up to 200 characters, kept 24 hours): the same key with the same body returns the first project (idempotent_replay: true); with a different body it fails with 422.
Templates are applied as recorded migrations once the project is active, then the seed runs; template_status goes pending → ready (or failed with template_error). project.ready is sent when the template is ready.
#Copy data from the template project
{ "name": "acme-staging", "template": { "from_project": "<ref>", "data": "masked" } }data: "masked" | Every row, with personal data (e-mails, names, phone numbers, addresses, IPs, secrets) replaced by realistic fake values, the same way as preview branches with data; the source project's masking rules apply. Auth users come along masked, without their passwords (include_auth: false leaves them out). Needs read access to the source. |
data: "full" | An exact copy. Auth users only with include_auth: true (then with their password hashes). Needs owner or administrator rights on the source; tokens need projects:write. |
tables | Only these tables, e.g. ["public.plans", "public.countries"] or ["catalog.*"]; the others stay empty. |
The rows are copied after the schema and before the seed; rows that migrations inserted into copied tables are replaced. Sequences continue after the copied rows. Storage files and Edge Functions are not copied. The source must be an active main project (not a branch); the size counts against the plan's data-copy limit (Limits: data copied into a preview branch or a new project). template_data on the new project tells how many tables and rows were copied. In the dashboard: Settings › General › Duplicate project; through MCP: create_project with from_project and copy_data.
#Bulk and capacity
Create many projects in parallel: each call returns in about a second; projects become active within seconds to a minute depending on how many are queued per server. When every server is full the API answers 503 with code: "capacity" and nothing is half-created; retry later (we are alerted and add capacity). New accounts have a daily creation limit against abuse; enterprise accounts do not. Talk to us before provisioning thousands of projects.
#Change, pause, restore, delete
| Call | Does |
|---|---|
PATCH /projects/<ref> | { name?, labels? (null removes a key), expires_at? | ttl_seconds? (null clears) } |
POST /projects/<ref>/pause | Services stop, the API answers 503 project_paused, data is kept |
POST /projects/<ref>/restore | Back as it was (URL, keys, data) |
DELETE /projects/<ref> | Deletes the database, files, functions and preview branches. Not reversible. |
POST /projects/<ref>/api-keys/rotate | { grace_seconds } (default 86400): new anon and service_role keys; the old ones work until the grace ends, then are refused in every header |
GET / PATCH /projects/<ref>/config/auth | Site URL, redirect URLs, providers, SMTP, e-mail templates, sessions, MFA, rate limits (same fields as Studio › Auth settings) |
#List
GET /projects?label=customer_id:cus_123&status=active&limit=100; the next page is in the X-Next-Cursor header (&cursor=…).