Docs · Reference

MCP server

Let an AI tool work on the platform directly. The 494 tools are read from the MCP server (mcp.ts) and become this page. This list is generated from the server code, so new features appear here as soon as they exist.

Connecting

MCP address

https://end.blackall.ai/mcp?lang=en

JSON-RPC over POST to one address. ?lang=en, ?lang=ko or ?lang=ja picks the language of the tool descriptions and errors; without it Accept-Language is followed, and without that it is English.

Address options

Added after the address, they narrow what this connection can see and do. The server enforces them: a tool left out of the list is refused even when called by name. Fewer tools means less for the AI to sort through, and a connection that can only read one project has nothing to lose to a mistake. whoami says which are in effect.

Option	Description
`project_ref`	Holds the connection to one project. A tool called without `ref` uses this project, and any other ref is refused. `list_projects` shows this project only, and tools that reach other projects or the whole organisation (new projects, the team, notification channels, the audit log, billing) are left out.
`read_only`	With `true`, only tools that change nothing are listed, and the whole connection acts as a read token. A tool that changes something is refused even when called by name.
`features`	Only the groups of tools named, separated by commas. `whoami` and `list_projects` are always there. An unknown group is refused with the list of valid ones.
`lang`	`en`, `ko` or `ja`: the language of the tool descriptions, the guidance and the errors.

https://end.blackall.ai/mcp?lang=en&project_ref=<ref>&read_only=true&features=database,deploy

For a Claude or ChatGPT connector, enter the address with its options as it is. The consent screen also lets you pick one project and turn off write access, and that choice is kept with the connection.

Tool groups

Group	Tools	Name
`account`	106	`whoami` `list_projects` `list_regions` `list_server_sizes` `request_region` `create_project` `rename_project` `list_transfer_targets` `transfer_project` `pause_project` `resume_project` `delete_project` `retry_provisioning` `get_project_archive` `restore_project_archive` `create_archive_download_url` `get_project_keys` `list_api_keys` `create_api_key` `revoke_api_key` `list_team` `invite_member` `cancel_invitation` `set_member_role` `remove_member` `set_mfa_required` `list_channels` `create_channel` `test_channel` `set_channel_enabled` `remove_channel` `get_audit_log` `import_sources` `start_import` `get_import` `list_shared_env_vars` `create_shared_env_var` `update_shared_env_var` `remove_shared_env_var` `list_access_groups` `create_access_group` `update_access_group` `remove_access_group` `get_member_access` `set_member_access` `list_audit_drains` `create_audit_drain` `set_audit_drain_enabled` `test_audit_drain` `remove_audit_drain` `list_org_webhooks` `create_org_webhook` `set_org_webhook_enabled` `test_org_webhook` `list_org_webhook_deliveries` `retry_org_webhook_delivery` `remove_org_webhook` `get_committer_settings` `set_committer_policy` `trust_committer` `remove_trusted_committer` `answer_preview_approval` `get_org_sso` `set_org_sso` `remove_org_sso` `add_org_sso_domain` `verify_org_sso_domain` `remove_org_sso_domain` `get_org_policies` `set_org_policies` `set_preview_suffix` `verify_preview_suffix` `remove_preview_suffix` `list_platform_settings` `set_platform_setting` `clear_platform_setting` `list_platform_servers` `get_platform_cpu_history` `request_platform_server_change` `get_platform_server_request` `cancel_platform_server_request` `list_github_variables` `set_github_variable` `delete_github_variable` `list_platform_operators` `add_platform_operator` `remove_platform_operator` `list_platform_runs` `cancel_platform_run` `rerun_platform_run` `list_platform_checks` `set_merge_when_green` `get_ci_machines` `restart_ci_machine` `renew_ci_registration` `set_up_build_cache_bucket` `get_platform_overview` `find_customer` `list_parking_hosts` `list_project_placements` `get_platform_server_pricing` `set_platform_server_pricing` `set_platform_server_size` `start_support_session` `end_support_session` `list_support_sessions`
`database`	59	`list_tables` `list_policies` `query_sql` `run_sql` `read_rows` `export_table_csv` `import_table_csv` `get_database_connection` `reset_database_password` `list_backups` `create_backup` `restore_backup` `list_db_webhooks` `create_db_webhook` `set_db_webhook_enabled` `list_db_webhook_deliveries` `remove_db_webhook` `list_schemas` `set_exposed_schemas` `get_data_api_settings` `set_data_api_settings` `get_database_settings` `set_database_settings` `list_extensions` `enable_extension` `disable_extension` `list_vault_secrets` `create_vault_secret` `copy_vault_secrets_from_project` `set_vault_project_keys` `update_vault_secret` `delete_vault_secret` `get_network_restrictions` `update_network_restrictions` `list_migrations` `apply_migrations` `remove_migration_record` `dump_schema` `generate_typescript_types` `get_database_move` `move_to_dedicated_database` `get_dedicated_disk` `request_dedicated_disk` `shrink_dedicated_disk` `get_server` `request_server` `resize_server` `set_standby` `move_server` `release_server` `set_restore_days` `list_mysql_databases` `create_mysql_database` `bind_mysql_database` `delete_mysql_database` `get_mysql_connection` `create_mysql_backup` `list_mysql_backups` `restore_mysql_backup`
`auth`	57	`list_users` `add_user` `import_users` `update_user` `generate_link` `remove_user` `list_auth_providers` `set_auth_provider` `set_auth_provider_enabled` `remove_auth_provider` `get_smtp_settings` `set_smtp_settings` `test_smtp_settings` `remove_smtp_settings` `get_email_templates` `set_email_template` `preview_email_template` `remove_email_template` `get_sms_settings` `set_sms_settings` `remove_sms_settings` `list_sso_providers` `add_sso_provider` `update_sso_provider` `remove_sso_provider` `get_auth_config` `update_auth_config` `list_custom_providers` `create_custom_provider` `update_custom_provider` `set_custom_provider_enabled` `remove_custom_provider` `list_third_party_auth` `add_third_party_auth` `remove_third_party_auth` `list_redirect_urls` `add_redirect_url` `remove_redirect_url` `set_anonymous_sign_in` `copy_auth_from_import` `copy_auth_from_project` `copy_users_from_project` `copy_schema_from_project` `copy_data_from_project` `get_jwt_signing` `set_jwt_signing` `rotate_signing_key` `retire_signing_key` `get_passkey_settings` `set_passkey_settings` `list_user_factors` `remove_user_factors` `remove_user_passkey` `list_oauth_apps` `create_oauth_app` `reset_oauth_app_secret` `remove_oauth_app`
`storage`	41	`list_s3_keys` `create_s3_key` `revoke_s3_key` `list_buckets` `create_bucket` `update_bucket` `empty_bucket` `delete_bucket` `list_objects` `upload_object` `download_object` `delete_object` `create_upload_url` `create_signed_url` `copy_storage_from_import` `copy_storage_from_project` `list_kv_keys` `get_kv` `set_kv` `delete_kv` `get_edge_config` `set_edge_config` `get_edge_config_history` `list_edge_config_tokens` `create_edge_config_token` `connect_edge_config_token` `disconnect_edge_config_token` `revoke_edge_config_token` `get_storage_settings` `set_storage_settings` `set_s3_enabled` `set_bucket_versioning` `list_object_versions` `restore_object_version` `remove_object_version` `list_bucket_connections` `connect_bucket` `disconnect_bucket` `list_storage_policies` `create_storage_policy` `remove_storage_policy`
`functions`	25	`list_functions` `get_function` `deploy_function` `set_function_public` `set_function_limits` `remove_function` `list_function_secrets` `set_function_secrets` `copy_function_secrets` `copy_functions_from_project` `get_project_forward` `set_project_forward` `get_project_write_lock` `set_project_write_lock` `compare_projects_data` `delete_function_secret` `set_function_egress` `list_jobs` `save_job` `copy_jobs_from_project` `set_job_enabled` `run_job` `list_job_runs` `remove_job` `set_job_retention`
`deploy`	106	`list_deployments` `get_deployment` `redeploy` `promote_deployment` `rollback_deployment` `deploy_commit` `deploy_files` `deploy_source` `create_source_upload_url` `list_deploy_hooks` `create_deploy_hook` `remove_deploy_hook` `list_apps` `update_app` `delete_app` `get_preview_protection` `set_preview_protection` `get_branch_previews` `set_branch_previews` `list_env_vars` `set_env_vars` `remove_env_var` `list_git_access` `set_repo_token` `remove_repo_token` `add_repository` `list_importable_repositories` `import_repository` `disconnect_repository` `set_checks_on_server` `link_github_app` `unlink_github_app` `get_server_memory` `set_server_memory` `get_concurrent_builds` `set_concurrent_builds` `get_rolling_releases` `set_rolling_releases` `advance_rolling_release` `promote_rolling_release` `abort_rolling_release` `get_middleware` `set_middleware` `list_flags` `evaluate_flag` `set_flag_enabled` `get_remote_cache` `clear_remote_cache` `list_volumes` `create_volume` `resize_volume` `delete_volume` `create_volume_backup` `restore_volume_backup` `get_deployment_retention` `set_deployment_retention` `list_deleted_deployments` `delete_deployment` `restore_deployment` `set_protection_scope` `create_bypass_secret` `revoke_bypass_secret` `create_share_link` `revoke_share_link` `list_environments` `create_environment` `update_environment` `remove_environment` `set_domain_environment` `get_flag` `create_flag` `update_flag` `set_flag_environment` `add_flag_rule` `move_flag_rule` `remove_flag_rule` `set_flag_archived` `list_flag_segments` `create_flag_segment` `update_flag_segment` `remove_flag_segment` `list_flag_sdk_keys` `create_flag_sdk_key` `revoke_flag_sdk_key` `list_project_webhooks` `create_project_webhook` `set_project_webhook_enabled` `test_project_webhook` `list_project_webhook_deliveries` `retry_project_webhook_delivery` `remove_project_webhook` `list_remote_cache_tokens` `create_remote_cache_token` `revoke_remote_cache_token` `get_build_settings` `set_build_dev_settings` `set_ignored_build_step` `set_production_first` `set_git_checks` `set_expose_system_env` `set_directory_listing` `get_deployment_security` `set_deployment_security` `get_routing_rules` `save_routing_rules` `activate_routing_rules`
`domains`	28	`list_domains` `add_domain` `remove_domain` `set_domain_redirect` `move_domain` `get_edge` `set_edge` `purge_edge_cache` `get_network` `set_static_outbound_ip` `upload_certificate` `remove_certificate` `get_firewall` `save_firewall_rule` `move_firewall_rule` `set_firewall_rule_enabled` `remove_firewall_rule` `set_firewall_managed` `publish_firewall` `reset_firewall_draft` `restore_firewall_version` `set_attack_mode` `get_bulk_redirects` `upload_bulk_redirects` `activate_bulk_redirects` `get_skew_protection` `set_skew_protection` `purge_edge_cache_item`
`branching`	6	`list_branches` `create_branch` `merge_branch` `reset_branch` `delete_branch` `set_branching`
`logs`	21	`get_logs` `get_advisors` `list_log_drains` `create_log_drain` `set_log_drain_enabled` `remove_log_drain` `get_metrics` `get_analytics` `get_speed_insights` `set_insights` `get_analytics_breakdown` `set_analytics_previews` `export_analytics` `list_analytics_reports` `get_analytics_report` `save_analytics_report` `remove_analytics_report` `list_alert_rules` `create_alert_rule` `set_alert_rule_enabled` `remove_alert_rule`
`billing`	6	`usage` `get_billing` `get_plan` `get_spend_controls` `set_spend_cap` `set_spend_limit`
`ai`	15	`get_ai_gateway` `set_ai_gateway` `add_ai_provider` `set_ai_provider_enabled` `remove_ai_provider` `get_ai_gateway_logs` `set_ai_budgets` `list_ai_gateway_keys` `create_ai_gateway_key` `set_ai_gateway_key_budgets` `set_ai_gateway_key_limits` `set_ai_model_aliases` `set_ai_gateway_hooks` `revoke_ai_gateway_key` `get_ai_spend`
`realtime`	7	`list_realtime_tables` `set_realtime` `get_realtime_settings` `set_realtime_settings` `list_realtime_policies` `create_realtime_messages_table` `add_realtime_policy`
`queues`	8	`list_queues` `create_queue` `delete_queue` `purge_queue` `send_queue_message` `peek_queue` `set_queues_api` `get_queue_metrics`
`gpu`	9	`list_gpu` `create_gpu_job` `get_gpu_job` `cancel_gpu_job` `create_gpu_server` `stop_gpu_server` `delete_gpu_server` `create_gpu_volume` `delete_gpu_volume`

Claude and ChatGPT

In claude.ai, Claude Desktop and ChatGPT, add the MCP address as a custom connector. A sign-in page opens, and once you allow it they are connected. No token is needed. Untick write access on the consent screen for a read-only connection.

Claude Code

Add it with the command below; the browser opens to sign in the first time it is used.

claude mcp add --transport http oneend "https://end.blackall.ai/mcp?lang=en"

Connecting with a token

Where no browser can open (CI, a server), pass a bwk_… token made under Account, API and MCP tokens as a header. Other MCP clients take a configuration of the same shape.

claude mcp add --transport http oneend "https://end.blackall.ai/mcp?lang=en" \
  --header "Authorization: Bearer bwk_…"

{
  "mcpServers": {
    "oneend": {
      "type": "http",
      "url": "https://end.blackall.ai/mcp?lang=en",
      "headers": {
        "Authorization": "Bearer bwk_…"
      }
    }
  }
}

OAuth (ADR 0016)

The console is the authorization server. An initialize or tools/call without a token is answered 401 with a WWW-Authenticate header, which the client follows to the addresses below. Both dynamic client registration (RFC 7591) and client metadata documents are accepted, and every authorization needs PKCE S256. Access tokens last an hour; a refresh token can be used once.

Address	Purpose
`https://end.blackall.ai/.well-known/oauth-protected-resource`	Protected resource metadata
`https://end.blackall.ai/.well-known/oauth-authorization-server`	Authorization server metadata
`https://end.blackall.ai/oauth/register`	Client registration (RFC 7591)
`https://end.blackall.ai/oauth/authorize`	Sign-in and consent
`https://end.blackall.ai/oauth/token`	Exchange a code or refresh token for an access token
`https://end.blackall.ai/oauth/revoke`	Revoke a token

Protocol

MCP 2025-06-18 over stateless HTTP: one response per request, no stream (GET answers 405). tools/list, resources/* and prompts/* can be read without a token; initialize and tools/call need one. A tool that fails returns a result with isError: true, not a protocol error.

Supported methods

tools/call
initialize
ping
tools/list
resources/list
resources/read
prompts/list
prompts/get

curl -X POST "https://end.blackall.ai/mcp?lang=en" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer bwk_…" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_projects","arguments":{}}}'

Documents and procedures

The server hands out this site’s documents as MCP resources and the step-by-step guides as prompts.

Resource	Name	Description
`blackwall://start`	From start to finish	The order to use the tools in. Read this first when you are not sure what to call.
`blackwall://switch`	Moving from Supabase or Vercel	The order to move an app built on Supabase or Vercel: database, supabase-js, sign-in, functions, deploys. What runs as it is and what to check.
`blackwall://access-rules`	Access rules	Why a new table looks empty. This is where things go wrong most often on this platform, so read it first.
`blackwall://keys`	Three kinds of key	What the publishable key, secret key and access token are for, and which one must never be in a browser.
`blackwall://data-api`	Reading and writing data	Query syntax, operators, partial text search in Korean.
`blackwall://extensions`	Database extensions	How to turn extensions such as pgvector (embedding search) and PostGIS (maps) on and off, which ones you can turn on, and how they behave on a shared database.
`blackwall://branches`	Database branches	A preview database per git branch: making one, wiring it to preview deployments, merging, resetting, deleting, billing.
`blackwall://database-features`	Queues · Vault · GraphQL · network restrictions	Queues like pgmq, encrypted secrets inside the database (Vault), /graphql/v1, and address limits and TLS for direct connections.
`blackwall://auth`	Adding sign-in	Email and password, and social sign-in. Where the token comes back.
`blackwall://realtime`	Realtime subscriptions	That it must be turned on per table, and that access rules apply to realtime too.
`blackwall://storage`	Files	Buckets and uploads, the difference between public and private, S3 access, moving files from Supabase, and resumable (TUS) uploads.
`blackwall://env`	Environment variables	How to give a deployed app values such as API keys, when changes take effect, and names you cannot use.
`blackwall://logs`	Logs	How to see what happened when your app throws an error, and what each source records.
`blackwall://deploy`	Deployments	Connecting a repository, the production branch, and the build folder in a monorepo.
`blackwall://functions`	Functions, scheduled jobs and database webhooks	What function code looks like, what it can and cannot do (outbound requests must be turned on), how to call it, cron schedules (UTC), and webhooks that tell outside services about table changes.
`blackwall://domains`	Domains and the edge	Connecting, verifying and redirecting domains, domains for the API, the firewall and request limits, the edge cache.
`blackwall://edge`	Edge: analytics, edge config, KV, AI gateway, rolling releases, middleware	What runs in front of the site: web analytics and speed measurement with no personal data, values and feature flags that change without a deploy, a key-value store, an OpenAI-compatible AI gateway, sending a new deployment to some visitors first, and middleware.ts.
`blackwall://previews`	Preview protection	Who can open preview addresses, and how automation gets through.
`blackwall://limits`	Limits and pricing	That the free plan holds one person's GitHub site and refuses past its limits, and the paid plan bills.
`blackwall://organisation`	Organisation: team, notifications, billing, audit log	Inviting members and their roles, notification channels, bills, the audit log, and the paths to do the same over HTTP (/api/v1).
`blackwall://migrations`	Migrations and types	Applying and recording schema changes as versioned SQL, downloading the schema as SQL, and making TypeScript types for supabase-js.
`blackwall://cli`	The command line tool (oneend)	The oneend commands for terminals and CI: signing in, linking a project, environment variables, deployments, functions, migrations, types.

Prompt	Name	Description
`new-table`	Create a table and make it actually visible	Creates a table, sets up its access rules, and checks that the publishable key can read it.
`add-login`	Adding sign-in	Adds email sign-in and makes each user see only their own data.
`add-social-login`	Adding social sign-in	Lets people sign in with accounts such as Google or Kakao. Sets the callback address and the return address together.
`add-uploads`	Adding file uploads	Creates a bucket and adds uploading and downloading.
`cli`	Managing the schema and deployments with the command line tool	Signs in with the oneend CLI, links a folder to a project, then handles migrations, types and deployments.
`check-costs`	See what this month will cost	Reads usage and checks whether anything is close to a free limit.

Tools

Clients use the annotations to decide what to ask before running. Every tool that is not read-only is marked destructive except the few that only add. The console’s assistant asks for confirmation by the same rule.

Account and regions

Name	Description
`whoami`	My account
`list_regions`	Regions
`list_server_sizes`	Server sizes and prices
`request_region`	Request a region
`import_sources`	Import sources
`start_import`	Start an import
`get_import`	Import progress

`whoami` My account

Read-only

Tells you whose token this is and what it may do. operator says whether the operator tools are open to it (active) and, when not, this account's reasons (refused: not_listed, token_bound, no_second_factor). Call it first when you are not sure where to start.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/me`

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`list_regions` Regions

Read-only

Returns the regions. You can create a project now only where can_create is true; where it is false the region is being prepared and is listed, but cannot be chosen yet. A region is chosen once when a project is created and cannot be changed later, so check this before create_project.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/regions`

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`list_server_sizes` Server sizes and prices

Read-only

Each server size (memory) with its Google machine, CPUs and monthly price per region (monthly_minor). With no currency, the organisation's billing currency. KRW is in won with VAT included; USD is in cents with tax added at checkout. A size whose included_in is pro is included in the Pro plan. A region whose region_status is planned is coming soon and cannot be chosen. listed false means the sizes are not on sale yet and sizes is empty.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/server-sizes`

Input

Name	Type	Required	Description
`region`	`string`	No	One region's code (code in list_regions) to see only that region. Empty means every region.
`currency`	`string`, KRW \| USD	No	KRW or USD. Empty means the organisation's billing currency.

JSON Schema

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "description": "One region's code (code in list_regions) to see only that region. Empty means every region."
    },
    "currency": {
      "type": "string",
      "enum": [
        "KRW",
        "USD"
      ],
      "description": "KRW or USD. Empty means the organisation's billing currency."
    }
  },
  "additionalProperties": false
}

`request_region` Request a region

Only adds

Records that you need a region that is not open yet (one where can_create is false). A person from our team will contact you. No date is promised. A region that is already open is not something to request: create the project there with create_project.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	POST `/regions/requests`

Input

Name	Type	Required	Description
`region`	`string`	Yes	A code that list_regions reported with can_create=false.
`note`	`string`	No	What you plan to run there, and why it has to be that region. Optional, but it is the first thing the person who contacts you reads.

JSON Schema

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "description": "A code that list_regions reported with can_create=false."
    },
    "note": {
      "type": "string",
      "description": "What you plan to run there, and why it has to be that region. Optional, but it is the first thing the person who contacts you reads."
    }
  },
  "required": [
    "region"
  ],
  "additionalProperties": false
}

`import_sources` Import sources

Read-only Reaches outside

The same as Import from another server in the console. For each source account connected to this organisation (Supabase, Vercel, PostgreSQL), its projects, and the imports so far. Accounts are connected in the console (connect_url), so a token is never pasted into a chat.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/imports/sources`

Input

Name	Type	Required	Description
`org`	`string`	No	The organisation id or name. Empty means the first one this token reaches.

JSON Schema

{
  "type": "object",
  "properties": {
    "org": {
      "type": "string",
      "description": "The organisation id or name. Empty means the first one this token reaches."
    }
  },
  "additionalProperties": false
}

`start_import` Start an import

Only adds Reaches outside

The same as [Start import] in the console. Starts an import split in the console (import), or a new one from import_sources' connection and project, split one new project per group. New projects are made; the source is never changed. A Supabase source needs its session pooler connection string in address, used for this run only and then deleted. Starting a stopped import again passes over finished destinations and moves only what changed. Owners, admins and developers only.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	POST `/imports`

Input

Name	Type	Required	Description
`org`	`string`	No	The organisation id or name. Empty means the first one this token reaches.
`import`	`string`	No	The import id (imports from import_sources, or the id in the console address).
`connection`	`string`	No	The source account (connection from import_sources), with project when there is no import.
`project`	`string`	No	The source project (projects[].id from import_sources).
`address`	`string`	No	A Supabase source's session pooler connection string (postgres.<ref>, port 5432). Empty for other sources.

JSON Schema

{
  "type": "object",
  "properties": {
    "org": {
      "type": "string",
      "description": "The organisation id or name. Empty means the first one this token reaches."
    },
    "import": {
      "type": "string",
      "description": "The import id (imports from import_sources, or the id in the console address)."
    },
    "connection": {
      "type": "string",
      "description": "The source account (connection from import_sources), with project when there is no import."
    },
    "project": {
      "type": "string",
      "description": "The source project (projects[].id from import_sources)."
    },
    "address": {
      "type": "string",
      "description": "A Supabase source's session pooler connection string (postgres.<ref>, port 5432). Empty for other sources."
    }
  },
  "additionalProperties": false
}

`get_import` Import progress

Read-only Reaches outside

The same as the import progress page in the console. For each destination the state and counts of each step (schema, sign-in users, data, files, scheduled jobs...), what is not moved and why, and what is worth checking.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/imports/{id}`

Input

Name	Type	Required	Description
`id`	`string`	Yes	The import id.
`org`	`string`	No	The organisation id or name. Empty means the first one this token reaches.

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The import id."
    },
    "org": {
      "type": "string",
      "description": "The organisation id or name. Empty means the first one this token reaches."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Projects

Name	Description
`list_projects`	Projects
`create_project`	Create a project
`pause_project`	Pause a project
`resume_project`	Resume a project
`delete_project`	Delete a project
`retry_provisioning`	Retry a project that failed to set up
`rename_project`	Rename
`get_project_archive`	Database archive status
`restore_project_archive`	Restore an archived database
`create_archive_download_url`	Archive download address

`list_projects` Projects

Read-only

Returns the projects on this account and the API address of each. status is ready (usable), provisioning (the database is being made, a few seconds), failed (retry_provisioning) or paused.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects`, GET `/projects/{ref}`

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`create_project` Create a project

Only adds

Creates a new project with a database, sign-in and file storage. Leave the region empty for the default region. The region cannot be changed after the project is created. The price is the same in every region. With several organizations, org chooses which one to create it in (only its owners, admins and developers can, within the number of projects its plan allows). The database is ready a few seconds later: when status is provisioning, pass wait (seconds) or use tables and keys once status in list_projects is ready.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Always asks
REST	POST `/projects`

Input

Name	Type	Required	Description
`name`	`string`	Yes	A name for people to read.
`region`	`string`	No	Where to put it. list_regions tells you the values you can use. Empty means the default region.
`org`	`string`	No	The id or name of the organization to create it in (organisation_id or organisation from list_projects). Empty means the first organization you can create projects in.
`tier`	`string`	No	The size of a server for this project alone: a value list_server_sizes gave (for example 4gb), or default for the plan's own size. The server is asked for as soon as the project exists. Empty starts it on the shared server.
`repo`	`string`	No	A GitHub repository (owner/name, the repo from list_importable_repositories) to connect and deploy as the project is made. Empty makes the project without one. The fields below (branch, root_directory, app, installation, framework, build_command, output_directory, install_command, dotenv, sensitive) are import_repository's and are read only when repo is given.
`branch`	`string`	No	With repo: the production branch. Empty means the repository's default branch.
`root_directory`	`string`	No	With repo: the app folder of a monorepo (for example apps/web).
`app`	`string`	No	With repo: the app's name. Empty means the folder name, or the repository name.
`installation`	`integer`	No	With repo: which GitHub account's installation to take it through.
`framework`	`string`	No	With repo: the framework preset. Empty or auto detects it.
`build_command`	`string`	No	With repo: overrides the build command.
`output_directory`	`string`	No	With repo: overrides the output directory.
`install_command`	`string`	No	With repo: overrides the install command.
`dotenv`	`string`	No	With repo: the contents of a .env file, saved for production and previews.
`sensitive`	`boolean`	No	With repo: the values of dotenv are not shown again after they are saved.
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the database to be ready (status: ready). The default 0 answers at once. It usually takes a few seconds.

JSON Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "A name for people to read."
    },
    "region": {
      "type": "string",
      "description": "Where to put it. list_regions tells you the values you can use. Empty means the default region."
    },
    "org": {
      "type": "string",
      "description": "The id or name of the organization to create it in (organisation_id or organisation from list_projects). Empty means the first organization you can create projects in."
    },
    "tier": {
      "type": "string",
      "description": "The size of a server for this project alone: a value list_server_sizes gave (for example 4gb), or default for the plan's own size. The server is asked for as soon as the project exists. Empty starts it on the shared server."
    },
    "repo": {
      "type": "string",
      "description": "A GitHub repository (owner/name, the repo from list_importable_repositories) to connect and deploy as the project is made. Empty makes the project without one. The fields below (branch, root_directory, app, installation, framework, build_command, output_directory, install_command, dotenv, sensitive) are import_repository's and are read only when repo is given."
    },
    "branch": {
      "type": "string",
      "description": "With repo: the production branch. Empty means the repository's default branch."
    },
    "root_directory": {
      "type": "string",
      "description": "With repo: the app folder of a monorepo (for example apps/web)."
    },
    "app": {
      "type": "string",
      "description": "With repo: the app's name. Empty means the folder name, or the repository name."
    },
    "installation": {
      "type": "integer",
      "description": "With repo: which GitHub account's installation to take it through."
    },
    "framework": {
      "type": "string",
      "description": "With repo: the framework preset. Empty or auto detects it."
    },
    "build_command": {
      "type": [
        "string",
        "null"
      ],
      "description": "With repo: overrides the build command."
    },
    "output_directory": {
      "type": [
        "string",
        "null"
      ],
      "description": "With repo: overrides the output directory."
    },
    "install_command": {
      "type": [
        "string",
        "null"
      ],
      "description": "With repo: overrides the install command."
    },
    "dotenv": {
      "type": "string",
      "description": "With repo: the contents of a .env file, saved for production and previews."
    },
    "sensitive": {
      "type": "boolean",
      "description": "With repo: the values of dotenv are not shown again after they are saved."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the database to be ready (status: ready). The default 0 answers at once. It usually takes a few seconds."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

`pause_project` Pause a project

Destructive

Stops everything the project does: the site, API and functions return 503, realtime connections are refused, and scheduled jobs and new deployments stop. Data and files stay, and resume_project brings it straight back. Paused for over 90 days, the database moves to archive storage (get_project_archive). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/pause`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`resume_project` Resume a project

Destructive

Starts a paused project again, including one the Free plan paused after 3 unused days (a new deployment also starts it). Scheduled jobs do not catch up on missed runs; they run from the next scheduled time.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/resume`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`delete_project` Delete a project

Destructive

Permanently deletes the project's tables, users, files, functions, scheduled jobs, environment variables and domains. This cannot be undone. Use it only when the user clearly asks, and put the project name exactly in confirm. The last remaining project cannot be deleted. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`confirm`	`string`	Yes	The project name. It must be exactly the name from list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "confirm": {
      "type": "string",
      "description": "The project name. It must be exactly the name from list_projects."
    }
  },
  "required": [
    "ref",
    "confirm"
  ],
  "additionalProperties": false
}

`retry_provisioning` Retry a project that failed to set up

Only adds

Sets up again a project whose database could not be created. Use it when another tool refuses with "could not create". Do not create a new project: this continues setting up the same one, and a new one only doubles the bill.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/retry-provisioning`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`rename_project` Rename

Destructive

Changes the project name, the organisation name, or both. The identifier (ref) and the addresses do not change. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	No	The new project name.
`organisation`	`string`	No	The new organisation name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The new project name."
    },
    "organisation": {
      "type": "string",
      "description": "The new organisation name."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_project_archive` Database archive status

Read-only

A database that has been unusable for 90 days (a failed payment, the Free plan, a pause) is moved to archive storage. Returns where this project stands: state (none, scheduled, archiving, archived, restoring, purged), reason, archive_at (when it moves), purge_at (when the archive and the files are deleted, a year after the move), restore_blocked_by.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/archive`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`restore_project_archive` Restore an archived database

Destructive

Makes the database in archive storage again, exactly as it was archived. Usually a few minutes; a paused project starts again with the restore. Refused while a payment is outstanding or on the Free plan (restore_blocked_by). If the archive was already deleted, creates a new, empty database. Owners and admins only.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/archive/restore`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_archive_download_url` Archive download address

Only adds

Creates a signed address the archived database (pg_dump format; restore it with pg_restore) can be downloaded from for an hour. Needs a reason, which is kept in the access records. Owners and admins only.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/archive/download`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`reason`	`string`, min length 4, max length 300	Yes	Why it is downloaded. Kept in the access records.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "reason": {
      "type": "string",
      "minLength": 4,
      "maxLength": 300,
      "description": "Why it is downloaded. Kept in the access records."
    }
  },
  "required": [
    "ref",
    "reason"
  ],
  "additionalProperties": false
}

Keys and signing

Name	Description
`get_project_keys`	Get API keys
`list_api_keys`	Named API keys
`create_api_key`	Create an API key
`revoke_api_key`	Revoke an API key
`get_jwt_signing`	Token signing
`set_jwt_signing`	Change token signing
`rotate_signing_key`	Rotate the key
`retire_signing_key`	Retire an old key

`get_project_keys` Get API keys

Read-only

Returns the project address and its two keys. The publishable key is for browsers. The secret key bypasses every access rule, so use it only on a server. Only a token with write access can call this. When you need values for frontend code, call it with only: "publishable": you get the address and the publishable key only, so the secret key never enters the conversation or the code (a read-only token can do this).

Name	Description
Token scope	`write`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`only`	`string`, publishable	No	publishable returns only the address and the publishable key. Empty returns both keys.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "only": {
      "type": "string",
      "enum": [
        "publishable"
      ],
      "description": "publishable returns only the address and the publishable key. Empty returns both keys."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_api_keys` Named API keys

Read-only

The name, kind, prefix, last use and revoked state of each bw_publishable_ and bw_secret_ key made for a purpose. The value of a secret key is never returned. The value of a publishable key is.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/api-keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_api_key` Create an API key

Only adds

Creates one named key. publishable is for browsers (follows access rules); secret is for servers (bypasses access rules). The value of a secret key is in this response only and cannot be seen again. Only owners and admins can create keys, up to 20 per project.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/api-keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`kind`	`string`, publishable \| secret	Yes	publishable for browsers, secret for servers.
`name`	`string`, min length 1, max length 60	Yes	What the key is for. For example: payment server

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "kind": {
      "type": "string",
      "enum": [
        "publishable",
        "secret"
      ],
      "description": "publishable for browsers, secret for servers."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "What the key is for. For example: payment server"
    }
  },
  "required": [
    "ref",
    "kind",
    "name"
  ],
  "additionalProperties": false
}

`revoke_api_key` Revoke an API key

Destructive

Revokes one named key. Requests with that key are refused within 30 seconds. Other keys are not affected. This cannot be undone.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/api-keys/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_api_keys.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_api_keys."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_jwt_signing` Token signing

Read-only

Shows whether sign-in tokens are signed with HS256 or ES256, and the old keys still accepted for now (keys in their grace period).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/signing`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_jwt_signing` Change token signing

Destructive

With ES256, new sign-ins are signed with an asymmetric key and other servers can check tokens with the public keys (JWKS). Tokens already issued keep working until they expire. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/signing`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`alg`	`string`, HS256 \| ES256	Yes	HS256 or ES256.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "alg": {
      "type": "string",
      "enum": [
        "HS256",
        "ES256"
      ],
      "description": "HS256 or ES256."
    }
  },
  "required": [
    "ref",
    "alg"
  ],
  "additionalProperties": false
}

`rotate_signing_key` Rotate the key

Destructive

Creates a new key for signing the publishable and secret keys. The old key is still accepted for grace_hours (0, 1, 24, 168); 0 (or empty) makes it invalid at once (when it leaked). With 0 every app using it stops within 30 seconds, so put the project name (name from list_projects) exactly in confirm. Every key put in an app has to be replaced, so use this only when the user clearly asks. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/signing/rotate`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`grace_hours`	`integer`, 0 \| 1 \| 24 \| 168	No	How many hours the old key is still accepted: 0, 1, 24 or 168.
`confirm`	`string`	No	Only when grace_hours is 0 or empty: the project name. It must be exactly the same as name in list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "grace_hours": {
      "type": "integer",
      "enum": [
        0,
        1,
        24,
        168
      ],
      "description": "How many hours the old key is still accepted: 0, 1, 24 or 168."
    },
    "confirm": {
      "type": "string",
      "description": "Only when grace_hours is 0 or empty: the project name. It must be exactly the same as name in list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`retire_signing_key` Retire an old key

Destructive

Ends an old key in its grace period now. kid is one in the keys of get_jwt_signing whose state is rotating. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/signing/keys/{kid}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`kid`	`string`	Yes	The kid from get_jwt_signing.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "kid": {
      "type": "string",
      "description": "The kid from get_jwt_signing."
    }
  },
  "required": [
    "ref",
    "kid"
  ],
  "additionalProperties": false
}

Database

Name	Description
`get_advisors`	Security and performance check
`list_tables`	Tables
`list_policies`	Access rules
`query_sql`	Query SQL (read-only)
`run_sql`	Run SQL (changes)
`read_rows`	Read a table
`export_table_csv`	Export a table as CSV
`import_table_csv`	Import CSV into a table
`get_database_connection`	Database connection details
`reset_database_password`	New database password
`list_extensions`	Database extensions
`enable_extension`	Turn on a database extension
`disable_extension`	Turn off a database extension
`get_database_move`	Move to a dedicated database: status
`move_to_dedicated_database`	Move to a dedicated database
`get_dedicated_disk`	Dedicated disk
`request_dedicated_disk`	Move to a dedicated disk
`shrink_dedicated_disk`	Make the disk smaller
`list_realtime_tables`	Tables with realtime on
`set_realtime`	Turn realtime on or off for a table
`list_migrations`	Migration history
`apply_migrations`	Apply migrations
`remove_migration_record`	Remove a migration record
`dump_schema`	The schema as SQL
`generate_typescript_types`	Generate TypeScript types
`list_mysql_databases`	List MySQL databases
`create_mysql_database`	Create a MySQL database
`bind_mysql_database`	Connect a MySQL database to an app
`delete_mysql_database`	Delete a MySQL database
`get_mysql_connection`	MySQL connection
`create_mysql_backup`	Back up MySQL now
`list_mysql_backups`	List MySQL backups
`restore_mysql_backup`	Restore MySQL from a backup

`get_advisors` Security and performance check

Read-only

Looks for security and performance problems in the project's database structure: tables with RLS off, rules that let anyone write, views that bypass access rules, security definer functions with no fixed search_path, views that expose the users table, foreign keys with no index, tables with no primary key, duplicate indexes, and rules that call uid() for every row. Where there is SQL that fixes an item (remedy), it is included. No data is read. Call this after creating tables or changing rules.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/advisors`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_tables` Tables

Read-only

Returns the project's tables with their columns, an approximate row count and the state of their access rules. If rules are on and there are none, the publishable key sees nothing.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/tables`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_policies` Access rules

Read-only

Returns which action on which table is open to whom.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/policies`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`query_sql` Query SQL (read-only)

Read-only

Runs one query (SELECT and the like) on the project's PostgreSQL database in a read-only transaction and returns the rows. A statement that changes data or structure is refused; use run_sql for that. A read-only token can call it. It does not open Vault secrets (decrypted_secret in vault.decrypted_secrets is empty). SQL follows the PostgreSQL 16 documentation (https://www.postgresql.org/docs/16/sql-commands.html).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/sql/query`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`sql`	`string`	Yes	One query to run.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "sql": {
      "type": "string",
      "description": "One query to run."
    }
  },
  "required": [
    "ref",
    "sql"
  ],
  "additionalProperties": false
}

`run_sql` Run SQL (changes)

Destructive

Runs SQL that changes data or structure (CREATE, INSERT, UPDATE, DELETE and so on) on the project's PostgreSQL database and returns the resulting rows. For reading only, use query_sql. SQL follows the PostgreSQL 16 documentation (https://www.postgresql.org/docs/16/sql-commands.html). A new table gets access rules turned on automatically, so unless you then create rules, the publishable key sees nothing. The role names to use in rules are <ref>_anon, <ref>_authenticated and <ref>_service_role. SQL written for Supabase (public., auth.uid(), storage., to authenticated) is run in this project's names, and translated says what was replaced (Supabase name translation).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Depends on the input (no question for read-only SQL or a dry_run)
REST	POST `/projects/{ref}/sql`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`sql`	`string`	Yes	One SQL statement to run.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "sql": {
      "type": "string",
      "description": "One SQL statement to run."
    }
  },
  "required": [
    "ref",
    "sql"
  ],
  "additionalProperties": false
}

`read_rows` Read a table

Read-only

Reads the first rows of a table as they are. For checking; when you need conditions, use run_sql.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/rows/{table}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`table`	`string`	Yes	The table name.
`limit`	`integer`, min 1, max 200	No	Default 50 rows.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "table": {
      "type": "string",
      "description": "The table name."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Default 50 rows."
    }
  },
  "required": [
    "ref",
    "table"
  ],
  "additionalProperties": false
}

`export_table_csv` Export a table as CSV

Read-only

Returns a table's rows as CSV (the first line holds the column names), as the console table editor's export does. Up to 1MB comes back; past that it is cut at a whole row and truncated is true. Then split the range with filters and fetch it in several calls. An empty field is NULL and "" is an empty string.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/tables/{table}/csv`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`table`	`string`	Yes	The table name (list_tables).
`filters`	`array<object>`, max items 10	No	Only rows that match all of these. For example [{"column": "created_at", "op": "gte", "value": "2026-01-01"}]
`sort`	`string`	No	Order by this column. Empty for the table's own order.
`desc`	`boolean`	No	With true, largest first.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "table": {
      "type": "string",
      "description": "The table name (list_tables)."
    },
    "filters": {
      "type": "array",
      "maxItems": 10,
      "description": "Only rows that match all of these. For example [{\"column\": \"created_at\", \"op\": \"gte\", \"value\": \"2026-01-01\"}]",
      "items": {
        "type": "object",
        "properties": {
          "column": {
            "type": "string",
            "description": "The column name."
          },
          "op": {
            "type": "string",
            "enum": [
              "eq",
              "neq",
              "gt",
              "lt",
              "gte",
              "lte",
              "like",
              "ilike",
              "in",
              "is",
              "isnot"
            ],
            "description": "The comparison. in takes comma separated values; is and isnot test for NULL."
          },
          "value": {
            "type": "string",
            "description": "The value to compare with."
          }
        },
        "required": [
          "column",
          "op"
        ],
        "additionalProperties": false
      }
    },
    "sort": {
      "type": "string",
      "description": "Order by this column. Empty for the table's own order."
    },
    "desc": {
      "type": "boolean",
      "description": "With true, largest first."
    }
  },
  "required": [
    "ref",
    "table"
  ],
  "additionalProperties": false
}

`import_table_csv` Import CSV into a table

Only adds

Puts CSV rows into a table, as the console table editor's import does. The first line names the columns, and each goes into the column of the same name (columns changes that). If any row cannot go in, nothing goes in, and the line numbers and reasons come back. Up to 2MB and 10,000 rows. An unquoted empty field is NULL or the column's default. Split anything larger into several calls.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/tables/{table}/csv`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`table`	`string`	Yes	The table name (list_tables).
`csv`	`string`	Yes	The CSV text. The first line holds the column names.
`columns`	`array<string>`	No	For each CSV column, the table column it goes into, or "" to skip it. As many as the first line has. Leave it out to match by name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "table": {
      "type": "string",
      "description": "The table name (list_tables)."
    },
    "csv": {
      "type": "string",
      "description": "The CSV text. The first line holds the column names."
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "For each CSV column, the table column it goes into, or \"\" to skip it. As many as the first line has. Leave it out to match by name."
    }
  },
  "required": [
    "ref",
    "table",
    "csv"
  ],
  "additionalProperties": false
}

`get_database_connection` Database connection details

Read-only

Shows the addresses for connecting directly to this project's PostgreSQL: direct (5432, session: migration tools and database clients) and pooler (6543, transaction: serverless). The password is not stored, so it appears as [YOUR-PASSWORD].

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/database`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`reset_database_password` New database password

Destructive

Creates a new password for direct connections and returns it once. Anything connecting with the old password is refused from its next connection: servers, jobs and tools connected with it now break when they reconnect, so put the project name (name from list_projects) exactly in confirm.This user bypasses row level security, so keep it on servers only. With keep_for_deploys: true the password is also kept sealed, and production servers, middleware and functions get DATABASE_URL, POSTGRES_URL and DIRECT_URL at runtime (never builds). Deployed code can then read every row, like the secret key, so turn it on only when the user wants it. A reset without it stops the handover. Use this only when the user asks. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/database/password`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`keep_for_deploys`	`boolean`	No	true: hand it to production deploys as DATABASE_URL (kept sealed). Absent or false: not kept, and any handover stops.
`confirm`	`string`	Yes	The project name. It must be exactly the same as name in list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "keep_for_deploys": {
      "type": "boolean",
      "description": "true: hand it to production deploys as DATABASE_URL (kept sealed). Absent or false: not kept, and any handover stops."
    },
    "confirm": {
      "type": "string",
      "description": "The project name. It must be exactly the same as name in list_projects."
    }
  },
  "required": [
    "ref",
    "confirm"
  ],
  "additionalProperties": false
}

`list_extensions` Database extensions

Read-only

The PostgreSQL extensions you can turn on (vector from pgvector, postgis, citext, pgcrypto and others), and for each whether this server has it (available), whether it is on (enabled), and its version. Extensions are installed in the extensions schema and used in SQL just as vector(1536) or geometry.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/extensions`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`enable_extension` Turn on a database extension

Destructive

Turns on one extension (create extension ... with schema extensions). vector for embedding search, postgis for maps and distances. Extensions not on the list are refused. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/extensions/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The extension name: vector, postgis, citext, hstore, uuid-ossp, pgcrypto, ltree, fuzzystrmatch, btree_gin, btree_gist, intarray, tablefunc

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The extension name: vector, postgis, citext, hstore, uuid-ossp, pgcrypto, ltree, fuzzystrmatch, btree_gin, btree_gist, intarray, tablefunc"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`disable_extension` Turn off a database extension

Destructive

Turns off one extension. Refused while columns, indexes or functions that use it remain. If another project on the same database uses it, it stays installed and only this project's record is removed (note). pg_trgm and unaccent are built in and cannot be turned off. Put the extension name exactly in confirm. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	DELETE `/projects/{ref}/extensions/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The extension name, as in list_extensions.
`confirm`	`string`	Yes	The extension name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The extension name, as in list_extensions."
    },
    "confirm": {
      "type": "string",
      "description": "The extension name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`get_database_move` Move to a dedicated database: status

Read-only

Whether this project is on a dedicated database (dedicated), whether its plan includes one (plan_allows), and whether a move was requested, is under way or failed and stopped (stopped, last_error). When size_bytes is above auto_move_max_bytes the project is not moved automatically; request it with move_to_dedicated_database.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/database/move`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`move_to_dedicated_database` Move to a dedicated database

Destructive

Requests the move of a project on the shared database to a database of its own, as the console's "Move now" does. It moves when its turn comes; writes pause during the move and reads carry on. The project as it was just before is kept as a backup, and if the move fails the project stays where it was (a stopped move is tried again when requested again). Needed for Vault and for large databases. Included from the Pro plan. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/database/move`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_dedicated_disk` Dedicated disk

Read-only

The disk and Postgres of this project's own, used once its database has grown: its size (size_gb), what is used, the monthly cost, 30 days of history, a request in progress and the suggestion to make it smaller (shrink). While the project is on the shared disk, the size that moves it (threshold_gb) and the database's size now.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/database/dedicated-disk`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`request_dedicated_disk` Move to a dedicated disk

Destructive

Requests the move of this project's database to a disk of its own (max(1.2 x the database, 20 GB)), as the console's "Move to a dedicated disk" does. The disk is billed on its provisioned size at KRW 1,200 (75 cents) per GB a month, and while it moves writes fail and reads work (expected_downtime_seconds in get_dedicated_disk). Enterprise may ask at any time; other paid plans once past the threshold. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/database/dedicated-disk`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`shrink_dedicated_disk` Make the disk smaller

Destructive

Makes the dedicated disk smaller: a new, smaller disk (1.2 x the database, at least 20 GB) is made, the data moves onto it and the old disk is deleted. Only a disk under 25% used for 7 days can be made smaller (shrink.suggested in get_dedicated_disk). While it moves writes fail and reads work. It is never made smaller on its own. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/database/dedicated-disk/shrink`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_realtime_tables` Tables with realtime on

Read-only

The tables whose changes are sent in real time. Subscribing to a table not listed here receives nothing.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/realtime`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_realtime` Turn realtime on or off for a table

Destructive

Turns change notifications for one table on or off. Notifications also go only for rows that pass the access rules.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/realtime/{table}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`table`	`string`	Yes	The table name.
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "table": {
      "type": "string",
      "description": "The table name."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "table",
    "enabled"
  ],
  "additionalProperties": false
}

`list_migrations` Migration history

Read-only

Returns the version, name and time applied of each migration applied with apply_migrations, oldest first. The record is kept in the project's oneend_migrations table.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/migrations`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`apply_migrations` Apply migrations

Destructive

Runs the migrations not yet applied, in version order, each in a transaction of its own, and records them. Versions already applied are skipped. If one fails, only that one is rolled back and applying stops; the ones before it stay applied. Use this instead of run_sql when changing the schema, and you can apply the same changes to other projects exactly as they are. Files from supabase/migrations can be sent as they are: Supabase names such as public., auth.uid(), storage. and to authenticated are run in this project's names and reported in translated (Supabase name translation). The ledger keeps each file as written.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Depends on the input (no question for read-only SQL or a dry_run)
REST	POST `/projects/{ref}/migrations`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`migrations`	`array<object>`, max items 500	Yes	The migrations, each with version, name and sql.
`include_all`	`boolean`	No	Also applies versions earlier than the last applied one. False by default.
`record_only`	`boolean`	No	Records them as applied without running them. False by default.
`dry_run`	`boolean`	No	Only tells you what would be applied.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "migrations": {
      "type": "array",
      "maxItems": 500,
      "items": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string",
            "pattern": "^[0-9]{1,32}$",
            "description": "A numeric version. Usually YYYYMMDDHHMMSS."
          },
          "name": {
            "type": "string",
            "description": "A short name of letters, digits, _ and -. For example: create_notes"
          },
          "sql": {
            "type": "string",
            "description": "The SQL to run. Several statements are fine."
          }
        },
        "required": [
          "version",
          "sql"
        ],
        "additionalProperties": false
      },
      "description": "The migrations, each with version, name and sql."
    },
    "include_all": {
      "type": "boolean",
      "description": "Also applies versions earlier than the last applied one. False by default."
    },
    "record_only": {
      "type": "boolean",
      "description": "Records them as applied without running them. False by default."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Only tells you what would be applied."
    }
  },
  "required": [
    "ref",
    "migrations"
  ],
  "additionalProperties": false
}

`remove_migration_record` Remove a migration record

Destructive

Marks one migration as not applied. Only the record is removed; what the migration made is left as it is.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/migrations/{version}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`version`	`string`, pattern ^[0-9]{1,32}$	Yes	The version from list_migrations.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9]{1,32}$",
      "description": "The version from list_migrations."
    }
  },
  "required": [
    "ref",
    "version"
  ],
  "additionalProperties": false
}

`dump_schema` The schema as SQL

Read-only

Returns the project's schema (types, sequences, tables and constraints, foreign keys, indexes, functions, views, triggers, RLS and rules) as SQL that builds it again. Row data and privileges are not included.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/schema`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`generate_typescript_types` Generate TypeScript types

Read-only

Makes the Database type for supabase-js's createClient<Database>() from the project's tables, views, functions and enums. Call it again after changing the schema.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/types/typescript`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`schema`	`string`	No	public by default. A schema the project made (name from list_schemas) works too.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "schema": {
      "type": "string",
      "description": "public by default. A schema the project made (name from list_schemas) works too."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_mysql_databases` List MySQL databases

Read-only

Returns this project's MySQL databases (MariaDB 11.4), which app each goes to (app; null is the whole project), their status and size, and how many the plan allows (max). available false means this server has no MySQL yet.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/mysql`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_mysql_database` Create a MySQL database

Only adds

Creates a database and its own login for an app that uses MySQL, such as WordPress. Usually ready within a minute. With app, only that app's deployments get it; without, every app of the project does (while it is the project's only one). That app's servers start with MYSQL_URL, MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE and WORDPRESS_DB_HOST, WORDPRESS_DB_USER, WORDPRESS_DB_PASSWORD, WORDPRESS_DB_NAME (never in a build). Backed up every night.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/mysql`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, pattern ^[a-z][a-z0-9_]{0,31}$	Yes	Starts with a lowercase letter; lowercase letters, digits and underscores (_), up to 32. For example: wordpress
`app`	`string`	No	The app that gets this database. Empty for the whole project

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{0,31}$",
      "description": "Starts with a lowercase letter; lowercase letters, digits and underscores (_), up to 32. For example: wordpress"
    },
    "app": {
      "type": "string",
      "description": "The app that gets this database. Empty for the whole project"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`bind_mysql_database` Connect a MySQL database to an app

Destructive

Changes which app gets a MySQL database. app null makes it the whole project's. One app has at most one database. Running servers get the change when they restart or are deployed again.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/mysql/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The MySQL database name
`app`	`string`	Yes	An app name, or null for the whole project

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The MySQL database name"
    },
    "app": {
      "type": [
        "string",
        "null"
      ],
      "description": "An app name, or null for the whole project"
    }
  },
  "required": [
    "ref",
    "name",
    "app"
  ],
  "additionalProperties": false
}

`delete_mysql_database` Delete a MySQL database

Destructive

Deletes a MySQL database with its login and every backup. This cannot be undone: use it only when the user clearly asked, and put the database name exactly in confirm. The app that got it no longer gets MYSQL_* variables from its next start. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/mysql/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The MySQL database name
`confirm`	`string`	Yes	The MySQL database name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The MySQL database name"
    },
    "confirm": {
      "type": "string",
      "description": "The MySQL database name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`get_mysql_connection` MySQL connection

Read-only

Returns a MySQL database's address, port, database name, login, password and the variables its app gets (variables). The address is reachable only from apps on this server. The password is shown to a write token only.

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/mysql/{name}/connection`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The MySQL database name

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The MySQL database name"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`create_mysql_backup` Back up MySQL now

Only adds

Backs up a MySQL database now. Make one before updating plugins or changing a lot at once. Kept for 7 days. The nightly backup happens on its own as well.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/mysql/{name}/backups`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The MySQL database name

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The MySQL database name"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`list_mysql_backups` List MySQL backups

Read-only

Returns a MySQL database's backups (nightly, made by hand, and taken just before a restore) and its restores.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/mysql/{name}/backups`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The MySQL database name

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The MySQL database name"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`restore_mysql_backup` Restore MySQL from a backup

Destructive

Puts a MySQL database back to when a backup was taken. Every change since is lost, so use it only when the user clearly asked, and put the database name exactly in confirm. The state just before is backed up first, so undo_backup_id restores it again. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/mysql/{name}/restore`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The MySQL database name
`backup_id`	`string`	Yes	A backup id from list_mysql_backups
`confirm`	`string`	Yes	The MySQL database name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The MySQL database name"
    },
    "backup_id": {
      "type": "string",
      "description": "A backup id from list_mysql_backups"
    },
    "confirm": {
      "type": "string",
      "description": "The MySQL database name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "backup_id",
    "confirm"
  ],
  "additionalProperties": false
}

Auth and users

Name	Description
`list_users`	The service's users
`add_user`	Add a user
`import_users`	Import users
`update_user`	Change a user
`generate_link`	Make a sign-in link
`list_auth_providers`	Social sign-in settings
`set_auth_provider`	Turn on social sign-in
`set_auth_provider_enabled`	Turn social sign-in off and on
`remove_auth_provider`	Remove social sign-in
`get_smtp_settings`	SMTP settings
`set_smtp_settings`	Set SMTP settings
`test_smtp_settings`	Send an SMTP test email
`remove_smtp_settings`	Remove SMTP settings
`get_email_templates`	Email templates
`set_email_template`	Save an email template
`preview_email_template`	Preview an email template
`remove_email_template`	Restore an email template
`get_sms_settings`	SMS sign-in settings
`set_sms_settings`	Set up SMS sign-in
`remove_sms_settings`	Remove SMS sign-in
`list_sso_providers`	SAML SSO
`remove_sso_provider`	Remove SAML SSO
`list_redirect_urls`	Addresses to return to after sign-in
`add_redirect_url`	Add an address to return to
`remove_redirect_url`	Remove an address to return to
`remove_user`	Remove a user
`set_anonymous_sign_in`	Turn anonymous sign-in on or off

`list_users` The service's users

Read-only

The users who signed up to the service that uses this project. They are separate from platform accounts. Up to 200 come at a time, and total gives the full count. When has_more is true there are more, so call again with a higher offset. Using the length of users as the head count is wrong.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/users`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`limit`	`integer`, min 1, max 200	No	How many users to get at a time. Default 50, at most 200.
`offset`	`integer`, min 0	No	How many users to skip. Default 0.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "How many users to get at a time. Default 50, at most 200."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "How many users to skip. Default 0."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`add_user` Add a user

Only adds

Creates one user in this project's service. The password must be at least 10 characters.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/users`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`email`	`string`	Yes	The user's email address.
`password`	`string`	Yes	At least 10 characters.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "email": {
      "type": "string",
      "description": "The user's email address."
    },
    "password": {
      "type": "string",
      "description": "At least 10 characters."
    }
  },
  "required": [
    "ref",
    "email",
    "password"
  ],
  "additionalProperties": false
}

`import_users` Import users

Only adds

Imports up to 500 users at once from another service (for example a Supabase auth.users export). Ids and bcrypt password hashes are kept, so nobody has to choose a new password. The whole list is checked first: a wrong row is named by number and nothing is imported. An account that already exists is skipped, so repeating a call is safe. dry_run=true only checks.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/users/import`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`users`	`array<object>`	Yes	The accounts: { email, id?, encrypted_password?, email_confirmed?, user_metadata?, app_metadata? }.
`dry_run`	`boolean`	No	Check the list and import nothing.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "encrypted_password": {
            "type": "string"
          },
          "email_confirmed": {
            "type": "boolean"
          },
          "user_metadata": {
            "type": "object"
          },
          "app_metadata": {
            "type": "object"
          }
        },
        "required": [
          "email"
        ],
        "additionalProperties": false
      },
      "description": "The accounts: { email, id?, encrypted_password?, email_confirmed?, user_metadata?, app_metadata? }."
    },
    "dry_run": {
      "type": "boolean",
      "description": "Check the list and import nothing."
    }
  },
  "required": [
    "ref",
    "users"
  ],
  "additionalProperties": false
}

`update_user` Change a user

Destructive

Changes one of this project's users: the email, the password, whether the email is confirmed, a ban and its end, and the metadata. Only what you give changes. A new password or a ban signs the person out everywhere. A password needs at least 10 characters, and one known from a breach is refused. Metadata is merged into what is there. Use it only when the user clearly asks.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	PATCH `/projects/{ref}/users/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id (UUID) from list_users.
`email`	`string`	No	The new email address.
`password`	`string`	No	The new password (at least 10 characters).
`email_confirm`	`boolean`	No	With true, marks the email address as confirmed.
`ban_duration`	`string`	No	How long to ban, such as 24h, 30m or 876000h (in effect forever). none lifts a ban.
`user_metadata`	`object`	No	Values to merge into the metadata the user may change.
`app_metadata`	`object`	No	Values to merge into the metadata only a server changes (a role, a plan and so on).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id (UUID) from list_users."
    },
    "email": {
      "type": "string",
      "description": "The new email address."
    },
    "password": {
      "type": "string",
      "description": "The new password (at least 10 characters)."
    },
    "email_confirm": {
      "type": "boolean",
      "description": "With true, marks the email address as confirmed."
    },
    "ban_duration": {
      "type": "string",
      "description": "How long to ban, such as 24h, 30m or 876000h (in effect forever). none lifts a ban."
    },
    "user_metadata": {
      "type": "object",
      "description": "Values to merge into the metadata the user may change."
    },
    "app_metadata": {
      "type": "object",
      "description": "Values to merge into the metadata only a server changes (a role, a plan and so on)."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`generate_link` Make a sign-in link

Destructive

Makes the link a sign-in mail would carry and returns it instead of mailing it: invite (creates the user when there is none), magiclink (sign-in without a password), recovery (a password reset) or signup (confirms a new sign-up; needs password). Whoever opens action_link is signed in as that user, so it is as good as a password. Make one only when the user clearly asks, and give it only to that person. redirect_to must be an address added with add_redirect_url. Only roles that can see the secret key (owner, admin, developer) can do this.

Name	Description
Token scope	`write`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/users/{id}/links`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`type`	`string`, invite \| magiclink \| recovery \| signup	Yes	invite, magiclink, recovery or signup.
`email`	`string`	Yes	The user's email address.
`password`	`string`	No	For signup, the new user's password (at least 10 characters).
`data`	`object`	No	User metadata for a user that invite, signup or magiclink creates.
`redirect_to`	`string`	No	Where to return after confirming. Only an address in list_redirect_urls.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "type": {
      "type": "string",
      "enum": [
        "invite",
        "magiclink",
        "recovery",
        "signup"
      ],
      "description": "invite, magiclink, recovery or signup."
    },
    "email": {
      "type": "string",
      "description": "The user's email address."
    },
    "password": {
      "type": "string",
      "description": "For signup, the new user's password (at least 10 characters)."
    },
    "data": {
      "type": "object",
      "description": "User metadata for a user that invite, signup or magiclink creates."
    },
    "redirect_to": {
      "type": "string",
      "description": "Where to return after confirming. Only an address in list_redirect_urls."
    }
  },
  "required": [
    "ref",
    "type",
    "email"
  ],
  "additionalProperties": false
}

`list_auth_providers` Social sign-in settings

Read-only

Shows which accounts people can use to sign in to this project's service. Every provider the platform supports is returned, so ones not set up yet show configured: false. Providers you registered yourself (custom:<name>) follow, with a custom entry (addresses, scopes, answer field mapping). callback_url is the address to paste as it is into the provider's console.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/auth/providers`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_auth_provider` Turn on social sign-in

Destructive

Saves and turns on one provider's client ID and secret. The secret is sealed and cannot be read back; only its last four characters can be checked. First create an app in the provider's console and register the callback_url from list_auth_providers as its redirect address. To change only the ID of a provider already saved, leave client_secret as an empty string. As on Supabase, a provider of custom:<name> registers an OAuth 2.0 or OpenID Connect provider the platform does not list (for example custom:kakao-xts). It then needs issuer (for OpenID Connect this alone fills in the addresses) or authorize_url and token_url (and userinfo_url), and may take scopes and claims (which field of the answer is id, email, email_verified, name, avatar and phone, as dotted paths). Your app signs in with signInWithOAuth({ provider: "custom:<name>" }), and right after sign-in the session carries provider_token, once.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/auth/providers/{provider}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, pattern ^(google\|kakao\|naver\|apple\|github\|gitlab\|microsoft\|facebook\|line\|discord\|x\|bitbucket\|figma\|linkedin_oidc\|notion\|twitch\|slack_oidc\|spotify\|zoom\|azure\|keycloak\|workos\|twitter\|slack\|custom:[a-z0-9][a-z0-9_-]{0,39})$	Yes	The sign-in provider: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack, or custom:<name> for one you register yourself (lowercase letters, digits, - and _, up to 40).
`client_id`	`string`	Yes	The client ID from the provider's console.
`client_secret`	`string`	Yes	An empty string keeps the secret already saved. Required for a new provider.
`enabled`	`boolean`	No	On by default.
`label`	`string`	No	custom: providers only. The name shown on screens.
`issuer`	`string`	No	custom: providers only. The OpenID Connect issuer (for example https://kauth.kakao.com). Empty addresses are filled from its discovery document.
`authorize_url`	`string`	No	custom: providers only. The sign-in page address (https).
`token_url`	`string`	No	custom: providers only. The address that trades the code for tokens (https).
`userinfo_url`	`string`	No	custom: providers only. The address that returns the person's details (https). Empty: read from the id_token.
`scopes`	`string`	No	custom: providers only. Scopes always asked for, space-separated. The scopes your app sends are added.
`claims`	`object`	No	custom: providers only. The answer field mapping, for example {"id": "sub", "email": "kakao_account.email", "phone": "phone_number"}. Left out: the OpenID standard names.
`claim_map`	`object`	No	custom: providers only. The same as claims, under the name the other tools use.
`token_auth`	`string`, body \| basic	No	custom: providers only. Send client_secret in the body (body, the default) or as HTTP Basic.
`pkce`	`boolean`	No	custom: providers only. On by default; turn it off only if the provider refuses PKCE.
`provider_type`	`string`, oidc \| oauth2	No	custom: providers only. oidc: the id_token is read only after its signature, issuer, audience, expiry and nonce are checked against the issuer's keys (jwks_uri). oauth2 (the default): read through the claims mapping. Left out: the stored value stays.
`discovery_url`	`string`	No	custom: providers only. When the discovery document is not at {issuer}/.well-known/openid-configuration.
`jwks_uri`	`string`	No	custom: providers only. Where an oidc provider's signing keys are. Empty: filled from the discovery document.
`email_optional`	`boolean`	No	custom: providers only. Let people without an email address sign in. Left out: the stored value stays (off for a new provider).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "pattern": "^(google|kakao|naver|apple|github|gitlab|microsoft|facebook|line|discord|x|bitbucket|figma|linkedin_oidc|notion|twitch|slack_oidc|spotify|zoom|azure|keycloak|workos|twitter|slack|custom:[a-z0-9][a-z0-9_-]{0,39})$",
      "description": "The sign-in provider: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack, or custom:<name> for one you register yourself (lowercase letters, digits, - and _, up to 40)."
    },
    "client_id": {
      "type": "string",
      "description": "The client ID from the provider's console."
    },
    "client_secret": {
      "type": "string",
      "description": "An empty string keeps the secret already saved. Required for a new provider."
    },
    "enabled": {
      "type": "boolean",
      "description": "On by default."
    },
    "label": {
      "type": "string",
      "description": "custom: providers only. The name shown on screens."
    },
    "issuer": {
      "type": "string",
      "description": "custom: providers only. The OpenID Connect issuer (for example https://kauth.kakao.com). Empty addresses are filled from its discovery document."
    },
    "authorize_url": {
      "type": "string",
      "description": "custom: providers only. The sign-in page address (https)."
    },
    "token_url": {
      "type": "string",
      "description": "custom: providers only. The address that trades the code for tokens (https)."
    },
    "userinfo_url": {
      "type": "string",
      "description": "custom: providers only. The address that returns the person's details (https). Empty: read from the id_token."
    },
    "scopes": {
      "type": "string",
      "description": "custom: providers only. Scopes always asked for, space-separated. The scopes your app sends are added."
    },
    "claims": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "custom: providers only. The answer field mapping, for example {\"id\": \"sub\", \"email\": \"kakao_account.email\", \"phone\": \"phone_number\"}. Left out: the OpenID standard names."
    },
    "claim_map": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "custom: providers only. The same as claims, under the name the other tools use."
    },
    "token_auth": {
      "type": "string",
      "enum": [
        "body",
        "basic"
      ],
      "description": "custom: providers only. Send client_secret in the body (body, the default) or as HTTP Basic."
    },
    "pkce": {
      "type": "boolean",
      "description": "custom: providers only. On by default; turn it off only if the provider refuses PKCE."
    },
    "provider_type": {
      "type": "string",
      "enum": [
        "oidc",
        "oauth2"
      ],
      "description": "custom: providers only. oidc: the id_token is read only after its signature, issuer, audience, expiry and nonce are checked against the issuer's keys (jwks_uri). oauth2 (the default): read through the claims mapping. Left out: the stored value stays."
    },
    "discovery_url": {
      "type": "string",
      "description": "custom: providers only. When the discovery document is not at {issuer}/.well-known/openid-configuration."
    },
    "jwks_uri": {
      "type": "string",
      "description": "custom: providers only. Where an oidc provider's signing keys are. Empty: filled from the discovery document."
    },
    "email_optional": {
      "type": "boolean",
      "description": "custom: providers only. Let people without an email address sign in. Left out: the stored value stays (off for a new provider)."
    }
  },
  "required": [
    "ref",
    "provider",
    "client_id",
    "client_secret"
  ],
  "additionalProperties": false
}

`set_auth_provider_enabled` Turn social sign-in off and on

Destructive

Turns a provider off or on and keeps its saved credentials. Use it while finding out why a provider misbehaves; turning it back on needs no new secret.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/auth/providers/{provider}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, pattern ^(google\|kakao\|naver\|apple\|github\|gitlab\|microsoft\|facebook\|line\|discord\|x\|bitbucket\|figma\|linkedin_oidc\|notion\|twitch\|slack_oidc\|spotify\|zoom\|azure\|keycloak\|workos\|twitter\|slack\|custom:[a-z0-9][a-z0-9_-]{0,39})$	Yes	The sign-in provider: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack, or custom:<name> for one you register yourself (lowercase letters, digits, - and _, up to 40).
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "pattern": "^(google|kakao|naver|apple|github|gitlab|microsoft|facebook|line|discord|x|bitbucket|figma|linkedin_oidc|notion|twitch|slack_oidc|spotify|zoom|azure|keycloak|workos|twitter|slack|custom:[a-z0-9][a-z0-9_-]{0,39})$",
      "description": "The sign-in provider: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack, or custom:<name> for one you register yourself (lowercase letters, digits, - and _, up to 40)."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "provider",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_auth_provider` Remove social sign-in

Destructive

Removes a provider's settings along with its credentials. To turn it off for a while, use set_auth_provider_enabled. After removing it this way, you have to get the secret again.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/auth/providers/{provider}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, pattern ^(google\|kakao\|naver\|apple\|github\|gitlab\|microsoft\|facebook\|line\|discord\|x\|bitbucket\|figma\|linkedin_oidc\|notion\|twitch\|slack_oidc\|spotify\|zoom\|azure\|keycloak\|workos\|twitter\|slack\|custom:[a-z0-9][a-z0-9_-]{0,39})$	Yes	The sign-in provider: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack, or custom:<name> for one you register yourself (lowercase letters, digits, - and _, up to 40).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "pattern": "^(google|kakao|naver|apple|github|gitlab|microsoft|facebook|line|discord|x|bitbucket|figma|linkedin_oidc|notion|twitch|slack_oidc|spotify|zoom|azure|keycloak|workos|twitter|slack|custom:[a-z0-9][a-z0-9_-]{0,39})$",
      "description": "The sign-in provider: google, kakao, naver, apple, github, gitlab, microsoft, facebook, line, discord, x, bitbucket, figma, linkedin_oidc, notion, twitch, slack_oidc, spotify, zoom, azure, keycloak, workos, twitter, slack, or custom:<name> for one you register yourself (lowercase letters, digits, - and _, up to 40)."
    }
  },
  "required": [
    "ref",
    "provider"
  ],
  "additionalProperties": false
}

`get_smtp_settings` SMTP settings

Read-only

Shows the SMTP server and sender this project's auth emails (sign-up confirmation, password reset, sign-in link, email change, invitation) go out through: the same fields as Supabase's SMTP Settings. The password is never shown; password_hint has its last four characters (when it has at least 8). A last_error means that server refused and the email went out from the platform's address instead. configured false means the platform's address is used.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/auth/smtp`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_smtp_settings` Set SMTP settings

Destructive

Sends auth emails through this project's SMTP server, with the sender name and address you choose. The first time it needs sender_email, host, username and password; after that, only what changes (an empty password keeps the stored one). The server has to be on a public address and use TLS (from the start on 465, STARTTLS otherwise). If it refuses, the email goes out from the platform's address and the reason is kept in last_error. Check it with test_smtp_settings after saving.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/auth/smtp`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`sender_email`	`string`	No	Sender email, e.g. [email protected].
`sender_name`	`string`	No	Sender name, e.g. My Shop.
`host`	`string`	No	The SMTP host, e.g. smtp.sendgrid.net.
`port`	`integer`, 25 \| 465 \| 587 \| 2465 \| 2525	No	Port: 25, 465, 587, 2465 or 2525. Default 587.
`username`	`string`	No	The SMTP username.
`password`	`string`	No	The SMTP password. Empty keeps the stored one.
`minimum_interval_seconds`	`integer`, min 0, max 3600	No	Minimum seconds between two emails to the same address. Default 60.
`rate_limit_per_hour`	`integer`, min 1, max 10000	No	Emails the whole project may send in an hour. Default 100. Past it, requests are refused with over_email_send_rate_limit (429).
`enabled`	`boolean`	No	false keeps the settings and sends from the platform's address.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "sender_email": {
      "type": "string",
      "description": "Sender email, e.g. [email protected]."
    },
    "sender_name": {
      "type": "string",
      "description": "Sender name, e.g. My Shop."
    },
    "host": {
      "type": "string",
      "description": "The SMTP host, e.g. smtp.sendgrid.net."
    },
    "port": {
      "type": "integer",
      "enum": [
        25,
        465,
        587,
        2465,
        2525
      ],
      "description": "Port: 25, 465, 587, 2465 or 2525. Default 587."
    },
    "username": {
      "type": "string",
      "description": "The SMTP username."
    },
    "password": {
      "type": "string",
      "description": "The SMTP password. Empty keeps the stored one."
    },
    "minimum_interval_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3600,
      "description": "Minimum seconds between two emails to the same address. Default 60."
    },
    "rate_limit_per_hour": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Emails the whole project may send in an hour. Default 100. Past it, requests are refused with over_email_send_rate_limit (429)."
    },
    "enabled": {
      "type": "boolean",
      "description": "false keeps the settings and sends from the platform's address."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`test_smtp_settings` Send an SMTP test email

Only adds Reaches outside

Sends one test email through the saved SMTP server. It does not fall back to the platform, so a failure gives the server's own reason. Without to, it goes to the caller's address.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/auth/smtp/test`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`to`	`string`	No	The address to send to. Leave it out for your own.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "to": {
      "type": "string",
      "description": "The address to send to. Leave it out for your own."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`remove_smtp_settings` Remove SMTP settings

Destructive

Removes the SMTP settings along with the password. Auth emails then go out from the platform's address. To pause them, call set_smtp_settings with enabled: false.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/auth/smtp`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_email_templates` Email templates

Read-only

The subject and HTML body of the six auth emails (confirmation, invite, magic_link, recovery, email_change, reauthentication). A type with custom false uses the default wording, in Korean, English or Japanese to match the request. Give type to see just one. The variables are the same as Supabase: {{ .ConfirmationURL }}, {{ .Token }}, {{ .TokenHash }}, {{ .SiteURL }}, {{ .Email }}, {{ .NewEmail }}, {{ .RedirectTo }}, {{ .Data.<key> }}.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/auth/templates`, GET `/projects/{ref}/auth/templates/{type}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`type`	`string`, confirmation \| invite \| magic_link \| recovery \| email_change \| reauthentication \| password_changed \| email_changed \| mfa_enrolled \| mfa_removed \| identity_linked \| identity_unlinked	No	confirmation, invite, magic_link, recovery, email_change or reauthentication.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "type": {
      "type": "string",
      "enum": [
        "confirmation",
        "invite",
        "magic_link",
        "recovery",
        "email_change",
        "reauthentication",
        "password_changed",
        "email_changed",
        "mfa_enrolled",
        "mfa_removed",
        "identity_linked",
        "identity_unlinked"
      ],
      "description": "confirmation, invite, magic_link, recovery, email_change or reauthentication."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_email_template` Save an email template

Destructive

Sets the subject and HTML body of one type. Templates copied from Supabase work as they are. Values are HTML-escaped, and the subject has to be one line. Other syntax such as {{ if }} is refused. reauthentication is stored but not sent yet (reauthenticate is not supported). Check it with preview_email_template before saving.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/auth/templates/{type}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`type`	`string`, confirmation \| invite \| magic_link \| recovery \| email_change \| reauthentication \| password_changed \| email_changed \| mfa_enrolled \| mfa_removed \| identity_linked \| identity_unlinked	Yes	confirmation, invite, magic_link, recovery, email_change or reauthentication.
`subject`	`string`, max length 200	Yes	The subject line, up to 200 characters.
`body`	`string`, max length 50000	Yes	The HTML body, e.g. <a href="{{ .ConfirmationURL }}">Confirm</a>

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "type": {
      "type": "string",
      "enum": [
        "confirmation",
        "invite",
        "magic_link",
        "recovery",
        "email_change",
        "reauthentication",
        "password_changed",
        "email_changed",
        "mfa_enrolled",
        "mfa_removed",
        "identity_linked",
        "identity_unlinked"
      ],
      "description": "confirmation, invite, magic_link, recovery, email_change or reauthentication."
    },
    "subject": {
      "type": "string",
      "maxLength": 200,
      "description": "The subject line, up to 200 characters."
    },
    "body": {
      "type": "string",
      "maxLength": 50000,
      "description": "The HTML body, e.g. <a href=\"{{ .ConfirmationURL }}\">Confirm</a>"
    }
  },
  "required": [
    "ref",
    "type",
    "subject",
    "body"
  ],
  "additionalProperties": false
}

`preview_email_template` Preview an email template

Only adds

Returns how the email looks with sample values (subject, HTML and text). With subject and body it shows those without saving; without them, the saved template or the default wording.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/auth/templates/{type}/preview`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`type`	`string`, confirmation \| invite \| magic_link \| recovery \| email_change \| reauthentication \| password_changed \| email_changed \| mfa_enrolled \| mfa_removed \| identity_linked \| identity_unlinked	Yes	confirmation, invite, magic_link, recovery, email_change or reauthentication.
`subject`	`string`	No	A subject to try without saving.
`body`	`string`	No	A body to try without saving.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "type": {
      "type": "string",
      "enum": [
        "confirmation",
        "invite",
        "magic_link",
        "recovery",
        "email_change",
        "reauthentication",
        "password_changed",
        "email_changed",
        "mfa_enrolled",
        "mfa_removed",
        "identity_linked",
        "identity_unlinked"
      ],
      "description": "confirmation, invite, magic_link, recovery, email_change or reauthentication."
    },
    "subject": {
      "type": "string",
      "description": "A subject to try without saving."
    },
    "body": {
      "type": "string",
      "description": "A body to try without saving."
    }
  },
  "required": [
    "ref",
    "type"
  ],
  "additionalProperties": false
}

`remove_email_template` Restore an email template

Destructive

Removes the template of one type, which goes back to the default wording (Korean, English and Japanese).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/auth/templates/{type}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`type`	`string`, confirmation \| invite \| magic_link \| recovery \| email_change \| reauthentication \| password_changed \| email_changed \| mfa_enrolled \| mfa_removed \| identity_linked \| identity_unlinked	Yes	confirmation, invite, magic_link, recovery, email_change or reauthentication.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "type": {
      "type": "string",
      "enum": [
        "confirmation",
        "invite",
        "magic_link",
        "recovery",
        "email_change",
        "reauthentication",
        "password_changed",
        "email_changed",
        "mfa_enrolled",
        "mfa_removed",
        "identity_linked",
        "identity_unlinked"
      ],
      "description": "confirmation, invite, magic_link, recovery, email_change or reauthentication."
    }
  },
  "required": [
    "ref",
    "type"
  ],
  "additionalProperties": false
}

`get_sms_settings` SMS sign-in settings

Read-only

Shows the SMS account used for phone sign-in (signInWithOtp({ phone })): the provider (platform, solapi, nhn, aligo, twilio), the sender number, the country codes it may send to, the code length and lifetime, and the hourly limit. Credentials show only their last four characters. platform_available has to be true to choose the platform account (₩100 a message, Korea only).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/auth/sms`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_sms_settings` Set up SMS sign-in

Destructive

Saves the SMS account and turns it on. Your own provider needs key, secret and account (they differ by provider: Solapi takes API Key and API Secret, NHN Cloud App Key and Secret Key, Aligo API Key and User ID as account, Twilio and Twilio Verify Account SID as account and Auth Token as secret, MessageBird Access Key as key, Textlocal API Key as key, Vonage API Key as key and API Secret as secret) and a sender registered with it (MessageBird, Textlocal and Vonage also take an alphanumeric sender ID of up to 11 characters; Twilio Verify takes its Verify Service SID, starting VA). Phone confirmations, test numbers and the rest are SMS_* keys of update_auth_config. Credentials left empty keep the stored ones. allowed_countries is only 82 (Korea) by default; adding countries you do not serve exposes you to fraud that makes you text premium-rate numbers abroad.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/auth/sms`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, platform \| solapi \| nhn \| aligo \| twilio \| messagebird \| textlocal \| vonage \| twilio_verify	Yes	platform (the platform account, paid plans only), solapi, nhn, aligo, twilio, messagebird, textlocal, vonage or twilio_verify.
`key`	`string`	No	Solapi API Key, NHN Cloud App Key or Aligo API Key. Empty keeps the stored one.
`secret`	`string`	No	Solapi API Secret, NHN Cloud Secret Key or Twilio Auth Token. Empty keeps the stored one.
`account`	`string`	No	Aligo User ID or Twilio Account SID. Empty keeps the stored one.
`sender`	`string`	No	The sender number, e.g. 01012345678. For Twilio, a +1 number or a Messaging Service SID starting with MG.
`allowed_countries`	`array<string>`	No	Country calling codes it may send to, e.g. ["82"].
`otp_length`	`integer`, min 6, max 10	No	Digits in a code, 6 to 10. Default 6.
`otp_ttl_seconds`	`integer`, min 60, max 3600	No	How long a code is valid, 60 to 3600 seconds. Default 300.
`hourly_limit`	`integer`, min 1, max 100000	No	Most messages the whole project may send in an hour. Default 200.
`template`	`string`	No	The message, containing {{code}}. null for the default wording.
`enabled`	`boolean`	No	On by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "enum": [
        "platform",
        "solapi",
        "nhn",
        "aligo",
        "twilio",
        "messagebird",
        "textlocal",
        "vonage",
        "twilio_verify"
      ],
      "description": "platform (the platform account, paid plans only), solapi, nhn, aligo, twilio, messagebird, textlocal, vonage or twilio_verify."
    },
    "key": {
      "type": "string",
      "description": "Solapi API Key, NHN Cloud App Key or Aligo API Key. Empty keeps the stored one."
    },
    "secret": {
      "type": "string",
      "description": "Solapi API Secret, NHN Cloud Secret Key or Twilio Auth Token. Empty keeps the stored one."
    },
    "account": {
      "type": "string",
      "description": "Aligo User ID or Twilio Account SID. Empty keeps the stored one."
    },
    "sender": {
      "type": "string",
      "description": "The sender number, e.g. 01012345678. For Twilio, a +1 number or a Messaging Service SID starting with MG."
    },
    "allowed_countries": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Country calling codes it may send to, e.g. [\"82\"]."
    },
    "otp_length": {
      "type": "integer",
      "minimum": 6,
      "maximum": 10,
      "description": "Digits in a code, 6 to 10. Default 6."
    },
    "otp_ttl_seconds": {
      "type": "integer",
      "minimum": 60,
      "maximum": 3600,
      "description": "How long a code is valid, 60 to 3600 seconds. Default 300."
    },
    "hourly_limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000,
      "description": "Most messages the whole project may send in an hour. Default 200."
    },
    "template": {
      "type": [
        "string",
        "null"
      ],
      "description": "The message, containing {{code}}. null for the default wording."
    },
    "enabled": {
      "type": "boolean",
      "description": "On by default."
    }
  },
  "required": [
    "ref",
    "provider"
  ],
  "additionalProperties": false
}

`remove_sms_settings` Remove SMS sign-in

Destructive

Removes the SMS account settings along with the credentials. Phone sign-in is then refused with phone_provider_disabled. To turn it off for a while, call set_sms_settings with enabled: false.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/auth/sms`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_sso_providers` SAML SSO

Read-only

Shows the SAML IdPs registered for this project with their email domains, and the two addresses to enter in the IdP (acs_url, entity_id). The app signs in with supabase.auth.signInWithSSO({ domain }).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/auth/sso`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`remove_sso_provider` Remove SAML SSO

Destructive

Removes one IdP. Accounts made through it remain, but can no longer sign in through SSO.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/auth/sso/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_sso_providers.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_sso_providers."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_redirect_urls` Addresses to return to after sign-in

Read-only

The addresses a person can be sent back to after signing in. Nobody is sent to an address not listed here. If sign-in works but goes nowhere, look here first.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/auth/redirect-urls`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`add_redirect_url` Add an address to return to

Only adds

Adds one address to the allow list. Scheme, host and port must all match and the path is not checked, so adding https://app.example.com/callback stores https://app.example.com. A mobile app’s own scheme is accepted too (co.example.app://callback, stored as co.example.app://callback): reverse-DNS, so it has a dot. The response holds the list as actually stored.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/auth/redirect-urls`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`url`	`string`	Yes	The address, for example https://app.example.com.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "url": {
      "type": "string",
      "description": "The address, for example https://app.example.com."
    }
  },
  "required": [
    "ref",
    "url"
  ],
  "additionalProperties": false
}

`remove_redirect_url` Remove an address to return to

Destructive

Takes one address off the allow list. Give it exactly as list_redirect_urls returned it.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/auth/redirect-urls`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`url`	`string`	Yes	The address, as list_redirect_urls returned it.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "url": {
      "type": "string",
      "description": "The address, as list_redirect_urls returned it."
    }
  },
  "required": [
    "ref",
    "url"
  ],
  "additionalProperties": false
}

`remove_user` Remove a user

Destructive

Removes one of the project's users. This cannot be undone. id is the value list_users returned. Use it only when the user clearly asks, and put that user's email (or id) exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/users/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id (UUID) from list_users.
`confirm`	`string`	Yes	The email or id of the user to remove. It must match email or id in list_users.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id (UUID) from list_users."
    },
    "confirm": {
      "type": "string",
      "description": "The email or id of the user to remove. It must match email or id in list_users."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`set_anonymous_sign_in` Turn anonymous sign-in on or off

Destructive

Turns on or off anonymous sign-in, which gives a session straight away without an email. The current state is anonymous_sign_in in list_auth_providers.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/auth/anonymous`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

Storage

Name	Description
`list_buckets`	Buckets
`create_bucket`	Create a bucket
`update_bucket`	Change bucket settings
`empty_bucket`	Empty a bucket
`delete_bucket`	Delete a bucket
`list_objects`	Files
`upload_object`	Upload a file
`download_object`	Download a file
`delete_object`	Delete a file
`create_upload_url`	Make an upload URL
`create_signed_url`	Create a signed URL

`list_buckets` Buckets

Read-only

Returns the storage buckets with the number of files and the size of each.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/buckets`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_bucket` Create a bucket

Only adds

Anyone can read a public bucket. Only the uploader can read a private bucket. file_size_limit and allowed_mime_types set the largest file and the types it takes from the start (later, with update_bucket).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/buckets`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`, pattern ^[a-z0-9][a-z0-9._-]{1,62}$	Yes	The bucket name: 2 to 63 characters of lowercase letters, digits, ". _ -".
`public`	`boolean`	No	Private by default.
`file_size_limit`	`string`	No	The largest one file may be: a number of bytes or a size such as "5MB". null means no limit (up to the plan's).
`allowed_mime_types`	`string`	No	The types it takes, such as ["image/png", "image/*"]. null means every type.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{1,62}$",
      "description": "The bucket name: 2 to 63 characters of lowercase letters, digits, \". _ -\"."
    },
    "public": {
      "type": "boolean",
      "description": "Private by default."
    },
    "file_size_limit": {
      "type": [
        "integer",
        "string",
        "null"
      ],
      "description": "The largest one file may be: a number of bytes or a size such as \"5MB\". null means no limit (up to the plan's)."
    },
    "allowed_mime_types": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "The types it takes, such as [\"image/png\", \"image/*\"]. null means every type."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`update_bucket` Change bucket settings

Destructive

Changes whether a bucket is public, the largest one file may be, and the types it takes. Only what you give changes. Making it public lets anyone download its files, so do it only when the user clearly asks. Files already there stay as they are.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	PATCH `/projects/{ref}/buckets/{bucket}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`public`	`boolean`	No	true for public, false for private.
`file_size_limit`	`string`	No	The largest one file may be: a number of bytes or a size such as "5MB". null means no limit (up to the plan's).
`allowed_mime_types`	`string`	No	The types it takes, such as ["image/png", "image/*"]. null means every type.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "public": {
      "type": "boolean",
      "description": "true for public, false for private."
    },
    "file_size_limit": {
      "type": [
        "integer",
        "string",
        "null"
      ],
      "description": "The largest one file may be: a number of bytes or a size such as \"5MB\". null means no limit (up to the plan's)."
    },
    "allowed_mime_types": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "The types it takes, such as [\"image/png\", \"image/*\"]. null means every type."
    }
  },
  "required": [
    "ref",
    "bucket"
  ],
  "additionalProperties": false
}

`empty_bucket` Empty a bucket

Destructive

Deletes every file in a bucket and keeps the bucket. It cannot be undone, so use it only when the user clearly asks, and put the bucket name exactly in confirm. removed is the number of files deleted.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/buckets/{bucket}/empty`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`confirm`	`string`	Yes	The bucket name. It must be exactly the same as bucket.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "confirm": {
      "type": "string",
      "description": "The bucket name. It must be exactly the same as bucket."
    }
  },
  "required": [
    "ref",
    "bucket",
    "confirm"
  ],
  "additionalProperties": false
}

`delete_bucket` Delete a bucket

Destructive

Deletes an empty bucket. One that still holds files is refused, so empty it first with empty_bucket. It cannot be undone. Use it only when the user clearly asks, and put the bucket name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/buckets/{bucket}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`confirm`	`string`	Yes	The bucket name. It must be exactly the same as bucket.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "confirm": {
      "type": "string",
      "description": "The bucket name. It must be exactly the same as bucket."
    }
  },
  "required": [
    "ref",
    "bucket",
    "confirm"
  ],
  "additionalProperties": false
}

`list_objects` Files

Read-only

Lists one folder of a bucket: its subfolders and files with name, size and type. Choose the folder with prefix (for example avatars/2024/) and find names with search.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/buckets/{bucket}/objects`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`prefix`	`string`	No	The folder to list. Empty for the top.
`search`	`string`	No	Only names containing this.
`limit`	`integer`, min 1, max 1000	No	100 by default.
`offset`	`integer`, min 0	No	How many to skip.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "prefix": {
      "type": "string",
      "description": "The folder to list. Empty for the top."
    },
    "search": {
      "type": "string",
      "description": "Only names containing this."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "100 by default."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "How many to skip."
    }
  },
  "required": [
    "ref",
    "bucket"
  ],
  "additionalProperties": false
}

`upload_object` Upload a file

Destructive

Uploads one file to a bucket (up to 2MB). Text goes as it is; for binary set encoding to base64 and put base64 in content. A file with the same name is refused, unless upsert is true, which replaces it. The bucket's size and type limits apply. Upload bigger files through the storage API (/storage/v1).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/buckets/{bucket}/objects`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`name`	`string`	Yes	The path inside the bucket. For example: docs/readme.txt
`content`	`string`	Yes	The file content (base64 when encoding is base64).
`encoding`	`string`, utf-8 \| base64	No	utf-8 by default.
`content_type`	`string`	No	For example image/png. Empty means text or application/octet-stream.
`upsert`	`boolean`	No	With true, a file with the same name is replaced.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "name": {
      "type": "string",
      "description": "The path inside the bucket. For example: docs/readme.txt"
    },
    "content": {
      "type": "string",
      "description": "The file content (base64 when encoding is base64)."
    },
    "encoding": {
      "type": "string",
      "enum": [
        "utf-8",
        "base64"
      ],
      "description": "utf-8 by default."
    },
    "content_type": {
      "type": "string",
      "description": "For example image/png. Empty means text or application/octet-stream."
    },
    "upsert": {
      "type": "boolean",
      "description": "With true, a file with the same name is replaced."
    }
  },
  "required": [
    "ref",
    "bucket",
    "name",
    "content"
  ],
  "additionalProperties": false
}

`download_object` Download a file

Read-only

Returns the content of one file (up to 2MB): text as utf-8, binary as base64. For bigger files make an address with create_signed_url.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/buckets/{bucket}/object`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`name`	`string`	Yes	The path inside the bucket.
`encoding`	`string`, utf-8 \| base64	No	Empty chooses by the content.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "name": {
      "type": "string",
      "description": "The path inside the bucket."
    },
    "encoding": {
      "type": "string",
      "enum": [
        "utf-8",
        "base64"
      ],
      "description": "Empty chooses by the content."
    }
  },
  "required": [
    "ref",
    "bucket",
    "name"
  ],
  "additionalProperties": false
}

`delete_object` Delete a file

Destructive

Removes one file from a bucket. This cannot be undone.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/buckets/{bucket}/object`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`name`	`string`	Yes	The path inside the bucket.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "name": {
      "type": "string",
      "description": "The path inside the bucket."
    }
  },
  "required": [
    "ref",
    "bucket",
    "name"
  ],
  "additionalProperties": false
}

`create_upload_url` Make an upload URL

Destructive

Makes a URL to upload one file larger than 2MB, such as an image or a video. The file itself is not sent through this tool. PUT the file bytes as the body to the returned url, with its type (image/png, video/mp4 and so on) as content-type, as in the curl of example. The URL works for that one name for 2 hours. A file larger than max_bytes, or of a type not in allowed_mime_types, is refused; for a file larger than max_bytes use the resumable (TUS) upload in blackwall://storage. For a public bucket, public_url is its public address once uploaded.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/buckets/{bucket}/upload-urls`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	A bucket name from list_buckets.
`name`	`string`	Yes	The path inside the bucket, such as videos/intro.mp4.
`upsert`	`boolean`	No	When true, replaces a file with the same name. By default that is refused.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "A bucket name from list_buckets."
    },
    "name": {
      "type": "string",
      "description": "The path inside the bucket, such as videos/intro.mp4."
    },
    "upsert": {
      "type": "boolean",
      "description": "When true, replaces a file with the same name. By default that is refused."
    }
  },
  "required": [
    "ref",
    "bucket",
    "name"
  ],
  "additionalProperties": false
}

`create_signed_url` Create a signed URL

Destructive

Makes an address anyone can download one file of a private bucket from for a set time (1 hour by default, 7 days at most). Whoever has the address downloads without signing in, so make only what you need.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/buckets/{bucket}/signed-urls`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	The bucket name, from list_buckets.
`name`	`string`	Yes	The path inside the bucket.
`expires_in`	`integer`, min 1, max 604800	No	Seconds it stays open. 3600 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket name, from list_buckets."
    },
    "name": {
      "type": "string",
      "description": "The path inside the bucket."
    },
    "expires_in": {
      "type": "integer",
      "minimum": 1,
      "maximum": 604800,
      "description": "Seconds it stays open. 3600 by default."
    }
  },
  "required": [
    "ref",
    "bucket",
    "name"
  ],
  "additionalProperties": false
}

Deployments and repositories

Name	Description
`list_deployments`	Deployments
`get_deployment`	One deployment and its build log
`redeploy`	Redeploy
`promote_deployment`	Promote a preview to production
`rollback_deployment`	Roll back production
`deploy_source`	Deploy an uploaded source
`create_source_upload_url`	Make an upload URL for a deployment archive
`list_deploy_hooks`	Deploy hooks
`create_deploy_hook`	Create a deploy hook
`remove_deploy_hook`	Remove a deploy hook
`list_apps`	Connected repositories and build settings
`delete_app`	Delete an app
`update_app`	Change build settings
`get_preview_protection`	Preview protection
`set_preview_protection`	Change preview protection
`get_branch_previews`	Branch previews
`set_branch_previews`	Change branch previews
`list_env_vars`	Environment variables
`set_env_vars`	Save environment variables
`remove_env_var`	Remove an environment variable
`list_git_access`	Git connection
`set_repo_token`	Save a repository token
`remove_repo_token`	Remove a repository token
`add_repository`	Add a repository
`list_importable_repositories`	Find repositories to import
`import_repository`	Import a repository
`disconnect_repository`	Disconnect a repository
`set_checks_on_server`	Run checks on One Server
`unlink_github_app`	Disconnect a GitHub account
`get_server_memory`	Server memory
`set_server_memory`	Change server memory
`get_concurrent_builds`	Concurrent builds
`set_concurrent_builds`	Change concurrent builds
`list_gpu`	GPU jobs and servers
`create_gpu_job`	Create a GPU job
`get_gpu_job`	A GPU job
`cancel_gpu_job`	Stop a GPU job
`create_gpu_server`	Create a GPU server
`stop_gpu_server`	Stop a GPU server
`delete_gpu_server`	Delete a GPU server
`create_gpu_volume`	Create GPU storage
`delete_gpu_volume`	Delete GPU storage
`list_deleted_deployments`	Recently deleted deployments
`delete_deployment`	Delete a deployment
`restore_deployment`	Restore a deployment
`list_volumes`	Volumes
`create_volume`	Create a volume
`resize_volume`	Grow a volume
`delete_volume`	Delete a volume
`create_volume_backup`	Back up a volume
`restore_volume_backup`	Restore a volume

`list_deployments` Deployments

Read-only

Shows this project's recent deployments, newest first: status (queued, building, ready, error), environment, addresses, branch, commit and the reason it failed. Deleted deployments are left out (list_deleted_deployments shows them). When next_before is set, pass it as before for the next page. url is the deployment's own dpl- address, production_url the production address, preview_url its branch's preview address. preview_protection says who can open a preview address (members: organization members only, the default / password / off: anyone); null for production, whose address is always public, though with protection on a dpl- address is protected even for a production build.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/deployments`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`limit`	`integer`, min 1, max 100	No	Default 20.
`before`	`string`, pattern ^dpl-[0-9a-f]{16}$	No	Start after this deployment (older ones). next_before from the previous page.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Default 20."
    },
    "before": {
      "type": "string",
      "pattern": "^dpl-[0-9a-f]{16}$",
      "description": "Start after this deployment (older ones). next_before from the previous page."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_deployment` One deployment and its build log

Read-only

Shows the status of one deployment, its addresses and the end of its build log. When a build failed, the reason is usually in the last few lines of the log. Environment variable values the customer set are masked as ••••••. url is the deployment's own dpl- address; production_url or preview_url is the production or branch address. preview_protection says who can open a preview address (members: organization members only, the default / password / off: anyone); null for production, whose address is always public. With wait (seconds) it waits for the build to finish.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/deployments/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The deployment name, starting with dpl-.
`tail`	`integer`, min 1, max 5000	No	How many lines from the end of the build log. Default 200.
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The deployment name, starting with dpl-."
    },
    "tail": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5000,
      "description": "How many lines from the end of the build log. Default 200."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`redeploy` Redeploy

Destructive

Builds the same commit as one deployment again, to the same environment. Use it to rerun a build that failed for a reason unrelated to the commit (an environment variable added later, a package registry that was briefly down). Only owners and admins can deploy to production. The answer has the new deployment's addresses (url, preview_url or production_url) and the security check (advisors).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/deployments/{id}/redeploy`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The deployment name, starting with dpl-.
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe.
`block_on_advisors`	`boolean`	No	With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The deployment name, starting with dpl-."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe."
    },
    "block_on_advisors": {
      "type": "boolean",
      "description": "With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`promote_deployment` Promote a preview to production

Destructive

Moves a finished preview deployment to production. The same commit is built again with the production environment variables, and when it finishes the production address points to the result. The preview build is not reused so that preview keys never reach production. Given a finished production deployment, the production address points to it now without a rebuild, and a hold a rollback put on production (production_held) is lifted; give the one serving now to lift the hold alone. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer, `project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/deployments/{id}/promote`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The dpl- name of the deployment to promote: usually a preview, or a production deployment to lift a hold.
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe.
`block_on_advisors`	`boolean`	No	With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The dpl- name of the deployment to promote: usually a preview, or a production deployment to lift a hold."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe."
    },
    "block_on_advisors": {
      "type": "boolean",
      "description": "With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`rollback_deployment` Roll back production

Destructive

Points the production address straight back to a production deployment that served before. Nothing is rebuilt, and the switch takes a few seconds. Custom domains follow. The answer has that deployment's url and production_url. Production is then held (production_held): new production builds are built but not served until you promote one with promote_deployment. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/deployments/{id}/rollback`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The dpl- name of the production deployment to go back to.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The dpl- name of the production deployment to go back to."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`deploy_source` Deploy an uploaded source

Destructive

Deploys an archive already uploaded with POST /deployments/sources (or oneend deploy), chosen by its source (SHA-256). Use it to deploy the same source to production after checking it as a preview. The other arguments are as for deploy_files.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/deployments`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`source`	`string`, pattern ^[0-9a-f]{64}$	Yes	The source returned by the upload (a 64 character SHA-256).
`target`	`string`, preview \| production	No	preview by default.
`prebuilt`	`boolean`	No	With true, nothing is built and the files are served as they are.
`app`	`string`	No	The app to deploy (a name from list_apps). Leave it out when there is one app.
`branch`	`string`	No	The name of the preview, which becomes its address. preview by default.
`message`	`string`	No	A note to show in the deployment list (optional).
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe.
`block_on_advisors`	`boolean`	No	With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "source": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "The source returned by the upload (a 64 character SHA-256)."
    },
    "target": {
      "type": "string",
      "enum": [
        "preview",
        "production"
      ],
      "description": "preview by default."
    },
    "prebuilt": {
      "type": "boolean",
      "description": "With true, nothing is built and the files are served as they are."
    },
    "app": {
      "type": "string",
      "description": "The app to deploy (a name from list_apps). Leave it out when there is one app."
    },
    "branch": {
      "type": "string",
      "description": "The name of the preview, which becomes its address. preview by default."
    },
    "message": {
      "type": "string",
      "description": "A note to show in the deployment list (optional)."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe."
    },
    "block_on_advisors": {
      "type": "boolean",
      "description": "With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back."
    }
  },
  "required": [
    "ref",
    "source"
  ],
  "additionalProperties": false
}

`create_source_upload_url` Make an upload URL for a deployment archive

Only adds

For deploying a site too large for deploy_files (over 3MB) without a repository: makes a URL to upload one archive (.zip, .tar, .tar.gz) to. The archive itself is not sent through this tool. PUT the archive as the body to the returned url (as in the curl of example, with no token); the answer carries source, and deploy_source with that source deploys it. The URL works for this project for 1 hour and takes up to max_bytes.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/deployments/sources/upload-urls`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_deploy_hooks` Deploy hooks

Read-only

Shows the deploy hooks and their addresses. A POST to an address builds the latest commit of its branch, so the address itself is a secret. A read-only token sees only the last four characters of each address (secret_hidden); a token with write access sees all of it.

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/deploy-hooks`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_deploy_hook` Create a deploy hook

Only adds

Creates an address that triggers a build without a push. Have a CMS call it when a post is published, or a scheduled job. Only owners and admins can create a hook for the production branch.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/deploy-hooks`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`branch`	`string`	Yes	The branch whose latest commit is built.
`name`	`string`	No	A name to recognise the hook by.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "branch": {
      "type": "string",
      "description": "The branch whose latest commit is built."
    },
    "name": {
      "type": "string",
      "description": "A name to recognise the hook by."
    }
  },
  "required": [
    "ref",
    "app",
    "branch"
  ],
  "additionalProperties": false
}

`remove_deploy_hook` Remove a deploy hook

Destructive

Removes a deploy hook. Whatever called its address no longer causes a deployment.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/deploy-hooks/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_deploy_hooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_deploy_hooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_apps` Connected repositories and build settings

Read-only

For each repository that deploys to this project, shows the production branch, the folder to build (root_directory), the framework preset (framework; null means detect automatically) and the build command, output directory and install command overrides (build_command, output_directory, install_command; null means the preset default). detected_framework is what the latest build used, and frameworks lists the presets you can choose. A repository appears on its first push.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/apps`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`delete_app` Delete an app

Destructive

Deletes one app of the project (an app whose folder a monorepo removed). Its addresses stop answering at once, its builds in progress are cancelled, and its deployments are deleted with no restore, their files gone within minutes. A push no longer builds it even if the folder is still in the repository. It cannot be undone. The project's own site, an app with domains and an app with disks are refused, with what to do first. Use it only when the user clearly asks, and put the app name exactly in confirm. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/apps/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The name from list_apps.
`confirm`	`string`	Yes	The app name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "confirm": {
      "type": "string",
      "description": "The app name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`update_app` Change build settings

Destructive

Changes one repository's production branch, folder to build, framework preset, build command, output directory or install command. For a monorepo, put the app folder (for example apps/web) in root_directory. Values you leave out stay as they are; null puts one back to detect automatically (the preset default). An empty command skips that step. If the repository's blackwall.json sets the same item, its value comes first. Takes effect from the next deployment, except port (the port the server listens on), which restarts the server within a minute. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/apps/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The name from list_apps.
`production_branch`	`string`	No	The branch that deploys to production.
`root_directory`	`string`	No	A path relative to the repository. "." for the whole repository.
`framework`	`string`, auto \| next \| vite \| astro \| sveltekit \| nuxt \| remix \| react-router \| angular \| create-react-app \| gatsby \| docusaurus \| vitepress \| eleventy \| hugo \| solidstart \| qwik \| node \| static \| docker \| null	No	The framework preset. "auto" or null detects it on every build. "static" is Other (static files).
`build_command`	`string`	No	Build command override, one line. null for the preset default; an empty string skips the build.
`output_directory`	`string`	No	Output directory override: a relative path inside root_directory (for example dist). null for the preset default.
`install_command`	`string`	No	Install command override, one line. null for the default that matches the lockfile; an empty string skips the install.
`run_as`	`string`, platform \| image	No	Who the server runs as. platform (the default) is an ordinary user (10001); image is the user the image names, root included, inside a gVisor sandbox. Use image only for Dockerfile apps that must start as root, like the official WordPress image. The server restarts within a minute, without a rebuild.
`port`	`string`, min 1, max 65535	No	The port the server listens on inside its container. null for the image's EXPOSE, or 3000. A change restarts the server within a minute, with no new deployment.
`build_machine`	`string`, standard \| enhanced \| turbo \| xl \| max	No	The build machine size. standard is 2 CPU and 6 GB, enhanced 4 CPU and 12 GB (twice the build minutes), turbo 8 CPU and 24 GB (four times), xl 16 CPU and 48 GB (eight times), max 32 CPU and 96 GB (sixteen times). xl and max come with the Enterprise plan. Choose a bigger one when a build runs out of memory. Takes effect from the next build.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "production_branch": {
      "type": "string",
      "description": "The branch that deploys to production."
    },
    "root_directory": {
      "type": "string",
      "description": "A path relative to the repository. \".\" for the whole repository."
    },
    "framework": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "auto",
        "next",
        "vite",
        "astro",
        "sveltekit",
        "nuxt",
        "remix",
        "react-router",
        "angular",
        "create-react-app",
        "gatsby",
        "docusaurus",
        "vitepress",
        "eleventy",
        "hugo",
        "solidstart",
        "qwik",
        "node",
        "static",
        "docker",
        null
      ],
      "description": "The framework preset. \"auto\" or null detects it on every build. \"static\" is Other (static files)."
    },
    "build_command": {
      "type": [
        "string",
        "null"
      ],
      "description": "Build command override, one line. null for the preset default; an empty string skips the build."
    },
    "output_directory": {
      "type": [
        "string",
        "null"
      ],
      "description": "Output directory override: a relative path inside root_directory (for example dist). null for the preset default."
    },
    "install_command": {
      "type": [
        "string",
        "null"
      ],
      "description": "Install command override, one line. null for the default that matches the lockfile; an empty string skips the install."
    },
    "run_as": {
      "type": "string",
      "enum": [
        "platform",
        "image"
      ],
      "description": "Who the server runs as. platform (the default) is an ordinary user (10001); image is the user the image names, root included, inside a gVisor sandbox. Use image only for Dockerfile apps that must start as root, like the official WordPress image. The server restarts within a minute, without a rebuild."
    },
    "port": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 65535,
      "description": "The port the server listens on inside its container. null for the image's EXPOSE, or 3000. A change restarts the server within a minute, with no new deployment."
    },
    "build_machine": {
      "type": "string",
      "enum": [
        "standard",
        "enhanced",
        "turbo",
        "xl",
        "max"
      ],
      "description": "The build machine size. standard is 2 CPU and 6 GB, enhanced 4 CPU and 12 GB (twice the build minutes), turbo 8 CPU and 24 GB (four times), xl 16 CPU and 48 GB (eight times), max 32 CPU and 96 GB (sixteen times). xl and max come with the Enterprise plan. Choose a bigger one when a build runs out of memory. Takes effect from the next build."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`get_preview_protection` Preview protection

Read-only

Shows who can open deployments that are not production (branch previews, per-deployment addresses): off, members (organisation members only), password. Also returns which addresses are protected (scope), addresses let in without signing in (trusted_ips), paths that pass unchecked (options_paths), bypass keys (bypass_secrets, only their last four characters) and share links (share_links).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/preview-protection`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_preview_protection` Change preview protection

Destructive

Changes who can open previews. members means organisation members signed in to the console, password means one shared password (a password of at least 8 characters is needed the first time), off means anyone. The production address and connected domains are always public. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/preview-protection`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`mode`	`string`, off \| members \| password	Yes	off, members or password.
`password`	`string`	No	When mode is password. Empty keeps the password already set.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "mode": {
      "type": "string",
      "enum": [
        "off",
        "members",
        "password"
      ],
      "description": "off, members or password."
    },
    "password": {
      "type": "string",
      "description": "When mode is password. Empty keeps the password already set."
    }
  },
  "required": [
    "ref",
    "mode"
  ],
  "additionalProperties": false
}

`get_branch_previews` Branch previews

Read-only

Shows whether a push to a branch other than production builds a preview in this project's organization (branch_previews). false means only what reaches the production branch (usually main) is built.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/branch-previews`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_branch_previews` Change branch previews

Destructive

Turns preview builds for branch pushes on or off for the whole organization. false builds only what reaches the production branch (usually main); a skipped push stays in the deployment history as skipped. Redeploys, uploads and deploy hooks still build. Applies to every project in the organization. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/branch-previews`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true builds a preview for every branch push.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true builds a preview for every branch push."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

`list_env_vars` Environment variables

Read-only

The environment variables a deployed app gets when it is built and run. The same name can exist separately for production and preview. A sensitive value is not returned; only its last four characters come as value_hint. readable false means the value cannot be opened and is left out of builds, so save it again. automatic lists the automatic variables that are set without being saved: SUPABASE_URL, NEXT_PUBLIC_SUPABASE_URL, SUPABASE_ANON_KEY, NEXT_PUBLIC_SUPABASE_ANON_KEY, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and SUPABASE_SERVICE_ROLE_KEY, the names an app moved from Supabase already reads. available_in says where each is available: the public ones in build and runtime (build, runtime), SUPABASE_SERVICE_ROLE_KEY in runtime only (runtime: servers, middleware, functions), never in builds. A variable saved under the same name comes first, and a saved value goes to builds too (overridden_in).

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/env`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_env_vars` Save environment variables

Destructive

Saves one or more environment variables. Give them one by one in variables, or the whole content of a .env file in dotenv. A name that exists is overwritten. If any one is invalid, nothing is saved, except that a dotenv line with a name the platform sets is skipped and listed in skipped. PORT, HOST, HOSTNAME, HOME and names starting with BLACKWALL_ are used by the platform and cannot be set. Builds get CI=1 unless you set CI yourself (CI=false, for example). Changed values are used from the next deployment. Without sensitive, a name that looks like a secret (API_KEY, STRIPE_SECRET, DATABASE_URL and the like) is saved as sensitive and cannot be read back (sensitive_keys). Only owners and admins can change production values.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/env`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`variables`	`array<object>`	No	A list of { key, value }.
`dotenv`	`string`	No	The content of a .env file. Comments and blank lines are skipped.
`targets`	`array<string>`, production \| preview \| development, min items 1	Yes	preview means the deployments of every branch that is not the production branch.
`sensitive`	`boolean`	No	true: the value cannot be read again after it is saved. Not given: only a variable whose name contains SECRET, TOKEN, PASSWORD, PRIVATE, DSN, DATABASE_URL or KEY_, or ends in _KEY, is saved as sensitive. false: every value stays readable.
`app`	`string`	No	The app name (name from list_apps) to save them for that app only, over a project variable of the same name. Empty means every app of the project.
`branch`	`string`, max length 200	No	A git branch name, to save them for that branch's previews only. targets must be preview alone. With app, they go to that app on that branch only. Empty means every preview.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "variables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "value"
        ],
        "additionalProperties": false
      },
      "description": "A list of { key, value }."
    },
    "dotenv": {
      "type": "string",
      "description": "The content of a .env file. Comments and blank lines are skipped."
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "production",
          "preview",
          "development"
        ]
      },
      "minItems": 1,
      "description": "preview means the deployments of every branch that is not the production branch."
    },
    "sensitive": {
      "type": "boolean",
      "description": "true: the value cannot be read again after it is saved. Not given: only a variable whose name contains SECRET, TOKEN, PASSWORD, PRIVATE, DSN, DATABASE_URL or KEY_, or ends in _KEY, is saved as sensitive. false: every value stays readable."
    },
    "app": {
      "type": "string",
      "description": "The app name (name from list_apps) to save them for that app only, over a project variable of the same name. Empty means every app of the project."
    },
    "branch": {
      "type": "string",
      "maxLength": 200,
      "description": "A git branch name, to save them for that branch's previews only. targets must be preview alone. With app, they go to that app on that branch only. Empty means every preview."
    }
  },
  "required": [
    "ref",
    "targets"
  ],
  "additionalProperties": false
}

`remove_env_var` Remove an environment variable

Destructive

Removes one environment variable from either production or preview. If the value was sensitive, it cannot be recovered.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/env/{target}/{key}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`	Yes	The variable name.
`target`	`string`, production \| preview \| development	Yes	production or preview.
`app`	`string`	No	The app name, for a variable saved for one app only. Empty means the project's variable.
`branch`	`string`, max length 200	No	The git branch, for a variable saved for one branch's previews only (branch in list_env_vars).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "description": "The variable name."
    },
    "target": {
      "type": "string",
      "enum": [
        "production",
        "preview",
        "development"
      ],
      "description": "production or preview."
    },
    "app": {
      "type": "string",
      "description": "The app name, for a variable saved for one app only. Empty means the project's variable."
    },
    "branch": {
      "type": "string",
      "maxLength": 200,
      "description": "The git branch, for a variable saved for one branch's previews only (branch in list_env_vars)."
    }
  },
  "required": [
    "ref",
    "key",
    "target"
  ],
  "additionalProperties": false
}

`list_git_access` Git connection

Read-only

The same as "Git connection" in the console. Shows the repositories this project deploys (connected: whether a push deploys it), the GitHub accounts linked (github_accounts) how private repositories are fetched (the last four characters of a GitHub or GitLab token, a GitHub App installation), and for each GitHub repository whether it runs its checks on One Server (checks_on_server: available, enabled, state, permission_url, workflows_using). If a private repository build fails at the fetch step, look here first.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/git`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_repo_token` Save a repository token

Destructive

Saves an access token used to fetch private repositories (read access is enough). It is sealed and never shown again. For a self-hosted GitLab, put https://gitlab.example.com in gitlab_base. Used from the next build. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/git/tokens/{provider}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, github \| gitlab \| bitbucket	Yes	github or gitlab.
`token`	`string`	Yes	The access token. Read access is enough.
`gitlab_base`	`string`	No	The address of a self-hosted GitLab. Empty for gitlab.com.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "enum": [
        "github",
        "gitlab",
        "bitbucket"
      ],
      "description": "github or gitlab."
    },
    "token": {
      "type": "string",
      "description": "The access token. Read access is enough."
    },
    "gitlab_base": {
      "type": "string",
      "description": "The address of a self-hosted GitLab. Empty for gitlab.com."
    }
  },
  "required": [
    "ref",
    "provider",
    "token"
  ],
  "additionalProperties": false
}

`remove_repo_token` Remove a repository token

Destructive

Removes the saved token. A connected GitHub App installation is kept. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/git/tokens/{provider}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, github \| gitlab \| bitbucket	Yes	github or gitlab.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "enum": [
        "github",
        "gitlab",
        "bitbucket"
      ],
      "description": "github or gitlab."
    }
  },
  "required": [
    "ref",
    "provider"
  ],
  "additionalProperties": false
}

`add_repository` Add a repository

Only adds Reaches outside

Attaches a repository to this project before its first push. Pushes that come through the GitHub App then come to this project, and create_deploy_hook can build without a push. repo is owner/name for GitHub and group/name for GitLab. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/git/repos`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`provider`	`string`, github \| gitlab \| bitbucket	Yes	github or gitlab.
`repo`	`string`	Yes	owner/name for GitHub, group/name for GitLab.
`branch`	`string`	No	The production branch. Empty means main.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "provider": {
      "type": "string",
      "enum": [
        "github",
        "gitlab",
        "bitbucket"
      ],
      "description": "github or gitlab."
    },
    "repo": {
      "type": "string",
      "description": "owner/name for GitHub, group/name for GitLab."
    },
    "branch": {
      "type": "string",
      "description": "The production branch. Empty means main."
    }
  },
  "required": [
    "ref",
    "provider",
    "repo"
  ],
  "additionalProperties": false
}

`list_importable_repositories` Find repositories to import

Read-only Reaches outside

The same as the import list under Git connection in the console. Shows up to 50 repositories the GitHub App can see on a linked GitHub account, most recently pushed first. With query it searches all of them, also past 300. If you just added a repository on GitHub, pass refresh: true. With several accounts, choose one with installation (github_accounts in list_git_access). Only owners and admins can see it.

Name	Description
Token scope	`read`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/git/importable`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`query`	`string`	No	Part of a repository name. Empty lists the most recently pushed.
`installation`	`integer`	No	Which GitHub account's installation. Empty means the default account.
`refresh`	`boolean`	No	Ask GitHub again, past its one-minute cache.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "query": {
      "type": "string",
      "description": "Part of a repository name. Empty lists the most recently pushed."
    },
    "installation": {
      "type": "integer",
      "description": "Which GitHub account's installation. Empty means the default account."
    },
    "refresh": {
      "type": "boolean",
      "description": "Ask GitHub again, past its one-minute cache."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`import_repository` Import a repository

Destructive Reaches outside

The same as [Connect and deploy] in the console. Connects a repository the GitHub App can see to this project and starts the first deployment from the newest commit of its production branch. An empty branch means the repository's default branch. Build settings (framework and the rest) and environment variables (a .env text in dotenv) are saved before the first build. Importing a disconnected repository again connects it again with its settings. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/git/import`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`repo`	`string`	Yes	owner/name, as list_importable_repositories gives it.
`branch`	`string`	No	The production branch. Empty means the repository's default branch.
`root_directory`	`string`	No	The app folder of a monorepo (for example apps/web). Empty means the top of the repository. Another folder of a repository already connected adds a new app.
`app`	`string`	No	The app name ("App name" in the console). Empty means the folder name, or the repository name. An app of that name has its settings changed.
`installation`	`integer`	No	Which GitHub account's installation fetches it. Empty means the account that owns the repository.
`framework`	`string`, auto \| next \| vite \| astro \| sveltekit \| nuxt \| remix \| react-router \| angular \| create-react-app \| gatsby \| docusaurus \| vitepress \| eleventy \| hugo \| solidstart \| qwik \| node \| static \| docker \| null	No	The framework preset. Empty or "auto" detects it.
`build_command`	`string`	No	Build command override, one line. An empty string skips the build.
`output_directory`	`string`	No	Output directory override (for example dist).
`install_command`	`string`	No	Install command override, one line.
`dotenv`	`string`	No	The contents of a .env file. Saved for production and previews.
`sensitive`	`boolean`	No	The dotenv values cannot be viewed again once saved.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "repo": {
      "type": "string",
      "description": "owner/name, as list_importable_repositories gives it."
    },
    "branch": {
      "type": "string",
      "description": "The production branch. Empty means the repository's default branch."
    },
    "root_directory": {
      "type": "string",
      "description": "The app folder of a monorepo (for example apps/web). Empty means the top of the repository. Another folder of a repository already connected adds a new app."
    },
    "app": {
      "type": "string",
      "description": "The app name (\"App name\" in the console). Empty means the folder name, or the repository name. An app of that name has its settings changed."
    },
    "installation": {
      "type": "integer",
      "description": "Which GitHub account's installation fetches it. Empty means the account that owns the repository."
    },
    "framework": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "auto",
        "next",
        "vite",
        "astro",
        "sveltekit",
        "nuxt",
        "remix",
        "react-router",
        "angular",
        "create-react-app",
        "gatsby",
        "docusaurus",
        "vitepress",
        "eleventy",
        "hugo",
        "solidstart",
        "qwik",
        "node",
        "static",
        "docker",
        null
      ],
      "description": "The framework preset. Empty or \"auto\" detects it."
    },
    "build_command": {
      "type": [
        "string",
        "null"
      ],
      "description": "Build command override, one line. An empty string skips the build."
    },
    "output_directory": {
      "type": [
        "string",
        "null"
      ],
      "description": "Output directory override (for example dist)."
    },
    "install_command": {
      "type": [
        "string",
        "null"
      ],
      "description": "Install command override, one line."
    },
    "dotenv": {
      "type": "string",
      "description": "The contents of a .env file. Saved for production and previews."
    },
    "sensitive": {
      "type": "boolean",
      "description": "The dotenv values cannot be viewed again once saved."
    }
  },
  "required": [
    "ref",
    "repo"
  ],
  "additionalProperties": false
}

`disconnect_repository` Disconnect a repository

Destructive

The same as [Disconnect] on a repository under Git connection in the console. Pushes to this repository no longer deploy. The deployment serving now, the history, build settings and environment variables stay, and import_repository with the same repository connects it again. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	DELETE `/projects/{ref}/git/repos/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	repositories[].name from list_git_access.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "repositories[].name from list_git_access."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`set_checks_on_server` Run checks on One Server

Destructive

Turns on or off running a connected GitHub repository's GitHub Actions checks on One Server's machines, as [Run checks on One Server] under Git connection in the console does. On saves the repository variable POOL_RUNNER: a job that says runs-on: ${{ vars.POOL_RUNNER || 'ubuntu-latest' }} runs on One Server. Off deletes it, and jobs go back to GitHub's machines. When state is needs_permission, approve the GitHub App's new permissions at permission_url and it turns on by itself. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/git/checks/{repo}/{repo}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`repo`	`string`	Yes	repositories[].repo (owner/name) from list_git_access.
`enabled`	`boolean`	Yes	true turns it on, false turns it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "repo": {
      "type": "string",
      "description": "repositories[].repo (owner/name) from list_git_access."
    },
    "enabled": {
      "type": "boolean",
      "description": "true turns it on, false turns it off."
    }
  },
  "required": [
    "ref",
    "repo",
    "enabled"
  ],
  "additionalProperties": false
}

`unlink_github_app` Disconnect a GitHub account

Destructive

Disconnects a GitHub account (a GitHub App installation) from this project: the one named by installation, or every one when it is empty. Saved tokens and the App installation on GitHub are kept. Connecting needs a person to confirm it on GitHub, so it can only be done in the console. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/git/github-app`, DELETE `/projects/{ref}/git/github-app/{installation}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`installation`	`integer`	No	github_accounts[].installation_id from list_git_access. Empty means all.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "installation": {
      "type": "integer",
      "description": "github_accounts[].installation_id from list_git_access. Empty means all."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_server_memory` Server memory

Read-only

The memory (MB) and CPUs this project's server deployments run with, the most its plan allows, the price per GB-hour and what a server held all month costs. Servers at production and branch addresses always run, requests or not (minimum one instance), so that is what one of them costs a month.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/server-memory`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_server_memory` Change server memory

Destructive

Chooses the memory this project's server deployments (Node servers, workers) run with: 512, 1024, 2048 or 4096 MB. Above 1024 MB they get two CPUs. Metered as runtime_gb_hour. Servers restart with the new size within a minute. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/server-memory`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`memory_mb`	`integer`, 512 \| 1024 \| 2048 \| 4096	Yes	Memory in MB: 512, 1024, 2048 or 4096.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "memory_mb": {
      "type": "integer",
      "enum": [
        512,
        1024,
        2048,
        4096
      ],
      "description": "Memory in MB: 512, 1024, 2048 or 4096."
    }
  },
  "required": [
    "ref",
    "memory_mb"
  ],
  "additionalProperties": false
}

`get_concurrent_builds` Concurrent builds

Read-only

How many of this project's builds may run at once. null means as many as the builders allow.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/concurrent-builds`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_concurrent_builds` Change concurrent builds

Destructive

Sets how many of this project's builds may run at once, 1 to 20, or null for no limit. Builds over the limit wait in the queue and start when one ahead of them finishes; a waiting build is not billed for build minutes. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/concurrent-builds`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`concurrent_builds`	`string`, min 1, max 20	Yes	A whole number from 1 to 20, or null for no limit.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "concurrent_builds": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 20,
      "description": "A whole number from 1 to 20, or null for no limit."
    }
  },
  "required": [
    "ref",
    "concurrent_builds"
  ],
  "additionalProperties": false
}

`list_gpu` GPU jobs and servers

Read-only

This project's GPU jobs (the latest 50), GPU servers and GPU storage, the hourly price of each card and the price of a GB-month of storage, the regions and data centers to choose from, and how many GPUs the organisation may run at once and runs now. The free plan has no GPUs.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/gpu`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_gpu_job` Create a GPU job

Destructive

Rents a GPU and runs a command in a public container image to its end (training, a batch). The GPU is let go when the command ends or max_minutes passes, and the seconds used are billed at the card's hourly price. Results last only if the job uploads them somewhere, such as the project's storage. The image needs curl, wget or python3 to report its start and end. Pulling the image is GPU time too: it is billed and counts toward max_minutes.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/gpu/jobs`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`gpu`	`string`, rtx4090 \| l40s \| a100 \| h100	Yes	rtx4090, l40s, a100 or h100
`image`	`string`	Yes	A public image, e.g. pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime
`command`	`string`	Yes	Run with sh
`name`	`string`	No	A name
`env`	`object`	No	Environment variables, kept sealed
`max_minutes`	`integer`, min 1, max 10080	No	60 by default
`region`	`string`, auto \| asia \| us \| eu	No	Where to rent: auto (any data center with a free card, the default), asia (Japan, India), us or eu. With a volume, the GPU is rented in its data center.
`volume`	`string`	No	The GPU storage to mount at /workspace, by name (made with create_gpu_volume)

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "gpu": {
      "type": "string",
      "enum": [
        "rtx4090",
        "l40s",
        "a100",
        "h100"
      ],
      "description": "rtx4090, l40s, a100 or h100"
    },
    "image": {
      "type": "string",
      "description": "A public image, e.g. pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime"
    },
    "command": {
      "type": "string",
      "description": "Run with sh"
    },
    "name": {
      "type": "string",
      "description": "A name"
    },
    "env": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Environment variables, kept sealed"
    },
    "max_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10080,
      "description": "60 by default"
    },
    "region": {
      "type": "string",
      "enum": [
        "auto",
        "asia",
        "us",
        "eu"
      ],
      "description": "Where to rent: auto (any data center with a free card, the default), asia (Japan, India), us or eu. With a volume, the GPU is rented in its data center."
    },
    "volume": {
      "type": "string",
      "description": "The GPU storage to mount at /workspace, by name (made with create_gpu_volume)"
    }
  },
  "required": [
    "ref",
    "gpu",
    "image",
    "command"
  ],
  "additionalProperties": false
}

`get_gpu_job` A GPU job

Read-only

One GPU job's status, the time and money it used, its exit code and the end of its output (up to 64KB).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/gpu/jobs/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The job id

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The job id"
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`cancel_gpu_job` Stop a GPU job

Destructive

Stops a GPU job. One not started yet never starts; a running one lets its GPU go. The time until the GPU is let go is billed.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/gpu/jobs/{id}/cancel`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The job id

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The job id"
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`create_gpu_server` Create a GPU server

Destructive

Creates a GPU server that hosts a model from a public image. Called with the secret key at https://<ref>.<zone>/gpu/v1/servers/<name>/, it starts when stopped (answering 503 meanwhile) and passes the request on. It stops after idle_minutes without a request (0 keeps it up). Billed by the second from when it starts turning on until it is off, image download included. The server receives the x-oneend-gpu-token header, the same value as ONEEND_GPU_TOKEN.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/gpu/servers`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	Lowercase letters, digits and hyphens
`gpu`	`string`, rtx4090 \| l40s \| a100 \| h100	Yes	rtx4090, l40s, a100 or h100
`image`	`string`	Yes	A public image, e.g. vllm/vllm-openai:latest
`command`	`string`	No	Empty runs the image's own
`env`	`object`	No	Environment variables, kept sealed
`port`	`integer`, min 1, max 65535	No	8000 by default
`idle_minutes`	`integer`, min 0, max 1440	No	15 by default, 0 keeps it up
`region`	`string`, auto \| asia \| us \| eu	No	Where to rent: auto (any data center with a free card, the default), asia (Japan, India), us or eu. With a volume, the GPU is rented in its data center.
`volume`	`string`	No	The GPU storage to mount at /workspace, by name (made with create_gpu_volume)

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "Lowercase letters, digits and hyphens"
    },
    "gpu": {
      "type": "string",
      "enum": [
        "rtx4090",
        "l40s",
        "a100",
        "h100"
      ],
      "description": "rtx4090, l40s, a100 or h100"
    },
    "image": {
      "type": "string",
      "description": "A public image, e.g. vllm/vllm-openai:latest"
    },
    "command": {
      "type": "string",
      "description": "Empty runs the image's own"
    },
    "env": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Environment variables, kept sealed"
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "description": "8000 by default"
    },
    "idle_minutes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1440,
      "description": "15 by default, 0 keeps it up"
    },
    "region": {
      "type": "string",
      "enum": [
        "auto",
        "asia",
        "us",
        "eu"
      ],
      "description": "Where to rent: auto (any data center with a free card, the default), asia (Japan, India), us or eu. With a volume, the GPU is rented in its data center."
    },
    "volume": {
      "type": "string",
      "description": "The GPU storage to mount at /workspace, by name (made with create_gpu_volume)"
    }
  },
  "required": [
    "ref",
    "name",
    "gpu",
    "image"
  ],
  "additionalProperties": false
}

`stop_gpu_server` Stop a GPU server

Destructive

Stops a GPU server now. The time until it is off is billed. The next request starts it again.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/gpu/servers/{name}/stop`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The server name

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The server name"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`delete_gpu_server` Delete a GPU server

Destructive

Deletes a GPU server, stopping it first when it runs. This cannot be undone, so put the GPU server name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/gpu/servers/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The server name
`confirm`	`string`	Yes	The GPU server name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The server name"
    },
    "confirm": {
      "type": "string",
      "description": "The GPU server name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`create_gpu_volume` Create GPU storage

Destructive

Creates GPU storage in one data center to keep models and data. Name it as volume on a job or server and it is mounted at /workspace, so nothing has to be downloaded again. Billed by the GB-month for as long as it exists, used or not. Jobs and servers that use it rent their GPU in its data center only. Not on the free plan.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/gpu/volumes`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	Lowercase letters, digits and hyphens
`size_gb`	`integer`, min 10, max 4000	No	50 GB by default
`datacenter`	`string`	Yes	A data center, e.g. AP-JP-1 (Japan); list_gpu lists them

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "Lowercase letters, digits and hyphens"
    },
    "size_gb": {
      "type": "integer",
      "minimum": 10,
      "maximum": 4000,
      "description": "50 GB by default"
    },
    "datacenter": {
      "type": "string",
      "description": "A data center, e.g. AP-JP-1 (Japan); list_gpu lists them"
    }
  },
  "required": [
    "ref",
    "name",
    "datacenter"
  ],
  "additionalProperties": false
}

`delete_gpu_volume` Delete GPU storage

Destructive

Deletes GPU storage and every file on it. Not while a job or server uses it. This cannot be undone. Storage is billed until it is deleted.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/gpu/volumes/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The storage name

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The storage name"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`list_deleted_deployments` Recently deleted deployments

Read-only

Returns the deployments deleted in the last 3 days (by hand or because their retention period ended) and until when each can be restored (restorable_until). Meanwhile their own address answers 410.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/deployments/deleted`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`delete_deployment` Delete a deployment

Destructive

Deletes one deployment. A deployment being served or still building cannot be deleted. It can be restored with restore_deployment for 3 days, then its files and build log are removed. Production deployments take a project admin, the rest a developer or above.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/deployments/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`, pattern ^dpl-[0-9a-f]{16}$	Yes	The deployment id (dpl-…). list_deployments or list_deleted_deployments shows it.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "pattern": "^dpl-[0-9a-f]{16}$",
      "description": "The deployment id (dpl-…). list_deployments or list_deleted_deployments shows it."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`restore_deployment` Restore a deployment

Destructive

Restores a deployment deleted in the last 30 days. Its own address answers again, and it can be rolled back or promoted to. Production deployments take a project admin, the rest a developer or above.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/deployments/{id}/restore`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`, pattern ^dpl-[0-9a-f]{16}$	Yes	The deployment id (dpl-…). list_deployments or list_deleted_deployments shows it.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "pattern": "^dpl-[0-9a-f]{16}$",
      "description": "The deployment id (dpl-…). list_deployments or list_deleted_deployments shows it."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_volumes` Volumes

Read-only

Returns the app volumes (disk that stays when a server restarts or a new deployment goes out) and their backups, how much the plan allows in total (max_gb) and how much is used (used_gb), and the port each app's server listens on (apps[].listens_on). Volumes are mounted on production servers only.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/volumes`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_volume` Create a volume

Only adds

Adds a volume to an app's production servers, mounted read-write at mount_path in the container; its size is a hard cap. For WordPress use /var/www/html. System paths such as /etc, /usr, /proc and /tmp are refused. Ready within a minute; the servers restart with it. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/volumes`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`mount_path`	`string`	Yes	An absolute path inside the container, for example /var/www/html.
`size_gb`	`integer`, min 1, max 500	No	Size in GB, 1 to 500. 1 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "mount_path": {
      "type": "string",
      "description": "An absolute path inside the container, for example /var/www/html."
    },
    "size_gb": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Size in GB, 1 to 500. 1 by default."
    }
  },
  "required": [
    "ref",
    "app",
    "mount_path"
  ],
  "additionalProperties": false
}

`resize_volume` Grow a volume

Destructive

Makes a volume larger without stopping the server. A volume cannot shrink. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/volumes/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The volume id from list_volumes.
`size_gb`	`integer`, min 1, max 500	Yes	Size in GB, 1 to 500.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The volume id from list_volumes."
    },
    "size_gb": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Size in GB, 1 to 500."
    }
  },
  "required": [
    "ref",
    "id",
    "size_gb"
  ],
  "additionalProperties": false
}

`delete_volume` Delete a volume

Destructive

Deletes a volume, every file on it and its backups. Production servers restart without it. This cannot be undone, so use it only when the user clearly asks, and put the volume path (mount_path) exactly in confirm. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/volumes/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The volume id from list_volumes.
`confirm`	`string`	Yes	The volume path. Must equal mount_path from list_volumes exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The volume id from list_volumes."
    },
    "confirm": {
      "type": "string",
      "description": "The volume path. Must equal mount_path from list_volumes exactly."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`create_volume_backup` Back up a volume

Only adds

Packs the volume's files now and keeps them for 30 days. Finishes within a few minutes and appears in list_volumes under backups. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/volumes/{id}/backups`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The volume id from list_volumes.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The volume id from list_volumes."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`restore_volume_backup` Restore a volume

Destructive

Replaces the volume's current files with a backup's. Files changed after the backup are lost, but the current files are backed up first and kept for 7 days, so that backup undoes it. Use it only when the user asks. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/volumes/{id}/restore`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The volume id from list_volumes.
`backup_id`	`string`	Yes	A backups[].id from list_volumes whose status is ready.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The volume id from list_volumes."
    },
    "backup_id": {
      "type": "string",
      "description": "A backups[].id from list_volumes whose status is ready."
    }
  },
  "required": [
    "ref",
    "id",
    "backup_id"
  ],
  "additionalProperties": false
}

Functions

Name	Description
`list_functions`	Functions
`get_function`	Read a function's code
`deploy_function`	Deploy a function
`set_function_limits`	Function time limits
`remove_function`	Remove a function
`list_function_secrets`	Function secrets
`set_function_secrets`	Save function secrets
`copy_function_secrets`	Copy function secrets
`delete_function_secret`	Delete a function secret
`set_function_egress`	Functions' outbound requests

`list_functions` Functions

Read-only

Shows the deployed functions with the address to call each one and whether it is public. egress says whether outbound requests are on, and outbound_requests_per_minute is the limit a minute on outside requests that functions, pg_net and HTTP jobs share (calls to the project's own API are not counted).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/functions`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_function` Read a function's code

Read-only

Shows the code and version of a deployed function. Read the current code before changing it. When deploy_function answered status "building", build.status (building, deployed or failed) and build.error tell how it ended.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/functions/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The function name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The function name."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`deploy_function` Deploy a function

Destructive

Deploys one function. A function with the same name is replaced as a whole, and the next call runs the new code. The code is one TypeScript file that exports, with export default, (request, { sql }) => response. request has method, headers, claims (the claims of the key it was called with: role anon, authenticated or service_role; null for a public function called with no key), text() and json(); sql(text, values) runs one SQL statement with this project's service_role privileges and returns an array of rows. The response is an object (sent as JSON), a string, or { status, headers, body }. To use npm packages, send dependencies ({"zod":"^3.23.8"}) or package_json (a string) with it. They are installed at deploy time and bundled with the code into one ESM file (up to 5MB; install scripts are not run; no native modules). A package set installed once is reused, so from the second deploy on it takes seconds. If it has not finished in 40 seconds, it answers status "building" at once and the deploy carries on on the server. Then call get_function again until build.status is deployed or failed. For several files, send them together as files ({"lib/util.ts": "..."}) and import them by relative path. To send a whole folder, leave source empty and put everything, index.ts included, in files. As on Supabase, the imports of a deno.json (or import_map.json) and npm:, jsr: and URL imports (such as npm:zod@3, jsr:@supabase/supabase-js@2, https://esm.sh/…, https://deno.land/[email protected]/http/server.ts) work. npm:, jsr: and esm.sh are installed as npm packages at deploy time; any other URL is fetched once at deploy time and bundled with the code (the addresses and SHA-256 fetched are in get_function's remote_imports, and must match a deno.lock when there is one). Nothing is fetched while the function runs. As with Supabase's supabase/functions/<name>/ folder, when the code imports ../_shared/cors.ts, put it in files as "../_shared/cors.ts". Only folders beside the function folder can be sent this way. One call may run for 150 seconds (as on Supabase). To change that, use set_function_limits. The caller's Authorization header (when it is a key of this project) reaches the function as it was sent, so createClient(url, anonKey, { global: { headers: { Authorization: req.headers.get('Authorization') } } }) acts as that person. When you change a bundled function, send back the package_json and files that get_function returned, as they are. Leave them out and it becomes a single-file function. Network access is off by default and can be turned on with set_function_egress. The production environment variables arrive in process.env. Only owners and admins can deploy functions. Who can call it: a private function (the default) needs a key of this project: the publishable key (claims.role anon), a signed-in user's token (authenticated) or the secret key (service_role). This is what Supabase's verify_jwt checks, so supabase.functions.invoke and a fetch with the publishable key work as they are. To accept signed-in users only, check request.claims.role in the function. With public set to true, anyone can call it, with no key at all. Use that only for requests that arrive without a key, such as a payment provider's webhook. Calling: POST https://<ref>.<zone>/functions/v1/<name>, with the header Authorization: Bearer <publishable key, user token or secret key>.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/functions/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	Starts with a lowercase letter; lowercase letters, digits and hyphens. It becomes the end of the address you call.
`source`	`string`	No	The whole function code (up to 8MB). With files, it is saved as the entry file. Leave it out when files holds the entry.
`public`	`boolean`	No	Left out, the current value is kept; a new function is private.
`dependencies`	`object`	No	The npm packages to use and their versions. For example: {"zod": "^3.23.8"}. Merged into the dependencies of package_json.
`package_json`	`string`	No	The whole package.json (optional). With it, packages are installed and everything is bundled into one file.
`package_lock`	`string`	No	package-lock.json (optional). With it, npm ci installs exactly those versions.
`files`	`object`	No	Other files to put beside source, relative path to content (up to 200, 8MB in total). A folder beside the function folder is written "../_shared/cors.ts".
`entry`	`string`	No	The file name source is saved as. index.ts by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "Starts with a lowercase letter; lowercase letters, digits and hyphens. It becomes the end of the address you call."
    },
    "source": {
      "type": "string",
      "description": "The whole function code (up to 8MB). With files, it is saved as the entry file. Leave it out when files holds the entry."
    },
    "public": {
      "type": "boolean",
      "description": "Left out, the current value is kept; a new function is private."
    },
    "dependencies": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "The npm packages to use and their versions. For example: {\"zod\": \"^3.23.8\"}. Merged into the dependencies of package_json."
    },
    "package_json": {
      "type": "string",
      "description": "The whole package.json (optional). With it, packages are installed and everything is bundled into one file."
    },
    "package_lock": {
      "type": "string",
      "description": "package-lock.json (optional). With it, npm ci installs exactly those versions."
    },
    "files": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Other files to put beside source, relative path to content (up to 200, 8MB in total). A folder beside the function folder is written \"../_shared/cors.ts\"."
    },
    "entry": {
      "type": "string",
      "description": "The file name source is saved as. index.ts by default."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`set_function_limits` Function time limits

Destructive

Sets, without deploying again, how long one call of a function may take (timeout_seconds) and how long one SQL statement of it may take (sql_timeout_seconds), in seconds. The defaults are 150 seconds (as on Supabase's edge functions) and 8 seconds; this server's maximum is get_function's timeout_cap_seconds. null puts one back to its default; leaving it out keeps the current value. Takes effect from the next call. A call past its limit is cut off with 504.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/functions/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The function name.
`timeout_seconds`	`string`, min 1	No	Seconds one call may take. null for the default (150 seconds).
`sql_timeout_seconds`	`string`, min 1	No	Seconds one SQL statement may take. null for the default (8 seconds).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The function name."
    },
    "timeout_seconds": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "Seconds one call may take. null for the default (150 seconds)."
    },
    "sql_timeout_seconds": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "Seconds one SQL statement may take. null for the default (8 seconds)."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`remove_function` Remove a function

Destructive

Removes a function. Its address returns 404, and scheduled jobs that call it fail. It cannot be undone, so use it only when the user clearly asks, and put the function name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/functions/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The function name.
`confirm`	`string`	Yes	The function name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The function name."
    },
    "confirm": {
      "type": "string",
      "description": "The function name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`list_function_secrets` Function secrets

Read-only

The names of the secrets only functions see, and when each changed. No tool can read a value back. readable false means the value no longer opens and is left out of functions, so save it again. Only owners and admins can see them.

Name	Description
Token scope	`read`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/function-secrets`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_function_secrets` Save function secrets

Destructive

Saves one or more secrets only functions see (a webhook signing key, a mail service's API key). They never reach a site build, and they win over an environment variable of the same name. Functions read them from process.env from their next call. A name already there is overwritten; if any one is wrong, nothing is saved. A saved value cannot be read back: the answer holds names only. Names starting with SUPABASE_ or BLACKWALL, and NODE_ENV, HOME, PATH, NODE_OPTIONS and TZ, are refused. Up to 100 per project and 32KB per value. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/function-secrets`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`secrets`	`object`	No	Names and values, for example {"STRIPE_WEBHOOK_SECRET": "whsec_…"}. The values are not shown again.
`dotenv`	`string`	No	The whole of a .env file. Comments and blank lines are skipped.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "secrets": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Names and values, for example {\"STRIPE_WEBHOOK_SECRET\": \"whsec_…\"}. The values are not shown again."
    },
    "dotenv": {
      "type": "string",
      "description": "The whole of a .env file. Comments and blank lines are skipped."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`copy_function_secrets` Copy function secrets

Destructive

Copies function secrets by name from another of your projects (from) into this one (ref). The values move inside the server and the answer holds names only, so the same key need not be pasted again. A name this project already has is skipped (skipped) unless overwrite is true. Names from does not have are listed in missing and the rest are copied. Up to 50 at a time. You must be an owner or admin of both projects (they may be in different organisations).

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/function-secrets/copy`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from. list_projects gives it.
`names`	`array<string>`, min items 1, max items 50	Yes	The secret names to copy: name in list_function_secrets of the from project. For example ["ANTHROPIC_API_KEY"].
`overwrite`	`boolean`	No	Whether to replace a name this project already has. Defaults to false (skipped).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from. list_projects gives it."
    },
    "names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "The secret names to copy: name in list_function_secrets of the from project. For example [\"ANTHROPIC_API_KEY\"]."
    },
    "overwrite": {
      "type": "boolean",
      "description": "Whether to replace a name this project already has. Defaults to false (skipped)."
    }
  },
  "required": [
    "ref",
    "from",
    "names"
  ],
  "additionalProperties": false
}

`delete_function_secret` Delete a function secret

Destructive

Deletes one function secret. The value cannot be brought back, and functions run without it from their next call. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/function-secrets/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	name in list_function_secrets.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "name in list_function_secrets."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`set_function_egress` Functions' outbound requests

Destructive

Allows or blocks functions from calling public HTTPS addresses with fetch(). The current state is egress in list_functions. Takes effect within 30 seconds. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/function-egress`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true to allow outbound requests, false to block them.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to allow outbound requests, false to block them."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

Domains and edge

Name	Description
`list_domains`	Domains
`add_domain`	Connect a domain
`remove_domain`	Disconnect a domain
`set_domain_redirect`	Redirect a domain
`get_edge`	Firewall and cache
`set_edge`	Change the firewall
`purge_edge_cache`	Purge the cache
`upload_certificate`	Upload a certificate
`remove_certificate`	Remove an uploaded certificate

`list_domains` Domains

Read-only

Shows the domains connected to this project with what each is for (site/api), the branch it follows, where it redirects, its verification state (with the TXT record to add if not verified yet) and its certificate state.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/domains`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`add_domain` Connect a domain

Only adds Reaches outside

Connects a domain. Add the returned verification_record (TXT) to DNS and it is verified within a few minutes. With target=api the address answers as the project API (data, sign-in, storage). With branch, it follows that branch's preview. Wildcards such as *.example.com work. With pair_www=true the www address is connected too and one redirects to the other.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/domains`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hostname`	`string`	Yes	For example: example.com, api.example.com, *.example.com
`target`	`string`, site \| api	No	site for the deployed site, api for the project API.
`branch`	`string`	No	Site only. Empty means production.
`pair_www`	`boolean`	No	Also connect the www address and redirect one to the other.
`app`	`string`	No	The app name (name from list_apps). Empty means the project's site (the app with project_site true).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hostname": {
      "type": "string",
      "description": "For example: example.com, api.example.com, *.example.com"
    },
    "target": {
      "type": "string",
      "enum": [
        "site",
        "api"
      ],
      "description": "site for the deployed site, api for the project API."
    },
    "branch": {
      "type": "string",
      "description": "Site only. Empty means production."
    },
    "pair_www": {
      "type": "boolean",
      "description": "Also connect the www address and redirect one to the other."
    },
    "app": {
      "type": "string",
      "description": "The app name (name from list_apps). Empty means the project's site (the app with project_site true)."
    }
  },
  "required": [
    "ref",
    "hostname"
  ],
  "additionalProperties": false
}

`remove_domain` Disconnect a domain

Destructive

Disconnects a domain. The address stops answering within a few seconds. Use it only when the user clearly asks, and put the domain exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/domains/{hostname}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hostname`	`string`	Yes	The connected domain.
`confirm`	`string`	Yes	The domain. It must be the same as hostname (case does not matter).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hostname": {
      "type": "string",
      "description": "The connected domain."
    },
    "confirm": {
      "type": "string",
      "description": "The domain. It must be the same as hostname (case does not matter)."
    }
  },
  "required": [
    "ref",
    "hostname",
    "confirm"
  ],
  "additionalProperties": false
}

`set_domain_redirect` Redirect a domain

Destructive

Makes this domain redirect to another domain of the same project, or, with to empty, serve the site again. With a path in to (example.com/vision), the visited path is appended to it and the query string goes along: vision.example.com/x?y=1 → example.com/vision/x?y=1, and the home page goes to example.com/vision. The domain in to must be connected to this project and not itself a redirect.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/domains/{hostname}/redirect`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hostname`	`string`	Yes	The domain to redirect.
`to`	`string`	No	A domain, or a domain and a path (for example example.com/vision). Empty turns the redirect off.
`status`	`integer`, 308 \| 307 \| 301 \| 302	No	The status code. 308 (permanent, keeps the method) by default. Left out, the current one stays.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hostname": {
      "type": "string",
      "description": "The domain to redirect."
    },
    "to": {
      "type": "string",
      "description": "A domain, or a domain and a path (for example example.com/vision). Empty turns the redirect off."
    },
    "status": {
      "type": "integer",
      "enum": [
        308,
        307,
        301,
        302
      ],
      "description": "The status code. 308 (permanent, keeps the method) by default. Left out, the current one stays."
    }
  },
  "required": [
    "ref",
    "hostname"
  ],
  "additionalProperties": false
}

`get_edge` Firewall and cache

Read-only

Shows this project's IP deny and allow lists, the request limit per minute for one address, what they apply to, and when the cache was last purged.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/edge`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_edge` Change the firewall

Destructive

Changes the IP deny list, the allow list (empty allows everyone), the request limit per minute (10 to 100000, null for the platform default) and what they apply to (all/site/api). Only the fields you give change. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/edge`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`deny`	`array<string>`	No	IP addresses or CIDR ranges to refuse.
`allow`	`array<string>`	No	IP addresses or CIDR ranges to allow. Empty allows everyone.
`rate_per_minute`	`string`	No	Requests per minute from one address, 10 to 100000. null for the platform default.
`scope`	`string`, all \| site \| api	No	What the rules apply to: all, site or api.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "deny": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "IP addresses or CIDR ranges to refuse."
    },
    "allow": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "IP addresses or CIDR ranges to allow. Empty allows everyone."
    },
    "rate_per_minute": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Requests per minute from one address, 10 to 100000. null for the platform default."
    },
    "scope": {
      "type": "string",
      "enum": [
        "all",
        "site",
        "api"
      ],
      "description": "What the rules apply to: all, site or api."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`purge_edge_cache` Purge the cache

Destructive

Discards every response stored at the edge because a server deployment allowed sharing with s-maxage. From the next request, the deployment answers again.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/edge/purge`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`upload_certificate` Upload a certificate

Destructive

Uses your own TLS certificate for a connected domain. certificate is the PEM chain (the server certificate first), key is the PEM private key. The domain name must be in the certificate. Takes effect within 1 minute. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/domains/{hostname}/certificate`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hostname`	`string`	Yes	The connected domain.
`certificate`	`string`	Yes	The PEM certificate chain, the server certificate first.
`key`	`string`	Yes	The PEM private key.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hostname": {
      "type": "string",
      "description": "The connected domain."
    },
    "certificate": {
      "type": "string",
      "description": "The PEM certificate chain, the server certificate first."
    },
    "key": {
      "type": "string",
      "description": "The PEM private key."
    }
  },
  "required": [
    "ref",
    "hostname",
    "certificate",
    "key"
  ],
  "additionalProperties": false
}

`remove_certificate` Remove an uploaded certificate

Destructive

Removes the uploaded certificate and goes back to the automatically issued one. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/domains/{hostname}/certificate`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hostname`	`string`	Yes	The connected domain.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hostname": {
      "type": "string",
      "description": "The connected domain."
    }
  },
  "required": [
    "ref",
    "hostname"
  ],
  "additionalProperties": false
}

Network

Name	Description
`get_network`	Network addresses
`set_static_outbound_ip`	Static outbound IP

`get_network` Network addresses

Read-only

The addresses the project receives requests on (inbound: a custom domain's A record) and, for a project with the static outbound IP turned on, the static addresses it sends from (outbound.addresses). For a project without it the outbound address is shared and not static, so it is not returned. Do not put it on an allow list.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/network`, GET `/projects/{ref}/network/ips`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_static_outbound_ip` Static outbound IP

Destructive

Turns the static outbound IP, a paid add-on, on or off. When on, server deployments, functions' fetch() and database webhooks leave from a static address, and a monthly price is billed for the time it is on. Pro plan and above; only owners, admins and billing members can do it. It costs money, so use it only when the user clearly asks. The price and the current state are in get_network. In a region whose address does not exist yet the outcome is provisioning: the address is being made (usually under an hour), and until it is ready nothing is billed and no address is returned.

Name	Description
Token scope	`write`
Roles	`billing.manage` owner or admin or billing
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/network/static-outbound-ip`, DELETE `/projects/{ref}/network/static-outbound-ip`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

Scheduled jobs

Name	Description
`list_jobs`	Scheduled jobs
`save_job`	Create or change a scheduled job
`set_job_enabled`	Turn a scheduled job on or off
`run_job`	Run a scheduled job now
`list_job_runs`	Scheduled job runs
`remove_job`	Remove a scheduled job

`list_jobs` Scheduled jobs

Read-only

Shows the scheduled jobs (cron) with their schedule, next run and last result. Jobs made with cron.schedule in the project's SQL have source sql. limit is the plan's number of jobs. All times are UTC.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/jobs`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`save_job` Create or change a scheduled job

Destructive

Calls a function or runs one SQL statement on a schedule. A job with the same name is changed. schedule is five-field cron (minute hour day month weekday) in UTC. Korea is UTC+9, so midnight in Korea is "0 15 * * *". With kind function, target is the name of a deployed function (called with a POST whose body is {}); with sql, target is SQL run as the service role. External URLs cannot be called. Create a function, or use net.http_post from SQL. SQL has to finish within timeout_seconds (120 by default); when the SQL raises its own statement_timeout it is given that long. Either way, at most the plan's maximum (Free 300 seconds, Pro and Enterprise 3600). Jobs made with cron.schedule in SQL are listed too, with source sql; change them in SQL (cron.alter_job, cron.unschedule) or with set_job_enabled and remove_job. Each plan has a number of jobs per project (limit in list_jobs).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/jobs/{job}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The job name. Saving a name that exists changes that job.
`schedule`	`string`	Yes	For example: "/5 * * " (every 5 minutes), "0 15 * *" (midnight in Korea).
`kind`	`string`, function \| sql	Yes	function to call a deployed function, sql to run SQL.
`target`	`string`	Yes	The function name, or the SQL to run.
`enabled`	`boolean`	No	Whether the job runs. On by default.
`timeout_seconds`	`number`	No	How long a SQL job may run, in seconds. 120 by default; at most the plan's maximum (Free 300, Pro and Enterprise 3600).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The job name. Saving a name that exists changes that job."
    },
    "schedule": {
      "type": "string",
      "description": "For example: \"*/5 * * * *\" (every 5 minutes), \"0 15 * * *\" (midnight in Korea)."
    },
    "kind": {
      "type": "string",
      "enum": [
        "function",
        "sql"
      ],
      "description": "function to call a deployed function, sql to run SQL."
    },
    "target": {
      "type": "string",
      "description": "The function name, or the SQL to run."
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether the job runs. On by default."
    },
    "timeout_seconds": {
      "type": "number",
      "description": "How long a SQL job may run, in seconds. 120 by default; at most the plan's maximum (Free 300, Pro and Enterprise 3600)."
    }
  },
  "required": [
    "ref",
    "name",
    "schedule",
    "kind",
    "target"
  ],
  "additionalProperties": false
}

`set_job_enabled` Turn a scheduled job on or off

Destructive

Turns a scheduled job off or back on. When turned back on it does not catch up on missed runs; it runs from the next scheduled time. job is the id or the name.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/jobs/{job}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`job`	`string`	Yes	The job id or name.
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "job": {
      "type": "string",
      "description": "The job id or name."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "job",
    "enabled"
  ],
  "additionalProperties": false
}

`run_job` Run a scheduled job now

Destructive

Runs the job once within a minute, without waiting for its schedule. See the result with list_job_runs.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/jobs/{job}/run`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`job`	`string`	Yes	The job id or name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "job": {
      "type": "string",
      "description": "The job id or name."
    }
  },
  "required": [
    "ref",
    "job"
  ],
  "additionalProperties": false
}

`list_job_runs` Scheduled job runs

Read-only

Shows a job's recent runs and their results, newest first, with the error when one failed.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/jobs/{job}/runs`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`job`	`string`	Yes	The job id or name.
`limit`	`number`	No	How many runs to show.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "job": {
      "type": "string",
      "description": "The job id or name."
    },
    "limit": {
      "type": "number",
      "description": "How many runs to show."
    }
  },
  "required": [
    "ref",
    "job"
  ],
  "additionalProperties": false
}

`remove_job` Remove a scheduled job

Destructive

Removes a scheduled job and its run history.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/jobs/{job}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`job`	`string`	Yes	The job id or name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "job": {
      "type": "string",
      "description": "The job id or name."
    }
  },
  "required": [
    "ref",
    "job"
  ],
  "additionalProperties": false
}

Database webhooks

Name	Description
`list_db_webhooks`	Database webhooks
`create_db_webhook`	Create a database webhook
`set_db_webhook_enabled`	Turn a database webhook on or off
`list_db_webhook_deliveries`	Database webhook deliveries
`remove_db_webhook`	Remove a database webhook

`list_db_webhooks` Database webhooks

Read-only

Shows the webhooks that report table changes and their recent deliveries. attached false means the table was dropped and the webhook stopped. The signing key (signing_secret) is shown once, when the webhook is created (create_db_webhook); the list carries only signing_secret_set and its last four characters (signing_secret_last4).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/webhooks`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_db_webhook` Create a database webhook

Only adds Reaches outside

Sends a POST when rows are added to, changed in or deleted from a table. Only for committed changes, within a few seconds. With kind url, target is a public https address (no private or internal addresses, redirects are not followed); with function, it is the name of a function in this project. Body: { type: "INSERT"|"UPDATE"|"DELETE", table, schema: "public", record, old_record, hook, delivery, occurred_at }. Verify it with the header x-blackwall-signature: t=<seconds>,v1=<HMAC-SHA256(signing_secret, "<t>.<body>") in hex>. signing_secret is in this answer only and cannot be read again, so save it on the receiving side right away. On failure (a response other than 2xx, or more than 10 seconds), it sends again after 10 seconds, 1 minute, 5 minutes and 30 minutes, and gives up on the fifth try.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/webhooks`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	A name to recognise the webhook by.
`table`	`string`	Yes	A table name from list_tables.
`events`	`array<string>`, insert \| update \| delete	Yes	Which changes to send: insert, update, delete.
`kind`	`string`, url \| function	Yes	url to POST to an address, function to call a function in this project.
`target`	`string`	Yes	The https address, or the function name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "A name to recognise the webhook by."
    },
    "table": {
      "type": "string",
      "description": "A table name from list_tables."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "insert",
          "update",
          "delete"
        ]
      },
      "description": "Which changes to send: insert, update, delete."
    },
    "kind": {
      "type": "string",
      "enum": [
        "url",
        "function"
      ],
      "description": "url to POST to an address, function to call a function in this project."
    },
    "target": {
      "type": "string",
      "description": "The https address, or the function name."
    }
  },
  "required": [
    "ref",
    "name",
    "table",
    "events",
    "kind",
    "target"
  ],
  "additionalProperties": false
}

`set_db_webhook_enabled` Turn a database webhook on or off

Destructive

Turns a webhook off or on. Changes made while it is off are never sent. webhook is the id or the name.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/webhooks/{webhook}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`webhook`	`string`	Yes	The webhook id or name.
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "webhook": {
      "type": "string",
      "description": "The webhook id or name."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "webhook",
    "enabled"
  ],
  "additionalProperties": false
}

`list_db_webhook_deliveries` Database webhook deliveries

Read-only

Shows a webhook's recent deliveries with the response status and the reason for any failure, newest first. Kept for 7 days.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/webhooks/{webhook}/deliveries`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`webhook`	`string`	Yes	The webhook id or name.
`limit`	`number`	No	How many deliveries to show.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "webhook": {
      "type": "string",
      "description": "The webhook id or name."
    },
    "limit": {
      "type": "number",
      "description": "How many deliveries to show."
    }
  },
  "required": [
    "ref",
    "webhook"
  ],
  "additionalProperties": false
}

`remove_db_webhook` Remove a database webhook

Destructive

Removes a webhook, its delivery history and any changes not sent yet.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/webhooks/{webhook}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`webhook`	`string`	Yes	The webhook id or name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "webhook": {
      "type": "string",
      "description": "The webhook id or name."
    }
  },
  "required": [
    "ref",
    "webhook"
  ],
  "additionalProperties": false
}

Backups and restore

Name	Description
`list_backups`	Backups
`create_backup`	Back up now
`restore_backup`	Restore a backup

`list_backups` Backups

Read-only

Shows the project backups (automatic every night between 03:00 and 05:00 in the local time of the project region, made by hand, and made just before a restore) and the restore history. retention_days is how long they are kept.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/backups`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_backup` Back up now

Only adds

Backs up the tables, users and files now. Make one before a big change (a migration, a large delete). Kept for 7 days.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/backups`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`restore_backup` Restore a backup

Destructive

Returns the project's tables, users and files to when the backup was made. Give at (an ISO time) instead of backup_id to return to that moment, to the second (Pro and above, within list_backups' point_in_time range); files are then returned to what the rows at that moment point to (including ones deleted in the last 14 days) only on servers that use a file bucket, and otherwise left as they are now. Every change after that point is lost, so use this only when the user clearly asks. The state just before the restore is backed up first, so you can restore again with undo_backup_id. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/backups/{backup_id}/restore`, POST `/projects/{ref}/backups/restore-to-time`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`backup_id`	`string`	No	The id from list_backups.
`at`	`string`	No	For example: 2026-10-01T14:59:00+09:00

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "backup_id": {
      "type": "string",
      "description": "The id from list_backups."
    },
    "at": {
      "type": "string",
      "description": "For example: 2026-10-01T14:59:00+09:00"
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

Logs and observability

Name	Description
`get_logs`	Logs
`list_log_drains`	Log drains
`create_log_drain`	Add a log drain
`set_log_drain_enabled`	Turn a log drain off or on
`remove_log_drain`	Remove a log drain
`get_metrics`	Metrics
`get_audit_log`	Audit log

`get_logs` Logs

Read-only

Shows what happened in the project, newest first: requests to the site, API, sign-in and functions (method, path, status, time taken) and the lines the deployed servers and functions printed. If the app returns 500, look here first with level set to error. For the next page, pass the response's next_before as before. Query strings are not stored.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/logs`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`source`	`string`, site \| server \| api \| auth \| functions \| build	No	Where the lines come from: site, server, api, auth, functions, build.
`level`	`string`, warn \| error	No	warn for warnings and errors, error for errors only.
`search`	`string`	No	Text contained in the line. Case does not matter.
`before`	`string`	No	Only lines older than this time. The previous response's next_before.
`deployment_id`	`string`	No	Only lines from this deployment (dpl-).
`limit`	`integer`, min 1, max 500	No	Default 100.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "source": {
      "type": "string",
      "enum": [
        "site",
        "server",
        "api",
        "auth",
        "functions",
        "build"
      ],
      "description": "Where the lines come from: site, server, api, auth, functions, build."
    },
    "level": {
      "type": "string",
      "enum": [
        "warn",
        "error"
      ],
      "description": "warn for warnings and errors, error for errors only."
    },
    "search": {
      "type": "string",
      "description": "Text contained in the line. Case does not matter."
    },
    "before": {
      "type": "string",
      "description": "Only lines older than this time. The previous response's next_before."
    },
    "deployment_id": {
      "type": "string",
      "description": "Only lines from this deployment (dpl-)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "Default 100."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_log_drains` Log drains

Read-only

Where logs are sent (https or datadog), which sources are sent, and the last delivery and error. The signing key (signing_secret) is shown once, when the drain is created (create_log_drain); the list carries only signing_secret_set and, for owners and admins, its last four characters (signing_secret_last4).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/log-drains`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_log_drain` Add a log drain

Only adds Reaches outside

Sends this project's logs elsewhere, starting with logs written after it is created. kind=https POSTs signed JSON; kind=datadog needs an API key in secret. An https drain's signing_secret is in this answer only, so save it on the receiving side right away. Up to 5 per project. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/log-drains`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	A name to recognise the drain by.
`kind`	`string`, https \| datadog	Yes	https or datadog.
`url`	`string`	Yes	A public https address.
`secret`	`string`	No	The Datadog API key, or the value to put in the Authorization header when sending over https.
`sources`	`array<string>`, site \| server \| api \| auth \| functions \| build	No	Empty means all.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "A name to recognise the drain by."
    },
    "kind": {
      "type": "string",
      "enum": [
        "https",
        "datadog"
      ],
      "description": "https or datadog."
    },
    "url": {
      "type": "string",
      "description": "A public https address."
    },
    "secret": {
      "type": "string",
      "description": "The Datadog API key, or the value to put in the Authorization header when sending over https."
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "site",
          "server",
          "api",
          "auth",
          "functions",
          "build"
        ]
      },
      "description": "Empty means all."
    }
  },
  "required": [
    "ref",
    "name",
    "kind",
    "url"
  ],
  "additionalProperties": false
}

`set_log_drain_enabled` Turn a log drain off or on

Destructive

Stops or restarts sending and keeps the settings. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/log-drains/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_log_drains.
`enabled`	`boolean`	Yes	true to send, false to stop.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_log_drains."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to send, false to stop."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_log_drain` Remove a log drain

Destructive

Removes a log drain. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/log-drains/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_log_drains.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_log_drains."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_metrics` Metrics

Read-only

Returns requests, failures and latency (p50/p95/p99) by surface and by time, and the database size, connections and cache hit rate.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/metrics`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`range`	`string`, 1h \| 24h \| 7d	No	Empty means 24h.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "range": {
      "type": "string",
      "enum": [
        "1h",
        "24h",
        "7d"
      ],
      "description": "Empty means 24h."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_audit_log` Audit log

Read-only

tab=activity is who changed what in the organisation; tab=access is who accessed personal data. Newest first, up to 200 at a time; when has_more is true, call again with a higher offset. from and to are YYYY-MM-DD (dates in Korea). Only owners and admins can do this.

Name	Description
Token scope	`read`
Roles	`audit.read` owner or admin
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/audit`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`tab`	`string`, activity \| access	No	activity for changes, access for access to personal data.
`from`	`string`	No	The first date, YYYY-MM-DD.
`to`	`string`	No	The last date, YYYY-MM-DD.
`actor`	`string`	No	Part of an email address.
`action`	`string`	No	Actions starting with these words. For example: member.
`limit`	`integer`, min 1, max 200	No	How many entries to get, up to 200.
`offset`	`integer`, min 0	No	How many entries to skip.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "tab": {
      "type": "string",
      "enum": [
        "activity",
        "access"
      ],
      "description": "activity for changes, access for access to personal data."
    },
    "from": {
      "type": "string",
      "description": "The first date, YYYY-MM-DD."
    },
    "to": {
      "type": "string",
      "description": "The last date, YYYY-MM-DD."
    },
    "actor": {
      "type": "string",
      "description": "Part of an email address."
    },
    "action": {
      "type": "string",
      "description": "Actions starting with these words. For example: member."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "How many entries to get, up to 200."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "How many entries to skip."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

Team and notifications

Name	Description
`list_team`	Team members
`invite_member`	Invite a member
`cancel_invitation`	Cancel an invitation
`set_member_role`	Change a member's role
`remove_member`	Remove a member
`set_mfa_required`	Require two-step verification
`list_channels`	Notification channels
`create_channel`	Add a notification channel
`test_channel`	Test a notification channel
`set_channel_enabled`	Turn a notification channel off or on
`remove_channel`	Remove a notification channel

`list_team` Team members

Read-only

The members of the organisation that owns this project, with their roles, whether they use two-step verification, and invitations not accepted yet.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/team`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`invite_member` Invite a member

Only adds Reaches outside

Sends an invitation link by email. A person joins by opening the link, so nobody is added straight away. For an address that is already a member, only the role changes. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/team/invitations`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`email`	`string`	Yes	The email address to invite.
`role`	`string`, admin \| developer \| billing \| viewer	No	Empty means developer.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "email": {
      "type": "string",
      "description": "The email address to invite."
    },
    "role": {
      "type": "string",
      "enum": [
        "admin",
        "developer",
        "billing",
        "viewer"
      ],
      "description": "Empty means developer."
    }
  },
  "required": [
    "ref",
    "email"
  ],
  "additionalProperties": false
}

`cancel_invitation` Cancel an invitation

Destructive

Cancels a sent invitation. Its link stops opening at once. id is in the invitations of list_team.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/team/invitations/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The invitation id from list_team.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The invitation id from list_team."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`set_member_role` Change a member's role

Destructive

Changes the role of someone who is already a member. The owner's role cannot be changed. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Always asks
REST	PATCH `/projects/{ref}/team/members/{email}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`email`	`string`	Yes	The member's email address.
`role`	`string`, admin \| developer \| billing \| viewer	Yes	The new role.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "email": {
      "type": "string",
      "description": "The member's email address."
    },
    "role": {
      "type": "string",
      "enum": [
        "admin",
        "developer",
        "billing",
        "viewer"
      ],
      "description": "The new role."
    }
  },
  "required": [
    "ref",
    "email",
    "role"
  ],
  "additionalProperties": false
}

`remove_member` Remove a member

Destructive

Removes someone from the organisation. The owner cannot be removed. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/team/members/{email}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`email`	`string`	Yes	The member's email address.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "email": {
      "type": "string",
      "description": "The member's email address."
    }
  },
  "required": [
    "ref",
    "email"
  ],
  "additionalProperties": false
}

`set_mfa_required` Require two-step verification

Destructive

Requires two-step verification from every member of the organisation, or stops requiring it. To turn it on, this token's owner must have two-step verification on first. Members without it cannot open this organisation until they turn it on, and are listed in without_mfa in the response. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/team/mfa`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`required`	`boolean`	Yes	true to require it, false to stop requiring it.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "required": {
      "type": "boolean",
      "description": "true to require it, false to stop requiring it."
    }
  },
  "required": [
    "ref",
    "required"
  ],
  "additionalProperties": false
}

`list_channels` Notification channels

Read-only

The Slack, KakaoWork and webhook channels that receive news about deployments, domains, usage and billing, with the result of the last delivery. Organisation wide. A webhook channel's signing key (signing_secret) is shown once, when the channel is created (create_channel); the list carries only signing_secret_set and its last four characters (signing_secret_last4).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/channels`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_channel` Add a notification channel

Only adds Reaches outside

Sends notifications to Slack (an Incoming Webhook address), KakaoWork (a bot webhook address), a signed webhook, or email (1 to 10 addresses in emails). An email channel mails each address a confirmation link and sends notifications only to addresses that opened it. Leave notices empty to receive every kind (usage covers limit warnings and traffic spike alerts). The signing_secret of a webhook channel is in this answer only, so save it on the receiving side right away. Check it with test_channel after creating it. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/channels`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`kind`	`string`, slack \| kakaowork \| webhook \| email	Yes	slack, kakaowork, webhook or email.
`name`	`string`	Yes	A name to recognise the channel by.
`url`	`string`	No	The webhook address to send to. Not used by an email channel.
`emails`	`array<string>`, max items 10	No	For an email channel, the addresses to send to, e.g. ["[email protected]"].
`notices`	`array<string>`, deployments \| domains \| usage \| billing	No	Which kinds to receive: deployments, domains, usage, billing. Empty means all.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "kind": {
      "type": "string",
      "enum": [
        "slack",
        "kakaowork",
        "webhook",
        "email"
      ],
      "description": "slack, kakaowork, webhook or email."
    },
    "name": {
      "type": "string",
      "description": "A name to recognise the channel by."
    },
    "url": {
      "type": "string",
      "description": "The webhook address to send to. Not used by an email channel."
    },
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 10,
      "description": "For an email channel, the addresses to send to, e.g. [\"[email protected]\"]."
    },
    "notices": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "deployments",
          "domains",
          "usage",
          "billing"
        ]
      },
      "description": "Which kinds to receive: deployments, domains, usage, billing. Empty means all."
    }
  },
  "required": [
    "ref",
    "kind",
    "name"
  ],
  "additionalProperties": false
}

`test_channel` Test a notification channel

Only adds Reaches outside

Sends a test message to that one channel only. For an email channel it goes to confirmed addresses only, and addresses still waiting are sent the confirmation again. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/channels/{id}/test`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_channels.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_channels."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`set_channel_enabled` Turn a notification channel off or on

Destructive

Stops or resumes notifications and keeps the settings. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/channels/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_channels.
`enabled`	`boolean`	Yes	true to send, false to stop.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_channels."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to send, false to stop."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_channel` Remove a notification channel

Destructive

Removes a notification channel. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`team.manage` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/channels/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_channels.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_channels."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

Billing and usage

Name	Description
`usage`	Usage
`get_billing`	Bill and usage
`get_plan`	Plan
`get_spend_controls`	Spend controls
`set_spend_cap`	Turn the spend cap on or off
`set_spend_limit`	Monthly spend limit

`usage` Usage

Read-only

Returns the number of tables, rows, users and files, the storage used, this month's metered amounts, and the limits a minute (limits.outbound_requests_per_minute: outside requests that functions, pg_net and HTTP jobs share; calls to the project's own API are not counted).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/usage`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_billing` Bill and usage

Read-only

One month's bill (usage, included amount and charge per item) and usage by day. Empty period means this month (UTC). Amounts are in the smallest unit of currency (KRW: won, USD: cents). included is what the plans held this month allow, split by the days on each; list_included is the Pro allowance. amount_minor and total_minor are what is charged; list_amount_minor and list_total_minor are the list price. An organisation with billing_exempt true (the operator's own) is charged 0 and is never stopped for payment; its list price is the Pro rate card. Cards and payment history are only in the console. Only owners, admins and billing members can see it.

Name	Description
Token scope	`read`
Roles	`billing.manage` owner or admin or billing
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/billing`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`period`	`string`	No	YYYY-MM

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "period": {
      "type": "string",
      "description": "YYYY-MM"
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_plan` Plan

Read-only

The organisation's current plan, any scheduled change, the plans it can choose and their monthly prices, and the paid add-ons running in the organisation (addons). On the Free plan, free holds its limits (one person, no custom domains, deployments a day, paused after 3 unused days, build minutes and traffic) and what is Pro's. Each add-on is turned on and off with its own tool (set_static_outbound_ip). Changing the plan needs a payment, so it is done only on the console's billing page. Only owners, admins and billing members can see it.

Name	Description
Token scope	`read`
Roles	`billing.manage` owner or admin or billing
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/billing/plan`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_spend_controls` Spend controls

Read-only

The spend cap (on: usage stops at what the plan includes and no overage is charged), the monthly overage limit and its alert webhook, and this month's usage. Only owners, admins and billing members can see it.

Name	Description
Token scope	`read`
Roles	`billing.manage` owner or admin or billing
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/billing/spend`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_spend_cap` Turn the spend cap on or off

Destructive

Turns the spend cap of a paid plan on or off. On, usage stops at what is included and there is no overage (the console spend limit's "Allowances only"). Off, what goes over is billed, so turning it off takes the project name (name from list_projects) exactly in confirm. Only owners, admins and billing members can do this.

Name	Description
Token scope	`write`
Roles	`billing.manage` owner or admin or billing
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/billing/spend-cap`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true turns it on.
`confirm`	`string`	No	Only when turning it off (enabled: false): the project name. It must be exactly the same as name in list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true turns it on."
    },
    "confirm": {
      "type": "string",
      "description": "Only when turning it off (enabled: false): the project name. It must be exactly the same as name in list_projects."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

`set_spend_limit` Monthly spend limit

Destructive

Sets the limit on a month's overage (in the currency's smallest unit, won) and the webhook address to alert as it is approached. With the spend cap off, this is the console spend limit's "Allow overage up to an amount" (null: "No limit"). spend_limit_minor null removes the limit. Leave webhook_url out to keep the current address. New alert addresses are better added as notification channels (create_channel). Only owners, admins and billing members can do this.

Name	Description
Token scope	`write`
Roles	`billing.manage` owner or admin or billing
Console assistant confirmation	Always asks
REST	PUT `/projects/{ref}/billing/spend-limit`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`spend_limit_minor`	`string`, min 0	Yes	The limit. null for none.
`webhook_url`	`string`	No	The https address to alert. An empty string removes it.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "spend_limit_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0,
      "description": "The limit. null for none."
    },
    "webhook_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The https address to alert. An empty string removes it."
    }
  },
  "required": [
    "ref",
    "spend_limit_minor"
  ],
  "additionalProperties": false
}

Other

Name	Description
`list_s3_keys`	S3 access keys
`create_s3_key`	Create an S3 access key
`revoke_s3_key`	Revoke an S3 access key
`deploy_commit`	Deploy a commit
`deploy_files`	Deploy files
`set_function_public`	Make a function public or private
`add_sso_provider`	Add SAML SSO
`update_sso_provider`	Change SAML SSO
`get_auth_config`	Show the whole sign-in configuration
`update_auth_config`	Change the sign-in configuration
`list_custom_providers`	Custom sign-in providers
`create_custom_provider`	Create a custom sign-in provider
`update_custom_provider`	Change a custom sign-in provider
`set_custom_provider_enabled`	Turn a custom sign-in provider off or on
`remove_custom_provider`	Delete a custom sign-in provider
`list_third_party_auth`	Third-party auth
`add_third_party_auth`	Add third-party auth
`remove_third_party_auth`	Remove third-party auth
`copy_auth_from_import`	Copy sign-in settings from an import
`copy_schema_from_project`	Copy another project's structure
`copy_data_from_project`	Copy another project's rows
`move_domain`	Move a domain
`copy_users_from_project`	Copy another project's users
`compare_projects_data`	Compare two projects' data
`get_project_forward`	See the public-function forward
`set_project_forward`	Forward public functions
`get_project_write_lock`	See the write lock
`set_project_write_lock`	Write lock
`copy_functions_from_project`	Copy another project's functions
`set_vault_project_keys`	Put this project's own address and key in its vault
`copy_vault_secrets_from_project`	Copy another project's vault secrets
`copy_jobs_from_project`	Copy another project's scheduled jobs
`copy_auth_from_project`	Copy another project's sign-in settings
`copy_storage_from_project`	Copy another project's files
`copy_storage_from_import`	Copy files from an import
`link_github_app`	Connect a GitHub account
`list_schemas`	Project schemas
`set_exposed_schemas`	Set exposed schemas
`get_data_api_settings`	Data API settings
`set_data_api_settings`	Change the Data API settings
`get_database_settings`	Database connection settings
`set_database_settings`	Change the database connection settings
`list_branches`	Database branches
`create_branch`	Create a database branch
`merge_branch`	Merge a database branch
`reset_branch`	Reset a database branch
`delete_branch`	Delete a database branch
`set_branching`	Automatic database branches
`list_queues`	Queues
`create_queue`	Create a queue
`delete_queue`	Delete a queue
`purge_queue`	Empty a queue
`send_queue_message`	Send a message to a queue
`peek_queue`	Look at queue messages
`set_queues_api`	Open queues to the data API
`list_vault_secrets`	Vault secrets
`create_vault_secret`	Store a Vault secret
`update_vault_secret`	Change a Vault secret
`delete_vault_secret`	Delete a Vault secret
`get_network_restrictions`	Database network restrictions
`update_network_restrictions`	Change database network restrictions
`list_transfer_targets`	Organizations to transfer to
`transfer_project`	Transfer project
`get_analytics`	Web analytics
`get_speed_insights`	Speed Insights
`set_insights`	Turn analytics on or off
`get_edge_config`	Read edge config
`set_edge_config`	Change edge config
`get_edge_config_history`	Edge config history
`get_rolling_releases`	Rolling releases
`set_rolling_releases`	Rolling release settings
`advance_rolling_release`	Advance a rolling release
`promote_rolling_release`	Complete a rolling release
`abort_rolling_release`	Stop a rolling release
`list_kv_keys`	KV keys
`get_kv`	Read a KV value
`set_kv`	Save a KV value
`delete_kv`	Delete a KV key
`get_ai_gateway`	AI gateway
`set_ai_gateway`	AI gateway settings
`add_ai_provider`	Add an AI provider
`set_ai_provider_enabled`	Turn an AI provider off or on
`remove_ai_provider`	Remove an AI provider
`get_ai_gateway_logs`	AI gateway calls
`get_middleware`	Middleware settings
`set_middleware`	Change middleware settings
`set_ai_budgets`	AI gateway budgets
`list_ai_gateway_keys`	AI gateway keys
`create_ai_gateway_key`	Create an AI gateway key
`set_ai_gateway_key_budgets`	AI gateway key budgets
`set_ai_gateway_key_limits`	AI gateway key limits
`set_ai_model_aliases`	AI model aliases
`set_ai_gateway_hooks`	AI gateway hooks
`revoke_ai_gateway_key`	Revoke an AI gateway key
`get_ai_spend`	AI gateway spend
`get_analytics_breakdown`	Web Analytics breakdown
`set_analytics_previews`	Count preview visits
`export_analytics`	Export Web Analytics
`list_analytics_reports`	Custom reports
`get_analytics_report`	Show a custom report
`save_analytics_report`	Save a custom report
`remove_analytics_report`	Delete a custom report
`list_flags`	Feature flags
`evaluate_flag`	Evaluate a feature flag
`set_flag_enabled`	Turn a feature flag on or off
`get_remote_cache`	Remote cache
`clear_remote_cache`	Clear the remote cache
`get_queue_metrics`	Queue metrics
`list_edge_config_tokens`	Edge config read tokens
`create_edge_config_token`	Create an edge config read token
`connect_edge_config_token`	Connect a read token to a project
`disconnect_edge_config_token`	Disconnect a read token
`revoke_edge_config_token`	Revoke a read token
`get_deployment_retention`	Deployment retention
`set_deployment_retention`	Change deployment retention
`set_protection_scope`	Preview protection scope
`create_bypass_secret`	Create a protection bypass key
`revoke_bypass_secret`	Revoke a protection bypass key
`create_share_link`	Create a share link
`revoke_share_link`	Revoke a share link
`list_environments`	Environments
`create_environment`	Create an environment
`update_environment`	Change an environment
`remove_environment`	Remove an environment
`set_domain_environment`	Point a domain at an environment
`get_flag`	Feature flag
`create_flag`	Create a feature flag
`update_flag`	Change a feature flag
`set_flag_environment`	Flag settings in an environment
`add_flag_rule`	Add a flag rule
`move_flag_rule`	Reorder a flag rule
`remove_flag_rule`	Remove a flag rule
`set_flag_archived`	Archive a feature flag
`list_flag_segments`	Flag segments
`create_flag_segment`	Create a flag segment
`update_flag_segment`	Change a flag segment
`remove_flag_segment`	Remove a flag segment
`list_flag_sdk_keys`	Flag SDK keys
`create_flag_sdk_key`	Create a flag SDK key
`revoke_flag_sdk_key`	Revoke a flag SDK key
`list_alert_rules`	Alert rules
`create_alert_rule`	Create an alert rule
`set_alert_rule_enabled`	Turn an alert rule on or off
`remove_alert_rule`	Remove an alert rule
`list_project_webhooks`	Project webhooks
`create_project_webhook`	Create a project webhook
`set_project_webhook_enabled`	Turn a project webhook on or off
`test_project_webhook`	Test a project webhook
`list_project_webhook_deliveries`	Project webhook deliveries
`retry_project_webhook_delivery`	Send a project webhook delivery again
`remove_project_webhook`	Remove a project webhook
`get_firewall`	Firewall rules
`save_firewall_rule`	Save a firewall rule
`move_firewall_rule`	Move a firewall rule
`set_firewall_rule_enabled`	Turn a firewall rule on or off
`remove_firewall_rule`	Remove a firewall rule
`set_firewall_managed`	Bots and managed rules
`publish_firewall`	Publish the firewall
`reset_firewall_draft`	Discard the firewall draft
`restore_firewall_version`	Load an earlier firewall version
`set_attack_mode`	Attack challenge mode
`get_bulk_redirects`	Bulk redirects
`upload_bulk_redirects`	Upload bulk redirects
`activate_bulk_redirects`	Apply bulk redirects
`get_skew_protection`	Skew protection
`set_skew_protection`	Change skew protection
`list_remote_cache_tokens`	Remote cache tokens
`create_remote_cache_token`	Create a remote cache token
`revoke_remote_cache_token`	Revoke a remote cache token
`get_build_settings`	More build settings
`set_build_dev_settings`	Development command and Node.js version
`set_ignored_build_step`	Ignored build step
`set_production_first`	Production builds first
`set_git_checks`	Required checks and Git LFS
`set_expose_system_env`	System environment variables
`set_directory_listing`	Folder listings
`get_deployment_security`	Deployment security
`set_deployment_security`	Change deployment security
`get_routing_rules`	Routing rules
`save_routing_rules`	Save routing rules
`activate_routing_rules`	Apply a routing rules version
`purge_edge_cache_item`	Purge part of the cache
`set_job_retention`	Job run history kept
`get_storage_settings`	Storage settings
`set_storage_settings`	Change storage settings
`set_s3_enabled`	Turn the S3 endpoint on or off
`set_bucket_versioning`	Bucket versioning
`list_object_versions`	Earlier versions of files
`restore_object_version`	Restore an earlier version of a file
`remove_object_version`	Remove an earlier version for good
`list_bucket_connections`	Buckets connected to deployments
`connect_bucket`	Connect a bucket to deployments
`disconnect_bucket`	Disconnect a bucket
`list_storage_policies`	File access rules
`create_storage_policy`	Create a file access rule
`remove_storage_policy`	Remove a file access rule
`get_realtime_settings`	Realtime settings
`set_realtime_settings`	Change realtime settings
`list_realtime_policies`	Private channel rules
`create_realtime_messages_table`	Create the private channel rules table
`add_realtime_policy`	Add a private channel rule
`get_passkey_settings`	Passkey settings
`set_passkey_settings`	Change passkey settings
`list_user_factors`	A user's second factors and passkeys
`remove_user_factors`	Remove a user's second factors
`remove_user_passkey`	Remove a user's passkey
`list_oauth_apps`	OAuth apps
`create_oauth_app`	Create an OAuth app
`reset_oauth_app_secret`	Make a new OAuth app secret
`remove_oauth_app`	Remove an OAuth app
`list_shared_env_vars`	Shared environment variables
`create_shared_env_var`	Create a shared environment variable
`update_shared_env_var`	Change a shared environment variable
`remove_shared_env_var`	Remove a shared environment variable
`list_access_groups`	Access groups
`create_access_group`	Create an access group
`update_access_group`	Change an access group
`remove_access_group`	Remove an access group
`get_member_access`	A member's project access
`set_member_access`	Change a member's project access
`list_audit_drains`	Audit log drains
`create_audit_drain`	Create an audit log drain
`set_audit_drain_enabled`	Turn an audit log drain on or off
`test_audit_drain`	Test an audit log drain
`remove_audit_drain`	Remove an audit log drain
`list_org_webhooks`	Organization webhooks
`create_org_webhook`	Create an organization webhook
`set_org_webhook_enabled`	Turn an organization webhook on or off
`test_org_webhook`	Test an organization webhook
`list_org_webhook_deliveries`	Organization webhook deliveries
`retry_org_webhook_delivery`	Send an organization webhook delivery again
`remove_org_webhook`	Remove an organization webhook
`get_committer_settings`	Outside committer settings
`set_committer_policy`	Change the outside committer policy
`trust_committer`	Trust a committer
`remove_trusted_committer`	Stop trusting a committer
`answer_preview_approval`	Answer a waiting preview
`get_org_sso`	Organization SSO
`set_org_sso`	Set up organization SSO
`remove_org_sso`	Remove organization SSO
`add_org_sso_domain`	Add an organization SSO domain
`verify_org_sso_domain`	Verify an organization SSO domain
`remove_org_sso_domain`	Remove an organization SSO domain
`get_org_policies`	Organization deployment policies
`set_org_policies`	Change organization deployment policies
`set_preview_suffix`	Set the preview domain
`verify_preview_suffix`	Verify the preview domain
`remove_preview_suffix`	Remove the preview domain
`get_server`	Dedicated server
`request_server`	Rent a dedicated server
`resize_server`	Change the server size
`set_standby`	Standby server
`move_server`	Move the server
`release_server`	Give back the dedicated server
`set_restore_days`	Restore days
`list_platform_settings`	Platform settings
`set_platform_setting`	Save a platform setting
`clear_platform_setting`	Clear a platform setting
`list_platform_servers`	Platform servers
`get_platform_cpu_history`	Service host CPU history
`request_platform_server_change`	Request a platform server change
`get_platform_server_request`	Platform server change request
`cancel_platform_server_request`	Cancel a platform server change request
`list_github_variables`	GitHub repository variables
`set_github_variable`	Save a GitHub repository variable
`delete_github_variable`	Delete a GitHub repository variable
`list_platform_operators`	Platform operators
`add_platform_operator`	Add a platform operator
`remove_platform_operator`	Remove a platform operator
`list_platform_runs`	Platform workflow runs
`cancel_platform_run`	Cancel a platform workflow run
`rerun_platform_run`	Re-run a platform workflow run
`list_platform_checks`	Platform checks
`set_merge_when_green`	Merge when green
`get_ci_machines`	CI machines
`restart_ci_machine`	Restart a CI machine
`renew_ci_registration`	Register a CI machine again
`set_up_build_cache_bucket`	Set up the build cache bucket
`get_platform_overview`	Platform overview
`find_customer`	Find a customer
`list_parking_hosts`	Free servers
`list_project_placements`	Project placements
`get_platform_server_pricing`	Customer server sizes and prices
`set_platform_server_pricing`	Change the customer server switches
`set_platform_server_size`	Make or change a customer server size
`start_support_session`	Start a support session
`end_support_session`	End a support session
`list_support_sessions`	Support sessions

`list_s3_keys` S3 access keys

Read-only

The S3 endpoint (endpoint, region, force_path_style), the TUS address for resumable uploads, and each S3 access key's name, access key ID, last use and revoked state. The secret access key is never returned.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/s3-keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_s3_key` Create an S3 access key

Only adds

Creates an access key ID and secret access key that the AWS SDKs, the aws CLI or rclone sign requests to /storage/v1/s3 with. It acts as the service role and bypasses access rules, so keep it on a server. The secret access key is in this response only and cannot be seen again. Only owners and admins can create keys, up to 20 per project.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/s3-keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 60	Yes	What the key is for. For example: backup server

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "What the key is for. For example: backup server"
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`revoke_s3_key` Revoke an S3 access key

Destructive

Revokes one S3 access key. Requests signed with it are refused within 30 seconds. Other keys are not affected. This cannot be undone.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/s3-keys/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The keys[].id from list_s3_keys.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The keys[].id from list_s3_keys."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`deploy_commit` Deploy a commit

Destructive Reaches outside

Deploys a given commit of a repository. The production branch goes to production; any other branch goes to a preview. The commit must be the full 40-character hash. app is the name from list_apps. The answer has the addresses (url, preview_url or production_url) and the security check (advisors).

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`branch`	`string`	Yes	The branch the commit is on.
`commit`	`string`	Yes	The 40-character commit hash.
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe.
`block_on_advisors`	`boolean`	No	With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "branch": {
      "type": "string",
      "description": "The branch the commit is on."
    },
    "commit": {
      "type": "string",
      "description": "The 40-character commit hash."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe."
    },
    "block_on_advisors": {
      "type": "boolean",
      "description": "With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back."
    }
  },
  "required": [
    "ref",
    "app",
    "branch",
    "commit"
  ],
  "additionalProperties": false
}

`deploy_files` Deploy files

Destructive

Deploys files without a repository, as Vercel deploys files. files maps a path to text content; binary files such as images and fonts go in files_base64 as base64. Up to 3MB in total. For more, get an address with create_source_upload_url, PUT the archive there and deploy it with deploy_source (up to 50MB). They are built exactly like a pushed commit: with a package.json the framework is detected, installed and built; with only an index.html it is served as it is. With prebuilt set to true nothing is built and the files are served as sent (an already built dist). target is preview (the default) or production. Only owners and admins can deploy to production. A preview address comes from branch (preview by default). A project with no app gets an app called site. Sending the same files again gives the same source (SHA-256). Follow progress and the build log with get_deployment. In the answer, url is this deployment's own dpl- address and preview_url or production_url is the preview (branch) or production address. With wait (seconds) it waits for the build and answers with the result. advisors.critical is the number of critical security problems get_advisors finds (the top 3 in advisors.top). With block_on_advisors true, a production deploy is refused while there are any.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`files`	`object`	No	Path to text content. For example: {"index.html": "<h1>Hello</h1>"}
`files_base64`	`object`	No	Path to base64 content, for binary files.
`target`	`string`, preview \| production	No	preview by default.
`prebuilt`	`boolean`	No	With true, nothing is built and the files are served as they are.
`app`	`string`	No	The app to deploy (a name from list_apps). Leave it out when there is one app.
`branch`	`string`	No	The name of the preview, which becomes its address. preview by default.
`message`	`string`	No	A note to show in the deployment list (optional).
`wait`	`integer`, min 0, max 120	No	Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe.
`block_on_advisors`	`boolean`	No	With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "files": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Path to text content. For example: {\"index.html\": \"<h1>Hello</h1>\"}"
    },
    "files_base64": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Path to base64 content, for binary files."
    },
    "target": {
      "type": "string",
      "enum": [
        "preview",
        "production"
      ],
      "description": "preview by default."
    },
    "prebuilt": {
      "type": "boolean",
      "description": "With true, nothing is built and the files are served as they are."
    },
    "app": {
      "type": "string",
      "description": "The app to deploy (a name from list_apps). Leave it out when there is one app."
    },
    "branch": {
      "type": "string",
      "description": "The name of the preview, which becomes its address. preview by default."
    },
    "message": {
      "type": "string",
      "description": "A note to show in the deployment list (optional)."
    },
    "wait": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120,
      "description": "Seconds to wait for the build to finish (ready or error). The default 0 answers at once. If it is not done in time the answer has still_running: true and retry_after_seconds. MCP clients usually give up on a call after about 60 seconds, so around 45 is safe."
    },
    "block_on_advisors": {
      "type": "boolean",
      "description": "With true, a production deploy is refused while get_advisors has any critical security problem (advisors.critical). The default false deploys and reports the count and the top 3 in advisors. Previews are never held back."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_function_public` Make a function public or private

Destructive

Makes a function public (anyone can call it with no key) or private (it needs a key of this project: the publishable key, a user token or the secret key), without deploying again. Takes effect from the next call.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The function name.
`public`	`boolean`	Yes	true lets anyone call it without a key.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The function name."
    },
    "public": {
      "type": "boolean",
      "description": "true lets anyone call it without a key."
    }
  },
  "required": [
    "ref",
    "name",
    "public"
  ],
  "additionalProperties": false
}

`add_sso_provider` Add SAML SSO

Only adds Reaches outside

Registers a SAML IdP from its metadata (an https URL or the XML). The metadata needs an HTTP-Redirect sign-in address and a signing certificate. signInWithSSO with an email domain in domains goes to this IdP. A domain belongs to one IdP only. A new IdP can be added on the Enterprise plan only (new_providers_allowed in list_sso_providers); IdPs already added keep working on any plan.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/{param0}/{param1}`, PUT `/projects/{ref}/{param0}/{param1}/{param2}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`metadata_url`	`string`	No	An https URL. Give this or metadata_xml.
`metadata_xml`	`string`	No	The IdP's metadata XML. Give this or metadata_url.
`domains`	`array<string>`	No	Email domains, e.g. ["example.com"].
`attribute_mapping`	`object`	No	GoTrue form: {"keys": {"email": {"name": "mail"}}}.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "metadata_url": {
      "type": "string",
      "description": "An https URL. Give this or metadata_xml."
    },
    "metadata_xml": {
      "type": "string",
      "description": "The IdP's metadata XML. Give this or metadata_url."
    },
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Email domains, e.g. [\"example.com\"]."
    },
    "attribute_mapping": {
      "type": "object",
      "description": "GoTrue form: {\"keys\": {\"email\": {\"name\": \"mail\"}}}."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`update_sso_provider` Change SAML SSO

Destructive Reaches outside

Changes one IdP's domains, metadata (after it changed certificates) or attribute mapping. Only what is given changes. domains, when given, replaces the whole list.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_sso_providers.
`metadata_url`	`string`	No	An https URL to read the metadata from again.
`metadata_xml`	`string`	No	New metadata XML.
`domains`	`array<string>`	No	The full list of email domains.
`attribute_mapping`	`object`	No	GoTrue form: {"keys": {"email": {"name": "mail"}}}.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_sso_providers."
    },
    "metadata_url": {
      "type": "string",
      "description": "An https URL to read the metadata from again."
    },
    "metadata_xml": {
      "type": "string",
      "description": "New metadata XML."
    },
    "domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The full list of email domains."
    },
    "attribute_mapping": {
      "type": "object",
      "description": "GoTrue form: {\"keys\": {\"email\": {\"name\": \"mail\"}}}."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_auth_config` Show the whole sign-in configuration

Read-only

Returns this project's whole sign-in configuration under the same keys as Supabase's auth config, in lower case: sign-ups (disable_signup, mailer_autoconfirm, security_manual_linking_enabled, external_anonymous_users_enabled), the email provider and password rules, phone and the SMS provider (sms_*), SAML (saml_*), Web3, and for each social provider external_<provider>_enabled, client_id, secret, url and email_optional, and the custom providers switch. A secret is given as its last four characters, like ••••abcd; handing that back to update_auth_config leaves the stored one alone. callback_url is the address to paste into a provider's console.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/config/auth`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`update_auth_config` Change the sign-in configuration

Destructive

Changes only the keys given (GoTrue's upper-case names work too), checked by the same rules as the console's Sign In / Providers page: a provider switched on needs what it needs (external_google_client_id, a Keycloak realm url), an Apple secret must be an ES256 JWT with more than 7 days left, and an SMS message must contain {{ .Code }}. If any of it is wrong nothing is saved, and each key's reason comes back. Kakao's consent items are external_kakao_scopes (profile_nickname, account_email, gender and so on, separated by commas), the Naver fields to keep are external_naver_scopes, and Google's and GitHub's additional scopes are external_<provider>_additional_scopes. An empty string removes a secret. Only owners, admins and developers can do this.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/config/auth`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`config`	`object`	Yes	The keys and values to change, e.g. {"external_google_enabled": true, "external_google_client_id": "web.apps.googleusercontent.com"}.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "config": {
      "type": "object",
      "description": "The keys and values to change, e.g. {\"external_google_enabled\": true, \"external_google_client_id\": \"web.apps.googleusercontent.com\"}.",
      "additionalProperties": true
    }
  },
  "required": [
    "ref",
    "config"
  ],
  "additionalProperties": false
}

`list_custom_providers` Custom sign-in providers

Read-only

Shows the OAuth and OIDC providers the project defined itself (custom:<identifier>), the plan’s limit (max_providers) and the switch (enabled). The app signs in with signInWithOAuth({ provider: "custom:<identifier>" }).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/config/auth/custom-providers`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_custom_provider` Create a custom sign-in provider

Only adds

Creates one OAuth or OIDC provider (custom:<identifier>) and turns it on, in the same place set_auth_provider writes. With provider_type oidc the issuer alone is enough: the endpoints and jwks_uri are read from {issuer}/.well-known/openid-configuration, and each id_token's signature, issuer, audience, expiry and nonce are checked against those keys. With oauth2, give the issuer or authorization_url and token_url; endpoints left empty are {issuer}/oauth/authorize, /oauth/token and /oauth/userinfo. claim_map says which field of the answer is id, email, email_verified, name, avatar and phone (dotted paths). PKCE is on by default. Refused past the plan’s limit.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/config/auth/custom-providers`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`identifier`	`string`	Yes	Lowercase letters, numbers and hyphens. custom: may be given or left off.
`name`	`string`	Yes	The display name, under 100 characters.
`provider_type`	`string`, oidc \| oauth2	Yes	oidc (endpoints discovered, id_token verified) or oauth2 (endpoints given, read through claim_map).
`issuer`	`string`	No	The provider's base URL.
`discovery_url`	`string`	No	For oidc, when the discovery document is not at the standard path.
`authorization_url`	`string`	No	Required for oauth2 without an issuer; for oidc, empty is discovered.
`token_url`	`string`	No	Required for oauth2 without an issuer; for oidc, empty is discovered.
`userinfo_url`	`string`	No	Where the user is read; for oidc, empty is discovered.
`jwks_uri`	`string`	No	For oidc, to verify ID tokens; empty is discovered.
`client_id`	`string`	Yes	The client ID.
`client_secret`	`string`	Yes	The client secret.
`scopes`	`array<string>`	No	For example ["openid", "email", "profile"].
`email_optional`	`boolean`	No	Allow users without an email.
`claim_map`	`object`	No	Which field of the answer is id, email, email_verified, name, avatar and phone, as dotted paths. Left out: the OpenID standard names.
`token_auth`	`string`, body \| basic	No	Send client_secret in the body (body, the default) or as HTTP Basic (basic).
`pkce`	`boolean`	No	On by default; turn it off only if the provider refuses PKCE.
`enabled`	`boolean`	No	On by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "identifier": {
      "type": "string",
      "description": "Lowercase letters, numbers and hyphens. custom: may be given or left off."
    },
    "name": {
      "type": "string",
      "description": "The display name, under 100 characters."
    },
    "provider_type": {
      "type": "string",
      "enum": [
        "oidc",
        "oauth2"
      ],
      "description": "oidc (endpoints discovered, id_token verified) or oauth2 (endpoints given, read through claim_map)."
    },
    "issuer": {
      "type": "string",
      "description": "The provider's base URL."
    },
    "discovery_url": {
      "type": "string",
      "description": "For oidc, when the discovery document is not at the standard path."
    },
    "authorization_url": {
      "type": "string",
      "description": "Required for oauth2 without an issuer; for oidc, empty is discovered."
    },
    "token_url": {
      "type": "string",
      "description": "Required for oauth2 without an issuer; for oidc, empty is discovered."
    },
    "userinfo_url": {
      "type": "string",
      "description": "Where the user is read; for oidc, empty is discovered."
    },
    "jwks_uri": {
      "type": "string",
      "description": "For oidc, to verify ID tokens; empty is discovered."
    },
    "client_id": {
      "type": "string",
      "description": "The client ID."
    },
    "client_secret": {
      "type": "string",
      "description": "The client secret."
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "For example [\"openid\", \"email\", \"profile\"]."
    },
    "email_optional": {
      "type": "boolean",
      "description": "Allow users without an email."
    },
    "claim_map": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "Which field of the answer is id, email, email_verified, name, avatar and phone, as dotted paths. Left out: the OpenID standard names."
    },
    "token_auth": {
      "type": "string",
      "enum": [
        "body",
        "basic"
      ],
      "description": "Send client_secret in the body (body, the default) or as HTTP Basic (basic)."
    },
    "pkce": {
      "type": "boolean",
      "description": "On by default; turn it off only if the provider refuses PKCE."
    },
    "enabled": {
      "type": "boolean",
      "description": "On by default."
    }
  },
  "required": [
    "ref",
    "identifier",
    "name",
    "provider_type",
    "client_id",
    "client_secret"
  ],
  "additionalProperties": false
}

`update_custom_provider` Change a custom sign-in provider

Destructive

Changes one custom provider. The identifier cannot change. An empty client_secret keeps the stored one.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/config/auth/custom-providers/{identifier}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`identifier`	`string`	Yes	The identifier from list_custom_providers.
`name`	`string`	Yes	The display name, under 100 characters.
`provider_type`	`string`, oidc \| oauth2	Yes	oidc (endpoints discovered, id_token verified) or oauth2 (endpoints given, read through claim_map).
`issuer`	`string`	No	The provider's base URL.
`discovery_url`	`string`	No	For oidc, when the discovery document is not at the standard path.
`authorization_url`	`string`	No	Required for oauth2 without an issuer; for oidc, empty is discovered.
`token_url`	`string`	No	Required for oauth2 without an issuer; for oidc, empty is discovered.
`userinfo_url`	`string`	No	Where the user is read; for oidc, empty is discovered.
`jwks_uri`	`string`	No	For oidc, to verify ID tokens; empty is discovered.
`client_id`	`string`	Yes	The client ID.
`client_secret`	`string`	No	Empty keeps the stored secret.
`scopes`	`array<string>`	No	For example ["openid", "email", "profile"].
`email_optional`	`boolean`	No	Allow users without an email.
`claim_map`	`object`	No	Which field of the answer is id, email, email_verified, name, avatar and phone, as dotted paths. Left out: the OpenID standard names.
`token_auth`	`string`, body \| basic	No	Send client_secret in the body (body, the default) or as HTTP Basic (basic).
`pkce`	`boolean`	No	On by default; turn it off only if the provider refuses PKCE.
`enabled`	`boolean`	No	Turn it on or off as it is saved.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "identifier": {
      "type": "string",
      "description": "The identifier from list_custom_providers."
    },
    "name": {
      "type": "string",
      "description": "The display name, under 100 characters."
    },
    "provider_type": {
      "type": "string",
      "enum": [
        "oidc",
        "oauth2"
      ],
      "description": "oidc (endpoints discovered, id_token verified) or oauth2 (endpoints given, read through claim_map)."
    },
    "issuer": {
      "type": "string",
      "description": "The provider's base URL."
    },
    "discovery_url": {
      "type": "string",
      "description": "For oidc, when the discovery document is not at the standard path."
    },
    "authorization_url": {
      "type": "string",
      "description": "Required for oauth2 without an issuer; for oidc, empty is discovered."
    },
    "token_url": {
      "type": "string",
      "description": "Required for oauth2 without an issuer; for oidc, empty is discovered."
    },
    "userinfo_url": {
      "type": "string",
      "description": "Where the user is read; for oidc, empty is discovered."
    },
    "jwks_uri": {
      "type": "string",
      "description": "For oidc, to verify ID tokens; empty is discovered."
    },
    "client_id": {
      "type": "string",
      "description": "The client ID."
    },
    "client_secret": {
      "type": "string",
      "description": "Empty keeps the stored secret."
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "For example [\"openid\", \"email\", \"profile\"]."
    },
    "email_optional": {
      "type": "boolean",
      "description": "Allow users without an email."
    },
    "claim_map": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "Which field of the answer is id, email, email_verified, name, avatar and phone, as dotted paths. Left out: the OpenID standard names."
    },
    "token_auth": {
      "type": "string",
      "enum": [
        "body",
        "basic"
      ],
      "description": "Send client_secret in the body (body, the default) or as HTTP Basic (basic)."
    },
    "pkce": {
      "type": "boolean",
      "description": "On by default; turn it off only if the provider refuses PKCE."
    },
    "enabled": {
      "type": "boolean",
      "description": "Turn it on or off as it is saved."
    }
  },
  "required": [
    "ref",
    "identifier",
    "name",
    "provider_type",
    "client_id"
  ],
  "additionalProperties": false
}

`set_custom_provider_enabled` Turn a custom sign-in provider off or on

Destructive

Turns one custom provider off or on. Off, existing sessions stay, but new sign-ins fail until it is turned on again.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/config/auth/custom-providers/{identifier}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`identifier`	`string`	Yes	The identifier from list_custom_providers.
`enabled`	`boolean`	Yes	true to turn it on, false to turn it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "identifier": {
      "type": "string",
      "description": "The identifier from list_custom_providers."
    },
    "enabled": {
      "type": "boolean",
      "description": "true to turn it on, false to turn it off."
    }
  },
  "required": [
    "ref",
    "identifier",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_custom_provider` Delete a custom sign-in provider

Destructive

Deletes one custom provider. It cannot be undone, and users who signed in with it can no longer get in.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/config/auth/custom-providers/{identifier}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`identifier`	`string`	Yes	The identifier from list_custom_providers.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "identifier": {
      "type": "string",
      "description": "The identifier from list_custom_providers."
    }
  },
  "required": [
    "ref",
    "identifier"
  ],
  "additionalProperties": false
}

`list_third_party_auth` Third-party auth

Read-only

The other identity services whose tokens the Data API takes: Firebase, Clerk, WorkOS, Auth0, Amazon Cognito and OpenID issuers.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/config/auth/third-party-auth`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`add_third_party_auth` Add third-party auth

Only adds

Takes another identity service's JWTs as sign-ins to this project. value depends on type: firebase the project ID, clerk https://clerk.<domain> or https://<name>.clerk.accounts.dev, workos the issuer URL, auth0 the tenant name (the start of <name>.auth0.com), cognito the user pool ID (with region), oidc the issuer URL. For Auth0 and Cognito, giving audiences is recommended.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/config/auth/third-party-auth`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`type`	`string`, firebase \| clerk \| workos \| auth0 \| cognito \| oidc	Yes	firebase, clerk, workos, auth0, cognito or oidc.
`value`	`string`	Yes	What the type takes, as above.
`region`	`string`	No	Cognito's AWS region, e.g. ap-northeast-2.
`audiences`	`array<string>`	No	Values a token’s aud must contain.
`jwks_url`	`string`	No	For oidc, a JWKS address to use instead of discovery.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "type": {
      "type": "string",
      "enum": [
        "firebase",
        "clerk",
        "workos",
        "auth0",
        "cognito",
        "oidc"
      ],
      "description": "firebase, clerk, workos, auth0, cognito or oidc."
    },
    "value": {
      "type": "string",
      "description": "What the type takes, as above."
    },
    "region": {
      "type": "string",
      "description": "Cognito's AWS region, e.g. ap-northeast-2."
    },
    "audiences": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Values a token’s aud must contain."
    },
    "jwks_url": {
      "type": "string",
      "description": "For oidc, a JWKS address to use instead of discovery."
    }
  },
  "required": [
    "ref",
    "type",
    "value"
  ],
  "additionalProperties": false
}

`remove_third_party_auth` Remove third-party auth

Destructive

Removes one third-party auth integration. Requests from users signed in with that service are refused with 401 within 30 seconds.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/config/auth/third-party-auth/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id from list_third_party_auth.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id from list_third_party_auth."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`copy_auth_from_import` Copy sign-in settings from an import

Destructive Reaches outside

Copies a Supabase project's sign-in setup into a project here (ref), read with a Supabase account connected in import_sources: each social provider switched on there (client ID, secret and the rest, checked as update_auth_config checks them), the redirect allow list (uri_allow_list, as add_redirect_url adds it) and site_url only when this project's is empty. Secrets never appear in the conversation; the answer says per provider whether it was copied and why not. Sign-in fails until the answer's callback_url is registered in each provider's console. dry_run shows what would be copied and changes nothing. Owners, admins and developers only.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/config/auth/copy-from-import`

Input

Name	Type	Required	Description
`org`	`string`	No	The organisation id or name. Empty means the ref project's organisation.
`connection`	`string`	Yes	The Supabase account (connection from import_sources, whose source is supabase).
`project`	`string`	Yes	The Supabase project ref (projects[].id from import_sources).
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`providers`	`array<string>`	No	Providers to copy (google, kakao, apple, x...). Empty means every one switched on at Supabase.
`dry_run`	`boolean`	No	true shows what would be copied without changing anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "org": {
      "type": "string",
      "description": "The organisation id or name. Empty means the ref project's organisation."
    },
    "connection": {
      "type": "string",
      "description": "The Supabase account (connection from import_sources, whose source is supabase)."
    },
    "project": {
      "type": "string",
      "description": "The Supabase project ref (projects[].id from import_sources)."
    },
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Providers to copy (google, kakao, apple, x...). Empty means every one switched on at Supabase."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows what would be copied without changing anything."
    }
  },
  "required": [
    "connection",
    "project",
    "ref"
  ],
  "additionalProperties": false
}

`copy_schema_from_project` Copy another project's structure

Destructive

Builds the tables and structure of another project of the same account (from) in this one (ref): types, sequences, constraints, foreign keys, indexes, functions, views, triggers, row level security and policies, for the data schema (public) and each schema the project made (allfic ...). Statements run one at a time and any that needs something made later (a generated column that calls a function, a view over a view) is tried again after the others. What exists is passed over and nothing is dropped or changed, so after a failure fix the cause and call again. Rows are not copied (copy_data_from_project); grants and extensions are set separately. The source project's own name in the SQL is changed to this project's. dry_run shows the counts only. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`schemas`	`array<string>`	No	Schemas to copy (public, allfic ...). Empty means all.
`dry_run`	`boolean`	No	true shows the counts per kind without building anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Schemas to copy (public, allfic ...). Empty means all."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows the counts per kind without building anything."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`copy_data_from_project` Copy another project's rows

Destructive

Copies the rows of the tables of another project of the same account (from) into the same tables of this one (ref), inside the server. Build the tables first with copy_schema_from_project. Tables go in an order foreign keys allow, in pages by primary key. mode missing (the default) adds rows that are not here and leaves the rest; upsert also sets differing rows to the source's values, for the last pass before a cutover. Rows deleted at the source are not deleted here. A table with no primary key is copied only when empty. After 40 seconds it stops and gives next; call again with it to carry on. Sequences are set past the highest copied value. dry_run reads and writes nothing. Check the result with compare_projects_data. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`schemas`	`array<string>`	No	Schemas to copy (public, allfic ...). Empty means all.
`tables`	`array<string>`	No	Tables to copy (allfic.profiles or notes). Empty means all.
`mode`	`string`, missing \| upsert	No	missing adds only the rows that are not here; upsert also sets differing rows to the source values.
`dry_run`	`boolean`	No	true reads only and writes nothing.
`next`	`string`	No	The next from the previous answer, only to carry on.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Schemas to copy (public, allfic ...). Empty means all."
    },
    "tables": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tables to copy (allfic.profiles or notes). Empty means all."
    },
    "mode": {
      "type": "string",
      "enum": [
        "missing",
        "upsert"
      ],
      "description": "missing adds only the rows that are not here; upsert also sets differing rows to the source values."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true reads only and writes nothing."
    },
    "next": {
      "type": "string",
      "description": "The next from the previous answer, only to carry on."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`move_domain` Move a domain

Destructive

Moves domains (hostnames) to another project (to) of the same organisation with their ownership proof and certificate. Use it after a split so the new project answers the site's name. remove_domain then add_domain asks for a new TXT record in DNS and leaves the site down meanwhile; this needs neither. Only verified domains move, and domains attached to a branch preview do not. Give the www name with it. A domain left behind that redirected to a moved one has that redirect switched off, and the answer lists it. app is an app name of the receiving project (empty means its site). Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`to`	`string`	Yes	The ref of the receiving project (list_projects). It must be in the same organisation and differ from ref.
`hostnames`	`array<string>`	Yes	The domains to move (allfic.io, www.allfic.io ...).
`app`	`string`	No	The app of the receiving project that answers on these names (list_apps). Empty means its site.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "to": {
      "type": "string",
      "description": "The ref of the receiving project (list_projects). It must be in the same organisation and differ from ref."
    },
    "hostnames": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The domains to move (allfic.io, www.allfic.io ...)."
    },
    "app": {
      "type": "string",
      "description": "The app of the receiving project that answers on these names (list_apps). Empty means its site."
    }
  },
  "required": [
    "ref",
    "to",
    "hostnames"
  ],
  "additionalProperties": false
}

`copy_users_from_project` Copy another project's users

Destructive

Copies the sign-in users of another project of the same account (from), with their social sign-in links and passwords as the stored hashes, into this one (ref), inside the server. With referenced_by_schemas only the users that some table of those schemas points at (a foreign key to auth.users) move, so splitting a project that shared its sign-in does not bring the other project's users along. An account already here (same id, email or provider account) is left as it is; hashes and tokens never appear in the answer. dry_run shows the counts. Provider settings move with copy_auth_from_project. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`referenced_by_schemas`	`array<string>`	No	Only users that tables of these schemas point at (public, allfic ...). Empty means every user.
`dry_run`	`boolean`	No	true shows the counts without changing anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "referenced_by_schemas": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only users that tables of these schemas point at (public, allfic ...). Empty means every user."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows the counts without changing anything."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`compare_projects_data` Compare two projects' data

Read-only

Puts two projects' (ref, with) tables side by side inside the server and says whether they match: per table the row count and, unless hash is false, an MD5 over every row. Use it before a cutover to check that a copy of a split project is complete. Schemas are matched by name (the data schema as public, the others by what follows app_<ref>_). It only reads; tables it cannot finish in 40 seconds come back as not_checked, so split a big project with schemas. Both projects need an owner or admin.

Name	Description
Token scope	`read`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`with`	`string`	Yes	The ref of the project to compare with (list_projects). It must differ from ref.
`schemas`	`array<string>`	No	Schema names to compare (public, allfic ...). Empty means all.
`hash`	`boolean`	No	false compares row counts only (faster). Default true.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "with": {
      "type": "string",
      "description": "The ref of the project to compare with (list_projects). It must differ from ref."
    },
    "schemas": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Schema names to compare (public, allfic ...). Empty means all."
    },
    "hash": {
      "type": "boolean",
      "description": "false compares row counts only (faster). Default true."
    }
  },
  "required": [
    "ref",
    "with"
  ],
  "additionalProperties": false
}

`get_project_forward` See the public-function forward

Read-only

Shows whether another project answers this project's (ref) public function calls: the receiving project's ref, or null.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_project_forward` Forward public functions

Destructive

Lets another project (to) answer this project's (ref) public function calls, so a payment webhook or an old app that still calls the old address keeps working after a project is split. The same-named function of the project in to answers, in its environment and on its bill. Private functions, the REST API, sign-in and files are not forwarded (the keys and sessions their callers hold belong to the old project). Empty to turns it off. One step only; both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`to`	`string`	No	The ref of the project that answers instead (list_projects). Empty turns forwarding off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "to": {
      "type": "string",
      "description": "The ref of the project that answers instead (list_projects). Empty turns forwarding off."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_project_write_lock` See the write lock

Read-only

Shows whether this project (ref) is held read only right now. If it is, the end time and the reason come with it.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_project_write_lock` Write lock

Destructive

Holds this project (ref) read only for a while. Put it on just before the last copy of a split (copy_data_from_project with upsert) and that copy is the whole of it. Writes through the REST API, functions and scheduled jobs fail within seconds; reads, sign-in and files go on. The lock ends by itself after minutes (default 30, at most 1440), so a forgotten lock does not leave the project stuck. locked: false lifts it at once. Owner or admin only.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`locked`	`boolean`	Yes	true holds the project, false lifts the hold.
`minutes`	`integer`	No	How long to hold, in minutes. Default 30, from 1 to 1440.
`reason`	`string`	No	Why (up to 200 characters). It is kept in the audit log.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "locked": {
      "type": "boolean",
      "description": "true holds the project, false lifts the hold."
    },
    "minutes": {
      "type": "integer",
      "description": "How long to hold, in minutes. Default 30, from 1 to 1440."
    },
    "reason": {
      "type": "string",
      "description": "Why (up to 200 characters). It is kept in the audit log."
    }
  },
  "required": [
    "ref",
    "locked"
  ],
  "additionalProperties": false
}

`copy_functions_from_project` Copy another project's functions

Destructive

Deploys the functions of another project of the same account (from) into this one (ref) as they were written: code, files and package.json. Empty names means all of them. They arrive private (keep_public: true keeps the ones that were public), and their time and memory limits and the outbound switch are not carried over. A name already here is skipped (overwrite: true replaces it); dry_run only shows. Secrets move with copy_function_secrets. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`names`	`array<string>`	No	Function names to copy. Empty means all.
`keep_public`	`boolean`	No	true keeps a function public if it was. Default: all private.
`overwrite`	`boolean`	No	true replaces a function of the same name here. Default false (skipped).
`dry_run`	`boolean`	No	true shows what would be copied without changing anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Function names to copy. Empty means all."
    },
    "keep_public": {
      "type": "boolean",
      "description": "true keeps a function public if it was. Default: all private."
    },
    "overwrite": {
      "type": "boolean",
      "description": "true replaces a function of the same name here. Default false (skipped)."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows what would be copied without changing anything."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`set_vault_project_keys` Put this project's own address and key in its vault

Destructive

Writes this project's own address and secret key to its vault as supabase_url and service_role_key (replacing any that exist). The values move inside the server; the answer holds names only. A scheduled job copied from another project reads these two names in its SQL, so this is needed when a project is split. Do not copy the old project's two values: the jobs would call the old project. Call it again after rotate_signing_key. Vault is switched on if it is off. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`copy_vault_secrets_from_project` Copy another project's vault secrets

Destructive

Copies vault secrets of another project of the same account (from) into this one (ref), values included. The values are read and written inside the server and never appear in the answer; only names do. Names already here are skipped (overwrite: true replaces them); names the source lacks come back as missing. Vault is switched on here if it is not. dry_run lists what would be copied. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`names`	`array<string>`	No	Secret names to copy. Empty means every secret in the source vault.
`overwrite`	`boolean`	No	true replaces a secret of the same name here. Default false (skipped).
`dry_run`	`boolean`	No	true lists what would be copied without changing anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Secret names to copy. Empty means every secret in the source vault."
    },
    "overwrite": {
      "type": "boolean",
      "description": "true replaces a secret of the same name here. Default false (skipped)."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true lists what would be copied without changing anything."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`copy_jobs_from_project` Copy another project's scheduled jobs

Destructive

Copies scheduled jobs of another project of the same account (from) into this one (ref). They arrive SWITCHED OFF unless enabled: true, so a job never runs in both places at once; turn each on with set_job_enabled once the old one is off. The source project's own name in the SQL (net_, app_ and cron_ schemas, its address) is changed to this project's before the copy is saved, and retargeted in the answer counts the changes. Jobs made with cron.schedule (scheduled_in_sql) and address jobs with sealed headers (headers_sealed) are not copied; remake them. A function job needs its function deployed here first. dry_run changes nothing. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`names`	`array<string>`	No	Job names to copy. Empty means every job.
`enabled`	`boolean`	No	true switches the copies on. Default false.
`overwrite`	`boolean`	No	true replaces a job of the same name here. Default false (skipped).
`dry_run`	`boolean`	No	true shows what would be copied without changing anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "names": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Job names to copy. Empty means every job."
    },
    "enabled": {
      "type": "boolean",
      "description": "true switches the copies on. Default false."
    },
    "overwrite": {
      "type": "boolean",
      "description": "true replaces a job of the same name here. Default false (skipped)."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows what would be copied without changing anything."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`copy_auth_from_project` Copy another project's sign-in settings

Destructive

Copies the sign-in setup of another project of the same account (from) into this one (ref): each social provider switched on there (client ID, secret and the rest, checked and recorded as update_auth_config does), the redirect allow list (as add_redirect_url adds it) and site_url only when this project's is empty. It is what lets a project be split in two without pasting a secret: the secrets move inside the server and never appear in the answer. The answer says per provider whether it was copied and why not. Sign-in fails until the answer's callback_url is registered in each provider's console. A provider already switched on here is overwritten. dry_run shows what would be copied and changes nothing. Both projects need an owner or admin (they may be in different organisations).

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`providers`	`array<string>`	No	Providers to copy (google, kakao, apple, x...). Empty means every one switched on at from.
`dry_run`	`boolean`	No	true shows what would be copied without changing anything.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "providers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Providers to copy (google, kakao, apple, x...). Empty means every one switched on at from."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows what would be copied without changing anything."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`copy_storage_from_project` Copy another project's files

Destructive

Copies the buckets and files of another project of the same account (from) into this one (ref). It moves inside the server and copies as copy_storage_from_import does: a bucket missing here is made with the source's public flag, size limit and types, and a file already here with the same size is passed over, so it can be called again. One call moves up to 200 files (max_files) or 45 seconds; when there is more, pass the answer's next to call again until done is true. A bucket's access rules are not copied. dry_run only shows. Both projects need an owner or admin.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer, `project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`from`	`string`	Yes	The ref of the project to copy from (list_projects). It must differ from ref.
`buckets`	`array<string>`	No	Bucket names to copy. Empty means all.
`rename`	`object`	No	Rename buckets {"source bucket": "bucket here"}.
`dry_run`	`boolean`	No	true shows the buckets to make and the files to move without changing anything.
`next`	`string`	No	The next from the previous answer; pass it to carry on from there.
`max_files`	`integer`, min 1, max 1000	No	The most files to move in this call (default 200, at most 1000).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "from": {
      "type": "string",
      "description": "The ref of the project to copy from (list_projects). It must differ from ref."
    },
    "buckets": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Bucket names to copy. Empty means all."
    },
    "rename": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Rename buckets {\"source bucket\": \"bucket here\"}."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows the buckets to make and the files to move without changing anything."
    },
    "next": {
      "type": "string",
      "description": "The next from the previous answer; pass it to carry on from there."
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "The most files to move in this call (default 200, at most 1000)."
    }
  },
  "required": [
    "ref",
    "from"
  ],
  "additionalProperties": false
}

`copy_storage_from_import` Copy files from an import

Destructive Reaches outside

Copies a Supabase project's buckets and files into a project here (ref), read with a Supabase account connected in import_sources. A bucket missing here is made with the source's public flag, size limit and types; files go into the same store upload_object writes to, held to the same limits. A file already here with the same size is passed over, so calling again is safe. One call copies up to 200 files (max_files) within 45 seconds; when files remain, call again with the answer's next until done is true. The answer gives each bucket's created, copied, skipped, failed and bytes, and the first few failed files. The Supabase key never appears in the conversation. Bucket access rules are not copied. dry_run shows the counts and changes nothing. Owners, admins and developers only.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Depends on the input (no question for read-only SQL or a dry_run)
REST	POST `/projects/{ref}/storage/copy-from-import`

Input

Name	Type	Required	Description
`org`	`string`	No	The organisation id or name. Empty means the ref project's organisation.
`connection`	`string`	Yes	The Supabase account (connection from import_sources, whose source is supabase).
`project`	`string`	Yes	The Supabase project ref (projects[].id from import_sources).
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`buckets`	`array<string>`	No	Supabase bucket names to copy. Empty means all of them.
`rename`	`object`	No	Bucket names to change, {"Supabase bucket": "bucket here"}. Without it a name is lowercased with spaces as - (My Files becomes my-files).
`dry_run`	`boolean`	No	true shows the buckets that would be made and the files that would be copied, without changing anything.
`next`	`string`	No	The next from the previous answer. Given, the copy carries on from there.
`max_files`	`integer`, min 1, max 1000	No	The most files to copy in this call (default 200, at most 1000).

JSON Schema

{
  "type": "object",
  "properties": {
    "org": {
      "type": "string",
      "description": "The organisation id or name. Empty means the ref project's organisation."
    },
    "connection": {
      "type": "string",
      "description": "The Supabase account (connection from import_sources, whose source is supabase)."
    },
    "project": {
      "type": "string",
      "description": "The Supabase project ref (projects[].id from import_sources)."
    },
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "buckets": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Supabase bucket names to copy. Empty means all of them."
    },
    "rename": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Bucket names to change, {\"Supabase bucket\": \"bucket here\"}. Without it a name is lowercased with spaces as - (My Files becomes my-files)."
    },
    "dry_run": {
      "type": "boolean",
      "description": "true shows the buckets that would be made and the files that would be copied, without changing anything."
    },
    "next": {
      "type": "string",
      "description": "The next from the previous answer. Given, the copy carries on from there."
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "The most files to copy in this call (default 200, at most 1000)."
    }
  },
  "required": [
    "connection",
    "project",
    "ref"
  ],
  "additionalProperties": false
}

`link_github_app` Connect a GitHub account

Destructive

Links to this project the GitHub accounts (App installations) that other projects of the same organisation already linked, as [Connect GitHub] in the console does. 409 when the organisation has none linked yet: the first one needs a person to confirm it on GitHub in the console. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_schemas` Project schemas

Read-only

The schemas the project made with SQL besides public (create schema blackquant), and whether the data API exposes each (exposed). In the database the name is app_<ref>_<name>, but SQL and clients use the name as written.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/schemas`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_exposed_schemas` Set exposed schemas

Destructive

Sets, as a whole list, the schemas the data API (/rest/v1) answers for besides public (Supabase's Exposed schemas). Use an exposed schema with the Accept-Profile / Content-Profile headers, supabase-js db: { schema } or .schema(). Row level security and the anon, authenticated and service_role privileges apply exactly as in public. An empty list exposes only public. Takes effect within 30 seconds. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/schemas/exposed`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`exposed`	`array<string>`	Yes	The schema names to expose (name from list_schemas). public is always exposed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "exposed": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The schema names to expose (name from list_schemas). public is always exposed."
    }
  },
  "required": [
    "ref",
    "exposed"
  ],
  "additionalProperties": false
}

`get_data_api_settings` Data API settings

Read-only

Whether the data API (/rest/v1) is on, the most rows one read returns (max_rows, null for no cap), the exposed schemas and the search path. search_path_choices are the schemas the search path can take: public, the schemas the project made with create schema, and extensions.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/data-api`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_data_api_settings` Change the Data API settings

Destructive

Turns the data API (/rest/v1) on or off and sets the row cap and the search path. Only what is given changes. A schema on the search path comes after the one asked for, so functions and views find its tables and functions without the schema name. Takes effect within 30 seconds. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/data-api`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	false makes every /rest/v1 request answer 404.
`max_rows`	`string`, min 1, max 1000000	No	The most rows one read returns. null for no cap.
`search_path`	`array<string>`, max items 20	No	The schemas to put on the search path (name from search_path_choices in get_data_api_settings). An empty list puts none.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "false makes every /rest/v1 request answer 404."
    },
    "max_rows": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 1000000,
      "description": "The most rows one read returns. null for no cap."
    },
    "search_path": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "description": "The schemas to put on the search path (name from search_path_choices in get_data_api_settings). An empty list puts none."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_database_settings` Database connection settings

Read-only

The database's pool size (pool_size), the direct login's connection limit (max_connections) and the API login's connection limit (api_connections). Returns what was chosen (null is the default), what Postgres holds the logins to now (enforced) and the most this server can give (limits). When scheduled jobs or functions fail with "too many connections for role", look at enforced.api_connections and limits.api_connections here first.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_database_settings` Change the database connection settings

Destructive

Sets the pool size, the direct login's connection limit and the API login's connection limit. Only what is given changes; null puts it back to the default. The connection limits reach Postgres at once (open connections are not closed) and the pool size within a minute. The API login is the one API requests and scheduled jobs share, so when it is held at 20 raise it to the limit (limits.api_connections). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`pool_size`	`string`, min 1, max 20	No	The connection pool size. null for the default.
`max_connections`	`string`, min 1, max 500	No	The direct login's (<ref>_db) connection limit. null for the default.
`api_connections`	`string`, min 1, max 500	No	The API login's (<ref>_authenticator) connection limit, up to limits.api_connections from get_database_settings. null for the default the server can give.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "pool_size": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 20,
      "description": "The connection pool size. null for the default."
    },
    "max_connections": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 500,
      "description": "The direct login's (<ref>_db) connection limit. null for the default."
    },
    "api_connections": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 500,
      "description": "The API login's (<ref>_authenticator) connection limit, up to limits.api_connections from get_database_settings. null for the default the server can give."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_branches` Database branches

Read-only

This project's database branches: name, the branch's own project ref (use it with every other tool), the git branch it is wired to, status (creating, ready, merging, resetting, failed, deleting), size and when it expires. Also returns the automatic branching settings.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/branches`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_branch` Create a database branch

Only adds

Makes a preview database from the project's schema: the project's migrations (the history apply_migrations records) are replayed in order and the seed is run. Rows are copied only with with_data. A branch is a project with a ref of its own; use that ref with run_sql, get_project_keys and every other tool. With git_branch, that branch's preview deployments use this database. Available from the Pro plan.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/branches`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	No	The branch name (lower-case letters, digits and -, up to 30). Made from git_branch when absent.
`git_branch`	`string`	No	The git branch to wire it to. That branch's preview deployments get this database's address, keys and connection string.
`with_seed`	`boolean`	No	false to skip the seed.
`with_data`	`boolean`	No	true to copy the project's rows too, instead of replaying the migrations and running the seed. Files and their rows are not copied. Refused when the data is past 512MB. Progress is under copy in list_branches.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The branch name (lower-case letters, digits and -, up to 30). Made from git_branch when absent."
    },
    "git_branch": {
      "type": "string",
      "description": "The git branch to wire it to. That branch's preview deployments get this database's address, keys and connection string."
    },
    "with_seed": {
      "type": "boolean",
      "description": "false to skip the seed."
    },
    "with_data": {
      "type": "boolean",
      "description": "true to copy the project's rows too, instead of replaying the migrations and running the seed. Files and their rows are not copied. Refused when the data is past 512MB. Progress is under copy in list_branches."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`merge_branch` Merge a database branch

Destructive

Applies the migrations only the branch has to the project (production), in version order, each in a transaction of its own; stops at the first failure, rolling back only that one. Rows do not move. Change the schema in a branch with apply_migrations, not run_sql, for it to be merged.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/branches/{name}/merge`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The branch name (name in list_branches).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The branch name (name in list_branches)."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`reset_branch` Reset a database branch

Destructive

Drops the branch's database and makes it again from the project's migrations and seed. All the branch's rows and users are lost and no backup is kept. Put the branch name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/branches/{name}/reset`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The branch name.
`confirm`	`string`	Yes	The branch name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The branch name."
    },
    "confirm": {
      "type": "string",
      "description": "The branch name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`delete_branch` Delete a database branch

Destructive

Deletes the branch with its database and keys. It cannot be undone, so put the branch name exactly in confirm. Deleting the git branch or closing its pull request deletes it automatically.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/branches/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The branch name.
`confirm`	`string`	Yes	The branch name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The branch name."
    },
    "confirm": {
      "type": "string",
      "description": "The branch name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`set_branching` Automatic database branches

Destructive

Whether a database branch is made automatically for every git branch deployed as a preview, the seed SQL every branch gets, and how many days an unused branch is kept (1 to 90, extended by every deployment). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/branching`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`automatic`	`boolean`	No	true to make one for every preview branch.
`seed_sql`	`string`	No	SQL run in every new branch after the migrations (up to 1MB). An empty string removes it.
`lifetime_days`	`integer`, min 1, max 90	No	How many days a branch is kept after its last deployment.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "automatic": {
      "type": "boolean",
      "description": "true to make one for every preview branch."
    },
    "seed_sql": {
      "type": "string",
      "description": "SQL run in every new branch after the migrations (up to 1MB). An empty string removes it."
    },
    "lifetime_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 90,
      "description": "How many days a branch is kept after its last deployment."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_queues` Queues

Read-only

The queues (the same SQL functions as pgmq: pgmq.send, pgmq.read, pgmq.pop, pgmq.archive, pgmq.delete), with how many messages each holds, how many can be read now, how many are archived and the age of the oldest. enabled says whether pgmq is installed, exposed whether the data API (pgmq_public) can call it.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/queues`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_queue` Create a queue

Only adds

Makes one queue (pgmq.create), installing pgmq the first time. Messages are kept in the table pgmq.q_<name>; in SQL, put one in with pgmq.send(name, message) and read with pgmq.read(name, seconds, count). Only in a database of its own.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/queues`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The queue name (lower-case letters, digits and _, up to 47).
`unlogged`	`boolean`	No	true for a faster table that writes no WAL (messages are lost if the server stops abnormally).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The queue name (lower-case letters, digits and _, up to 47)."
    },
    "unlogged": {
      "type": "boolean",
      "description": "true for a faster table that writes no WAL (messages are lost if the server stops abnormally)."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`delete_queue` Delete a queue

Destructive

Deletes a queue with its messages and archive (pgmq.drop_queue). It cannot be undone, so put the queue name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/queues/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The queue name.
`confirm`	`string`	Yes	The queue name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The queue name."
    },
    "confirm": {
      "type": "string",
      "description": "The queue name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`purge_queue` Empty a queue

Destructive

Deletes all of a queue's messages (pgmq.purge_queue). The archive is kept. It cannot be undone, so put the queue name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/queues/{name}/purge`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The queue name.
`confirm`	`string`	Yes	The queue name. It must be exactly the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The queue name."
    },
    "confirm": {
      "type": "string",
      "description": "The queue name. It must be exactly the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`send_queue_message` Send a message to a queue

Only adds

Puts one JSON message on a queue (pgmq.send). It cannot be read for delay seconds.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/queues/{name}/messages`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The queue name.
`message`	`string`	Yes	The message. Any JSON value.
`delay`	`integer`, min 0	No	Seconds before it can be read.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The queue name."
    },
    "message": {
      "description": "The message. Any JSON value."
    },
    "delay": {
      "type": "integer",
      "minimum": 0,
      "description": "Seconds before it can be read."
    }
  },
  "required": [
    "ref",
    "name",
    "message"
  ],
  "additionalProperties": false
}

`peek_queue` Look at queue messages

Read-only

Shows the messages at the front of a queue without taking them. Neither the read count nor the visibility time changes, so it never takes a message a worker was about to get.

Name	Description
Token scope	`read`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/queues/{name}/messages`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The queue name.
`limit`	`integer`, min 1, max 100	No	How many messages to show (20 by default).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The queue name."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "How many messages to show (20 by default)."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`set_queues_api` Open queues to the data API

Destructive

true makes the pgmq_public schema (send, send_batch, read, pop, archive, delete) so the data API can call it as supabase.schema("pgmq_public").rpc("send", ...). It runs as the caller, so for the publishable key or signed-in users to use it, grant privileges and write access rules on the queue tables. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/queues/api`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`exposed`	`boolean`	Yes	true to open, false to close.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "exposed": {
      "type": "boolean",
      "description": "true to open, false to close."
    }
  },
  "required": [
    "ref",
    "exposed"
  ],
  "additionalProperties": false
}

`list_vault_secrets` Vault secrets

Read-only

The names and descriptions of the secrets in Vault. Values are never returned. The project's code reads one with the secret key: select decrypted_secret from vault.decrypted_secrets where name = ...

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/vault`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_vault_secret` Store a Vault secret

Only adds

Encrypts one secret and stores it in vault.secrets in the project's database (vault.create_secret). The platform holds the key and it is never stored in the database, so dumps and backups hold only ciphertext. Turns Vault on the first time. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/vault`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The secret name (starts with a letter or _, up to 128).
`value`	`string`	Yes	The value to store (up to 64KB). It is not shown again.
`description`	`string`	No	A description (up to 500 characters).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The secret name (starts with a letter or _, up to 128)."
    },
    "value": {
      "type": "string",
      "description": "The value to store (up to 64KB). It is not shown again."
    },
    "description": {
      "type": "string",
      "description": "A description (up to 500 characters)."
    }
  },
  "required": [
    "ref",
    "name",
    "value"
  ],
  "additionalProperties": false
}

`update_vault_secret` Change a Vault secret

Destructive

Changes a secret's value or description (vault.update_secret). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/vault/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The secret name.
`value`	`string`	No	The new value.
`description`	`string`	No	The new description.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The secret name."
    },
    "value": {
      "type": "string",
      "description": "The new value."
    },
    "description": {
      "type": "string",
      "description": "The new description."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`delete_vault_secret` Delete a Vault secret

Destructive

Deletes one secret. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/vault/{name}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The secret name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The secret name."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`get_network_restrictions` Database network restrictions

Read-only

The addresses that may connect to the database directly (5432 and 6543) and whether TLS is required. restricted false means every address may connect. your_address_allowed says whether the address this request came from is allowed.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/network-restrictions`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`update_network_restrictions` Change database network restrictions

Destructive

Changes the addresses allowed to connect directly (a list of CIDRs, up to 100) and whether TLS is required. allow_all allows every address again. Refused without confirm when the address this request came from is not on the list. The console, the API and run_sql do not go through the pooler, so a restriction can always be undone. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/network-restrictions`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`allowed_cidrs`	`array<string>`	No	Addresses or CIDRs to allow (for example 203.0.113.0/24). An empty array lifts the restriction.
`allow_all`	`boolean`	No	true to lift the restriction and allow every address.
`enforce_ssl`	`boolean`	No	true to accept only TLS connections (sslmode=require). The default is true.
`confirm`	`boolean`	No	Saves even when the address this request came from is not on the list.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "allowed_cidrs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Addresses or CIDRs to allow (for example 203.0.113.0/24). An empty array lifts the restriction."
    },
    "allow_all": {
      "type": "boolean",
      "description": "true to lift the restriction and allow every address."
    },
    "enforce_ssl": {
      "type": "boolean",
      "description": "true to accept only TLS connections (sslmode=require). The default is true."
    },
    "confirm": {
      "type": "boolean",
      "description": "Saves even when the address this request came from is not on the list."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_transfer_targets` Organizations to transfer to

Read-only

The other organizations this project can move to (ones where you are an owner or admin), with id, name and plan. can_transfer says whether you can move it, which needs you to be an owner of its current organization. Put an id in organisation of transfer_project.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/transfer`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`transfer_project` Transfer project

Destructive

Moves the project to another organization. You must be an owner of its current organization and an owner or admin of the receiving one, and the receiving plan must have room for another project. From the move on, usage is billed to the receiving organization, so this month's bill splits at that moment. Access given to members of the old organization is removed, and only an owner of the receiving organization can move it back. Addresses, keys, data and deployments stay as they are. Use it only when the user clearly asks, and put the project name exactly in confirm.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	POST `/projects/{ref}/transfer`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`organisation`	`string`	Yes	The receiving organization id, from list_transfer_targets. Its name also works when only one has it.
`confirm`	`string`	Yes	The project name. It must be exactly the name from list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "organisation": {
      "type": "string",
      "description": "The receiving organization id, from list_transfer_targets. Its name also works when only one has it."
    },
    "confirm": {
      "type": "string",
      "description": "The project name. It must be exactly the name from list_projects."
    }
  },
  "required": [
    "ref",
    "organisation",
    "confirm"
  ],
  "additionalProperties": false
}

`get_analytics` Web analytics

Read-only

Returns page views and visitors per day, with the top pages, referrers, countries, devices, browsers and operating systems. Nothing that identifies a person is stored, so these are totals only.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/analytics`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`integer`, 1 \| 7 \| 30 \| 90	No	The period in days. 7 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": "integer",
      "enum": [
        1,
        7,
        30,
        90
      ],
      "description": "The period in days. 7 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_speed_insights` Speed Insights

Read-only

Returns the 75th percentile and rating of the Core Web Vitals (LCP, INP, CLS, FCP, TTFB) that real visitors measured, and the slowest pages.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/speed-insights`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`integer`, 1 \| 7 \| 30 \| 90	No	The period in days. 7 by default.
`device`	`string`, all \| desktop \| mobile	No	The device. all by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": "integer",
      "enum": [
        1,
        7,
        30,
        90
      ],
      "description": "The period in days. 7 by default."
    },
    "device": {
      "type": "string",
      "enum": [
        "all",
        "desktop",
        "mobile"
      ],
      "description": "The device. all by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_insights` Turn analytics on or off

Destructive

Turns Web Analytics and Speed Insights on or off. When on, the site's HTML gets the /_oneend/insights/script.js script. Apps that use Vercel's @vercel/analytics and @vercel/speed-insights are counted in the same place with no code change. No cookies are used and no address is stored. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/insights`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`analytics`	`boolean`	No	Web Analytics.
`speed_insights`	`boolean`	No	Speed Insights.
`vitals_sample_percent`	`integer`, min 1, max 100	No	The share of visits whose speed is measured.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "analytics": {
      "type": "boolean",
      "description": "Web Analytics."
    },
    "speed_insights": {
      "type": "boolean",
      "description": "Speed Insights."
    },
    "vitals_sample_percent": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "The share of visits whose speed is measured."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_edge_config` Read edge config

Read-only

Returns the project's edge config (values and feature flags that change without a deploy), with its version, size and limits.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/edge-config`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_edge_config` Change edge config

Destructive

Sets or deletes keys. Every server has the change within a few seconds, and it is kept in the history. A flag is true or false, or {"enabled": true, "percent": 20}, or {"enabled": true, "allow": ["user-1"]}. Developers and above can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/edge-config`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`set`	`object`	No	Keys and values to set (values are JSON).
`delete`	`array<string>`	No	Keys to delete.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "set": {
      "type": "object",
      "additionalProperties": true,
      "description": "Keys and values to set (values are JSON)."
    },
    "delete": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Keys to delete."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_edge_config_history` Edge config history

Read-only

Returns who changed which key, when, from what to what, most recent first.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/edge-config/history`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`limit`	`integer`, min 1, max 500	No	How many. 50 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "How many. 50 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_rolling_releases` Rolling releases

Read-only

Returns the rolling release settings, the release in progress (the share of visitors the new deployment gets), and recent ones.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/rolling-releases`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_rolling_releases` Rolling release settings

Destructive

Decides whether new production deployments go out in stages. stages is a rising list of shares (for example [10, 50]), stage_minutes the length of each, and with auto_advance false each stage waits for approval. Above abort_error_rate (0.05 is 5%) the release is rolled back automatically. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/rolling-releases`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	On.
`stages`	`array<integer>`	No	The share at each stage (%).
`stage_minutes`	`integer`, min 1, max 1440	No	Stage length in minutes.
`auto_advance`	`boolean`	No	Move on automatically as time passes.
`abort_error_rate`	`string`, min 0.001, max 1	No	The 5xx rate that stops it automatically. null turns it off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "On."
    },
    "stages": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 99
      },
      "description": "The share at each stage (%)."
    },
    "stage_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1440,
      "description": "Stage length in minutes."
    },
    "auto_advance": {
      "type": "boolean",
      "description": "Move on automatically as time passes."
    },
    "abort_error_rate": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0.001,
      "maximum": 1,
      "description": "The 5xx rate that stops it automatically. null turns it off."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`advance_rolling_release` Advance a rolling release

Destructive

Moves the release in progress to its next stage. From the last stage it goes to everybody. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/rolling-releases/{action}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`promote_rolling_release` Complete a rolling release

Destructive

Sends the release in progress to every visitor now. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`abort_rolling_release` Stop a rolling release

Destructive

Stops the release in progress and serves the previous production deployment again. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`reason`	`string`, max length 300	No	Why, for the record.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "reason": {
      "type": "string",
      "maxLength": 300,
      "description": "Why, for the record."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_kv_keys` KV keys

Read-only

Returns the KV store's keys by prefix, 50 at a time, with usage, limits and the REST address. Only roles that may see secrets can do this.

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/kv`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`prefix`	`string`	No	A prefix.
`cursor`	`string`	No	The cursor from the previous answer.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "prefix": {
      "type": "string",
      "description": "A prefix."
    },
    "cursor": {
      "type": "string",
      "description": "The cursor from the previous answer."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_kv` Read a KV value

Read-only

Returns one key's value and the seconds it has left (ttl, -1 for no expiry).

Name	Description
Token scope	`read`
Roles	`secrets.read` owner or admin or developer
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/kv/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`	Yes	The key.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "description": "The key."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`set_kv` Save a KV value

Destructive

Stores a JSON value at a key. ttl is the seconds until it expires. Developers and above can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/kv/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`	Yes	The key.
`value`	`string`	Yes	The value (JSON).
`ttl`	`integer`, min 1	No	Seconds until it expires.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "description": "The key."
    },
    "value": {
      "description": "The value (JSON)."
    },
    "ttl": {
      "type": "integer",
      "minimum": 1,
      "description": "Seconds until it expires."
    }
  },
  "required": [
    "ref",
    "key",
    "value"
  ],
  "additionalProperties": false
}

`delete_kv` Delete a KV key

Destructive

Deletes a key. Developers and above can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/kv/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`	Yes	The key.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "description": "The key."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`get_ai_gateway` AI gateway

Read-only

Returns the AI gateway's OpenAI-compatible address, its settings, its providers (keys as their last four characters only), and the last 30 days of use.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/ai-gateway`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_ai_gateway` AI gateway settings

Destructive

Turns the AI gateway on or off and sets whether signed-in users may call it, the cache in seconds, the requests per minute, the fallback to the platform's provider (billed per token), and the daily requests and tokens one user of the app may use. The user is a signed-in user's id, or, with the secret key, the x-oneend-user header or the body's user. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/ai-gateway`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	On.
`allow_users`	`boolean`	No	Allow signed-in users.
`cache_seconds`	`integer`, min 0, max 86400	No	Cache seconds.
`rate_per_minute`	`integer`, min 1	No	Requests per minute.
`platform_fallback`	`boolean`	No	Fall back to the platform provider.
`user_daily_requests`	`string`, min 1	No	Requests one app user may make a day; null for no limit.
`user_daily_tokens`	`string`, min 1	No	Tokens one app user may use a day; null for no limit.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "On."
    },
    "allow_users": {
      "type": "boolean",
      "description": "Allow signed-in users."
    },
    "cache_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 86400,
      "description": "Cache seconds."
    },
    "rate_per_minute": {
      "type": "integer",
      "minimum": 1,
      "description": "Requests per minute."
    },
    "platform_fallback": {
      "type": "boolean",
      "description": "Fall back to the platform provider."
    },
    "user_daily_requests": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "Requests one app user may make a day; null for no limit."
    },
    "user_daily_tokens": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "Tokens one app user may use a day; null for no limit."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`add_ai_provider` Add an AI provider

Only adds

Adds a provider with its key: OpenAI-compatible, Anthropic (translated to and from its Messages API) or Google Gemini. Only public https addresses are accepted. The key is sealed and never shown again. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/ai-gateway/providers`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, pattern ^[a-z][a-z0-9-]{0,39}$	Yes	A name; calling name/model calls this provider only.
`kind`	`string`, openai \| anthropic \| google \| deepseek \| openai-compatible	Yes	The type.
`base_url`	`string`	No	The address. Optional for openai, anthropic, google and deepseek.
`key`	`string`	No	The API key.
`models`	`array<string>`	No	The models it takes. Empty for any.
`priority`	`integer`, min 0, max 1000	No	Priority, lowest first.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]{0,39}$",
      "description": "A name; calling name/model calls this provider only."
    },
    "kind": {
      "type": "string",
      "enum": [
        "openai",
        "anthropic",
        "google",
        "deepseek",
        "openai-compatible"
      ],
      "description": "The type."
    },
    "base_url": {
      "type": "string",
      "description": "The address. Optional for openai, anthropic, google and deepseek."
    },
    "key": {
      "type": "string",
      "description": "The API key."
    },
    "models": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The models it takes. Empty for any."
    },
    "priority": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000,
      "description": "Priority, lowest first."
    }
  },
  "required": [
    "ref",
    "name",
    "kind"
  ],
  "additionalProperties": false
}

`set_ai_provider_enabled` Turn an AI provider off or on

Destructive

Stops or resumes using a provider and keeps its settings and key. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/ai-gateway/providers/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id get_ai_gateway returned.
`enabled`	`boolean`	Yes	Use it.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id get_ai_gateway returned."
    },
    "enabled": {
      "type": "boolean",
      "description": "Use it."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_ai_provider` Remove an AI provider

Destructive

Removes a provider and its sealed key. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/ai-gateway/providers/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id get_ai_gateway returned.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id get_ai_gateway returned."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_ai_gateway_logs` AI gateway calls

Read-only

Returns recent calls with their provider, model, status, tokens, latency and whether they fell back. Conversations are not stored.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/ai-gateway/logs`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`limit`	`integer`, min 1, max 500	No	How many. 50 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "description": "How many. 50 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_middleware` Middleware settings

Read-only

Returns whether the site's middleware (middleware.ts) runs and its time limit.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/middleware`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_middleware` Change middleware settings

Destructive

Turns the site's middleware off or on and sets its time limit (100 to 5000ms). Off serves without middleware, with no new deploy. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/middleware`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	Run it.
`timeout_ms`	`integer`, min 100, max 5000	No	Time limit (ms).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "Run it."
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 100,
      "maximum": 5000,
      "description": "Time limit (ms)."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_ai_budgets` AI gateway budgets

Destructive

Sets the project's AI gateway budgets in dollars (day, week and month, UTC). Once one is spent, calls are refused until the next period. A value left out is kept. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/ai-gateway/budgets`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`daily_usd`	`string`, min 0, max 1000000	No	The daily (UTC) budget in dollars. null for none.
`weekly_usd`	`string`, min 0, max 1000000	No	The weekly (from Monday, UTC) budget in dollars. null for none.
`monthly_usd`	`string`, min 0, max 1000000	No	The monthly (UTC) budget in dollars. null for none.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "daily_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The daily (UTC) budget in dollars. null for none."
    },
    "weekly_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The weekly (from Monday, UTC) budget in dollars. null for none."
    },
    "monthly_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The monthly (UTC) budget in dollars. null for none."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_ai_gateway_keys` AI gateway keys

Read-only

Returns the gateway keys with their names, prefixes, budgets, this month's spend and when each was last used. Never the keys themselves.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/ai-gateway/keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_ai_gateway_key` Create an AI gateway key

Only adds

Creates a gateway key (bwai_…) for one app, or for one customer the project resells AI to, with its own budgets, tag and limits per minute. The key is in this answer once and never again. Keys with a tag (external_ref) do not count toward the 50 keys a project may have. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/ai-gateway/keys`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 60	Yes	The key's name.
`daily_usd`	`string`, min 0, max 1000000	No	The daily (UTC) budget in dollars. null for none.
`weekly_usd`	`string`, min 0, max 1000000	No	The weekly (from Monday, UTC) budget in dollars. null for none.
`monthly_usd`	`string`, min 0, max 1000000	No	The monthly (UTC) budget in dollars. null for none.
`external_ref`	`string`, max length 200	No	Who the key stands for in the project's own books, such as a customer's user id. Sent to the hooks.
`labels`	`object`	No	Up to 20 free labels, such as {"tier": "1"}. Sent to the hooks.
`rate_per_minute`	`string`, min 1, max 100000	No	Requests per minute. null for none.
`tokens_per_minute`	`string`, min 1, max 100000000	No	Tokens per minute, prompt and completion. null for none.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "The key's name."
    },
    "daily_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The daily (UTC) budget in dollars. null for none."
    },
    "weekly_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The weekly (from Monday, UTC) budget in dollars. null for none."
    },
    "monthly_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The monthly (UTC) budget in dollars. null for none."
    },
    "external_ref": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 200,
      "description": "Who the key stands for in the project's own books, such as a customer's user id. Sent to the hooks."
    },
    "labels": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 100
      },
      "description": "Up to 20 free labels, such as {\"tier\": \"1\"}. Sent to the hooks."
    },
    "rate_per_minute": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 100000,
      "description": "Requests per minute. null for none."
    },
    "tokens_per_minute": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 100000000,
      "description": "Tokens per minute, prompt and completion. null for none."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`set_ai_gateway_key_budgets` AI gateway key budgets

Destructive

Changes one gateway key's budgets. A value left out is kept. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/ai-gateway/keys/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id list_ai_gateway_keys returned.
`daily_usd`	`string`, min 0, max 1000000	No	The daily (UTC) budget in dollars. null for none.
`weekly_usd`	`string`, min 0, max 1000000	No	The weekly (from Monday, UTC) budget in dollars. null for none.
`monthly_usd`	`string`, min 0, max 1000000	No	The monthly (UTC) budget in dollars. null for none.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id list_ai_gateway_keys returned."
    },
    "daily_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The daily (UTC) budget in dollars. null for none."
    },
    "weekly_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The weekly (from Monday, UTC) budget in dollars. null for none."
    },
    "monthly_usd": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 1000000,
      "description": "The monthly (UTC) budget in dollars. null for none."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`set_ai_gateway_key_limits` AI gateway key limits

Destructive

Changes one gateway key's limits on requests and tokens per minute. Every server counts the same minute. A value left out is kept; null removes the limit. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/ai-gateway/keys/{id}/limits`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id list_ai_gateway_keys returned.
`rate_per_minute`	`string`, min 1, max 100000	No	Requests per minute. null for none.
`tokens_per_minute`	`string`, min 1, max 100000000	No	Tokens per minute, prompt and completion. null for none.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id list_ai_gateway_keys returned."
    },
    "rate_per_minute": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 100000,
      "description": "Requests per minute. null for none."
    },
    "tokens_per_minute": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 100000000,
      "description": "Tokens per minute, prompt and completion. null for none."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`set_ai_model_aliases` AI model aliases

Destructive

Sets the model names callers use (aliases) and the model each is sent to, each with an optional system prompt put first. Answers carry the alias as their model. The list given replaces the whole list. With aliases_only on, nothing but an alias can be asked for and /models lists only the aliases. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/ai-gateway/aliases`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`aliases`	`array<object>`, max items 50	Yes	Every alias. An empty list removes them all.
`aliases_only`	`boolean`	No	Allow aliases only. Kept as it is when left out.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "aliases": {
      "type": "array",
      "maxItems": 50,
      "description": "Every alias. An empty list removes them all.",
      "items": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$",
            "description": "The name callers use, such as blackall-air."
          },
          "target": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "description": "The model it is sent to, such as deepseek/deepseek-flash."
          },
          "system_prompt": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20000,
            "description": "A system prompt put first. The caller's own instructions follow it."
          }
        },
        "required": [
          "alias",
          "target"
        ],
        "additionalProperties": false
      }
    },
    "aliases_only": {
      "type": "boolean",
      "description": "Allow aliases only. Kept as it is when left out."
    }
  },
  "required": [
    "ref",
    "aliases"
  ],
  "additionalProperties": false
}

`set_ai_gateway_hooks` AI gateway hooks

Destructive

Sets the https address asked before, and told after, every call made with a gateway key. If ai.before does not answer 2xx within timeout_ms, the call is refused (a 402 is passed on as a low balance). ai.after carries the usage, cost and status, and is sent again for a day until it is taken. The answer holds the signing secret. A null url turns hooks off. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/ai-gateway/hooks`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`url`	`string`, max length 500	No	The hook address (https). null turns hooks off.
`timeout_ms`	`integer`, min 200, max 10000	No	How long ai.before may take to answer, in milliseconds. 2000 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 500,
      "description": "The hook address (https). null turns hooks off."
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 200,
      "maximum": 10000,
      "description": "How long ai.before may take to answer, in milliseconds. 2000 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`revoke_ai_gateway_key` Revoke an AI gateway key

Destructive

Revokes a gateway key. Every server refuses it within 30 seconds. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/ai-gateway/keys/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id list_ai_gateway_keys returned.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id list_ai_gateway_keys returned."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_ai_spend` AI gateway spend

Read-only

Returns today's, this week's and this month's spend against the budgets, and spend per day, model and key, in dollars. Calls to a provider with the project's own key are estimated at list price.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/ai-gateway/spend`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`integer`, min 1, max 400	No	How many days. 30 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 400,
      "description": "How many days. 30 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_analytics_breakdown` Web Analytics breakdown

Read-only

Returns campaigns (utm_source, utm_medium, utm_campaign), routes, custom events and how many bots were filtered. With event, also that event's values per property. Totals only.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/analytics/breakdown`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`integer`, 1 \| 7 \| 30 \| 90	No	The period. 7 by default.
`event`	`string`, max length 100	No	The event whose properties to break down.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": "integer",
      "enum": [
        1,
        7,
        30,
        90
      ],
      "description": "The period. 7 by default."
    },
    "event": {
      "type": "string",
      "maxLength": 100,
      "description": "The event whose properties to break down."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_analytics_previews` Count preview visits

Destructive

Sets whether visits to preview deployments and dpl- addresses count in Web Analytics. Off (the default), previews get no script and what they send is dropped. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/analytics/previews`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`include_previews`	`boolean`	Yes	Count previews too.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "include_previews": {
      "type": "boolean",
      "description": "Count previews too."
    }
  },
  "required": [
    "ref",
    "include_previews"
  ],
  "additionalProperties": false
}

`export_analytics` Export Web Analytics

Read-only

Returns the period's totals as a CSV string, by day, dimension and value.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/analytics/export`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`integer`, 1 \| 7 \| 30 \| 90	No	The period. 7 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": "integer",
      "enum": [
        1,
        7,
        30,
        90
      ],
      "description": "The period. 7 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_analytics_reports` Custom reports

Read-only

Returns the saved Web Analytics reports and the names of the charts a report can hold.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/analytics/reports`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_analytics_report` Show a custom report

Read-only

Returns one saved report with its period's totals, breakdowns and speed.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/analytics/reports/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id list_analytics_reports returned.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id list_analytics_reports returned."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`save_analytics_report` Save a custom report

Destructive

Creates a report, or changes the one id names. Developers and above can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/analytics/reports`, PATCH `/projects/{ref}/analytics/reports`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	No	The id of the report to change. Empty to create one.
`name`	`string`, min length 1, max length 80	Yes	The name.
`days`	`integer`, 1 \| 7 \| 30 \| 90	No	The period. 7 by default.
`widgets`	`array<string>`, views \| visitors \| path \| referrer \| country \| device \| browser \| os \| utm_source \| utm_medium \| utm_campaign \| route \| event \| bot \| vitals, min items 1, max items 16	Yes	The charts and tables to show.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id of the report to change. Empty to create one."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "The name."
    },
    "days": {
      "type": "integer",
      "enum": [
        1,
        7,
        30,
        90
      ],
      "description": "The period. 7 by default."
    },
    "widgets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "views",
          "visitors",
          "path",
          "referrer",
          "country",
          "device",
          "browser",
          "os",
          "utm_source",
          "utm_medium",
          "utm_campaign",
          "route",
          "event",
          "bot",
          "vitals"
        ]
      },
      "minItems": 1,
      "maxItems": 16,
      "description": "The charts and tables to show."
    }
  },
  "required": [
    "ref",
    "name",
    "widgets"
  ],
  "additionalProperties": false
}

`remove_analytics_report` Delete a custom report

Destructive

Deletes the report only; the analytics stay as they are. Developers and above can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/analytics/reports/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The id list_analytics_reports returned.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id list_analytics_reports returned."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_flags` Feature flags

Read-only

Returns the project's feature flags together with the flag-shaped values kept in its edge config. source says where each is kept and shadows whether it hides an edge config value of the same key. Where both have a key, the flag decides.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/flags`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`evaluate_flag` Evaluate a feature flag

Read-only

Returns what the app would get: with a context (e.g. {"user": {"id": "u1"}}) and an environment, the flag's rules decide; with no flag of that key, the edge config value does. source says which decided.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/flags/evaluate`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 256	Yes	The flag key.
`environment`	`string`	No	The environment. production by default.
`context`	`object`	No	The context to evaluate for (a JSON object).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 256,
      "description": "The flag key."
    },
    "environment": {
      "type": "string",
      "description": "The environment. production by default."
    },
    "context": {
      "type": "object",
      "description": "The context to evaluate for (a JSON object)."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`set_flag_enabled` Turn a feature flag on or off

Destructive

Turns a flag on or off in one environment. Production takes owners and admins; other environments, developers and above.

Name	Description
Token scope	`write`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/flags/{key}/environments/{environment}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`environment`	`string`	Yes	The environment.
`enabled`	`boolean`	Yes	On.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "environment": {
      "type": "string",
      "description": "The environment."
    },
    "enabled": {
      "type": "boolean",
      "description": "On."
    }
  },
  "required": [
    "ref",
    "key",
    "environment",
    "enabled"
  ],
  "additionalProperties": false
}

`get_remote_cache` Remote cache

Read-only

Returns the Turborepo remote cache's address, how many outputs it holds and their size, the last 30 days' hits and uploads, and this month's metered storage (remote_cache_gb_hour) with its price. Downloads are counted as egress_gb.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/remote-cache`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`clear_remote_cache` Clear the remote cache

Destructive

Deletes every stored output. The next builds fill it again, and the metered storage drops by what was cleared. Developers and above can do this.

Name	Description
Token scope	`write`
Roles	`data.write` owner or admin or developer
Console assistant confirmation	Does not ask
REST	DELETE `/projects/{ref}/remote-cache/artifacts`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_queue_metrics` Queue metrics

Read-only

From the queue samples taken every five minutes: each queue's current depth, ready messages, oldest wait and archived count, and across all queues the depth, messages sent and messages processed over time. 24 hours by default, up to 168.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/queues/metrics`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hours`	`integer`, min 1, max 168	No	How many hours. 24 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 168,
      "description": "How many hours. 24 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_edge_config_tokens` Edge config read tokens

Read-only

Returns the read tokens other projects read this project's edge config with, the projects each is connected to (variable name, environments), and other projects' edge configs connected to this one. The tokens themselves are not returned.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/edge-config/tokens`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_edge_config_token` Create an edge config read token

Only adds

Creates a read token and, with connect, connects it to a project in the same organization. From its next deployment, that project gets the connection string (https://<ref>.<zone>/config/v1?token=…) as a variable. The token is shown only this once. Project admins only.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/edge-config/tokens`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 60	Yes	The token's name.
`connect`	`object`	No	A project in the same organization to connect right away: ref, the variable name (GLOBAL_CONFIG by default) and targets (all three environments by default; production only by that project's owners and admins).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "The token's name."
    },
    "connect": {
      "type": "object",
      "properties": {
        "ref": {
          "type": "string",
          "pattern": "^[a-z]{20}$"
        },
        "variable": {
          "type": "string",
          "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
        },
        "targets": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "production",
              "preview",
              "development"
            ]
          },
          "minItems": 1,
          "uniqueItems": true
        }
      },
      "required": [
        "ref"
      ],
      "additionalProperties": false,
      "description": "A project in the same organization to connect right away: ref, the variable name (GLOBAL_CONFIG by default) and targets (all three environments by default; production only by that project's owners and admins)."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`connect_edge_config_token` Connect a read token to a project

Destructive

Connects a read token to another project in the organization as a variable in its deployments. If already connected, changes the variable name and environments. Takes a developer or above of that project (owners and admins for production).

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/edge-config/tokens/{id}/connections/{ref}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The read token id, from list_edge_config_tokens.
`target`	`string`, pattern ^[a-z]{20}$	Yes	A project in the same organization to connect.
`variable`	`string`, pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$	No	The variable deployments read. GLOBAL_CONFIG by default.
`targets`	`array<string>`, production \| preview \| development, min items 1	No	Environments that get the variable. All three by default; production only by that project's owners and admins.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The read token id, from list_edge_config_tokens."
    },
    "target": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "A project in the same organization to connect."
    },
    "variable": {
      "type": "string",
      "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
      "description": "The variable deployments read. GLOBAL_CONFIG by default."
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "production",
          "preview",
          "development"
        ]
      },
      "minItems": 1,
      "uniqueItems": true,
      "description": "Environments that get the variable. All three by default; production only by that project's owners and admins."
    }
  },
  "required": [
    "ref",
    "id",
    "target"
  ],
  "additionalProperties": false
}

`disconnect_edge_config_token` Disconnect a read token

Destructive

Takes a read token out of one project. The variable leaves with that project's next deployment.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	DELETE `/projects/{ref}/edge-config/tokens/{id}/connections/{ref}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The read token id, from list_edge_config_tokens.
`target`	`string`, pattern ^[a-z]{20}$	Yes	A project in the same organization to connect.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The read token id, from list_edge_config_tokens."
    },
    "target": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "A project in the same organization to connect."
    }
  },
  "required": [
    "ref",
    "id",
    "target"
  ],
  "additionalProperties": false
}

`revoke_edge_config_token` Revoke a read token

Destructive

Revokes a read token. It stops reading at once, and connected projects lose the variable with their next deployment.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Always asks
REST	DELETE `/projects/{ref}/edge-config/tokens/{id}`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	The read token id, from list_edge_config_tokens.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The read token id, from list_edge_config_tokens."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_deployment_retention` Deployment retention

Read-only

Returns how many days canceled, failed, preview and production deployments are kept: the days in force (days), the project's own number (project_days, null when it follows the plan) and the plan default (plan_days). Also what is kept whatever the period (always_kept) and how many days a deleted deployment can be restored (restore_days).

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/deployment-retention`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_deployment_retention` Change deployment retention

Destructive

Changes how long each kind of deployment is kept. A deployment past its period is deleted and can be restored with restore_deployment for 3 days. Recent and served deployments are kept whatever the period. Only project admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/deployment-retention`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`canceled_days`	`string`, min 1, max 3650	No	Days to keep canceled or skipped deployments (1 to 3650). null for the plan default. Left out: kept as it is.
`error_days`	`string`, min 1, max 3650	No	Days to keep failed deployments (1 to 3650). null for the plan default. Left out: kept as it is.
`preview_days`	`string`, min 1, max 3650	No	Days to keep preview deployments (1 to 3650). null for the plan default. Left out: kept as it is.
`production_days`	`string`, min 1, max 3650	No	Days to keep production deployments (1 to 3650). null for the plan default. Left out: kept as it is.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "canceled_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 3650,
      "description": "Days to keep canceled or skipped deployments (1 to 3650). null for the plan default. Left out: kept as it is."
    },
    "error_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 3650,
      "description": "Days to keep failed deployments (1 to 3650). null for the plan default. Left out: kept as it is."
    },
    "preview_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 3650,
      "description": "Days to keep preview deployments (1 to 3650). null for the plan default. Left out: kept as it is."
    },
    "production_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 3650,
      "description": "Days to keep production deployments (1 to 3650). null for the plan default. Left out: kept as it is."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_protection_scope` Preview protection scope

Destructive

Sets which addresses are protected and what passes. scope: previews (branch previews and per-deployment addresses), generated (production's own address too) or all (connected domains too). trusted_ips are addresses or CIDR ranges let in without signing in (up to 100); options_paths are paths that pass unchecked, for example /api/:path* (up to 50). A field left out keeps its value. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`scope`	`string`, previews \| generated \| all	No	previews, generated or all.
`trusted_ips`	`array<string>`	No	IP addresses or CIDR ranges, for example ["203.0.113.4", "10.0.0.0/8"]. [] clears them.
`options_paths`	`array<string>`	No	Paths starting with /, for example ["/api/:path*"]. [] clears them.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "scope": {
      "type": "string",
      "enum": [
        "previews",
        "generated",
        "all"
      ],
      "description": "previews, generated or all."
    },
    "trusted_ips": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "IP addresses or CIDR ranges, for example [\"203.0.113.4\", \"10.0.0.0/8\"]. [] clears them."
    },
    "options_paths": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Paths starting with /, for example [\"/api/:path*\"]. [] clears them."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_bypass_secret` Create a protection bypass key

Only adds

Creates a key that opens protected addresses without signing in. Send it in the x-blackwall-protection-bypass header from end-to-end tests, or when an assistant checks a preview it deployed. The value is in this response only. Up to 20 per project. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, max length 60	No	What the key is for. automation when empty.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "maxLength": 60,
      "description": "What the key is for. automation when empty."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`revoke_bypass_secret` Revoke a protection bypass key

Destructive

Deletes a bypass key. Requests carrying it are refused at once. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	A bypass_secrets[].id from get_preview_protection.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "A bypass_secrets[].id from get_preview_protection."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`create_share_link` Create a share link

Only adds

Creates a link that opens one deployment, or one branch's preview, to anybody holding it. Give deployment or branch, not both. It expires after 1 to 30 days (7 by default) and revoke_share_link closes it at once. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`deployment`	`string`	No	A deployment id from list_deployments (starts with dpl-).
`branch`	`string`	No	A branch name.
`days`	`integer`, min 1, max 30	No	Days it stays valid. 7 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "deployment": {
      "type": "string",
      "description": "A deployment id from list_deployments (starts with dpl-)."
    },
    "branch": {
      "type": "string",
      "description": "A branch name."
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 30,
      "description": "Days it stays valid. 7 by default."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`revoke_share_link` Revoke a share link

Destructive

Closes a share link at once. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	A share_links[].id from get_preview_protection.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "A share_links[].id from get_preview_protection."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_environments` Environments

Read-only

Returns production and the environments the project made itself (staging, qa and so on): the branch each follows, whether it takes builds by itself (auto_assign), its address, its domains and the deployment it serves now. Also returns the domains that can be pointed at one (domains) and whether builds get the system environment variables (expose_system_env).

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_environment` Create an environment

Only adds

Creates an environment such as staging, with its own address, domains and environment variables (its name as the target in set_env_vars). Lowercase letters, digits and - up to 40 characters; production, preview and development are taken. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, pattern ^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$	Yes	The environment name, for example staging.
`branch`	`string`	No	The branch this environment follows: an exact name (staging) or a prefix ending in * (release/*). Empty or null takes deployments only through promote_deployment.
`auto_assign`	`boolean`	No	With true (the default) each finished build goes out to this environment; with false it waits for promote_deployment.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "pattern": "^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$",
      "description": "The environment name, for example staging."
    },
    "branch": {
      "type": [
        "string",
        "null"
      ],
      "description": "The branch this environment follows: an exact name (staging) or a prefix ending in * (release/*). Empty or null takes deployments only through promote_deployment."
    },
    "auto_assign": {
      "type": "boolean",
      "description": "With true (the default) each finished build goes out to this environment; with false it waits for promote_deployment."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`update_environment` Change an environment

Destructive

Changes the branch an environment follows and whether it takes builds by itself. Production takes only auto_assign (its branch is production_branch in update_app). A field left out keeps its value. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The name from list_environments.
`branch`	`string`	No	The branch this environment follows: an exact name (staging) or a prefix ending in * (release/*). Empty or null takes deployments only through promote_deployment.
`auto_assign`	`boolean`	No	With true (the default) each finished build goes out to this environment; with false it waits for promote_deployment.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The name from list_environments."
    },
    "branch": {
      "type": [
        "string",
        "null"
      ],
      "description": "The branch this environment follows: an exact name (staging) or a prefix ending in * (release/*). Empty or null takes deployments only through promote_deployment."
    },
    "auto_assign": {
      "type": "boolean",
      "description": "With true (the default) each finished build goes out to this environment; with false it waits for promote_deployment."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`remove_environment` Remove an environment

Destructive

Removes an environment the project made. Its deployments stay as history; its address, its domains' pointing at it and its environment variables go. Production cannot be removed. Use it only when the user asks, with the environment name in confirm. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`	Yes	The name from list_environments.
`confirm`	`string`	Yes	The environment name. Must equal name exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "description": "The name from list_environments."
    },
    "confirm": {
      "type": "string",
      "description": "The environment name. Must equal name exactly."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`set_domain_environment` Point a domain at an environment

Destructive

Chooses which environment (production or one the project made) a verified domain serves, for example staging.example.com for staging. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`hostname`	`string`	Yes	A domains[].hostname from list_environments.
`environment`	`string`	Yes	The name from list_environments.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "hostname": {
      "type": "string",
      "description": "A domains[].hostname from list_environments."
    },
    "environment": {
      "type": "string",
      "description": "The name from list_environments."
    }
  },
  "required": [
    "ref",
    "hostname",
    "environment"
  ],
  "additionalProperties": false
}

`get_flag` Feature flag

Read-only

Returns one flag in full: its kind, its variants and, for each environment, whether it is on, the variant served when off (off_variant), what is served by default (fallthrough) and its rules (rules, the first that matches from the top wins). Also returns the environment names it can be changed in.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`create_flag` Create a feature flag

Only adds

Creates a flag, off in every environment. A boolean flag gets the variants on (true) and off (false). The key starts and ends with a lowercase letter or digit and may hold dots, underscores and hyphens, up to 64 characters. Up to 500 per project. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`kind`	`string`, boolean \| string \| number \| json	Yes	boolean, string, number or json.
`description`	`string`, max length 500	No	What the flag is for, up to 500 characters.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "kind": {
      "type": "string",
      "enum": [
        "boolean",
        "string",
        "number",
        "json"
      ],
      "description": "boolean, string, number or json."
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "What the flag is for, up to 500 characters."
    }
  },
  "required": [
    "ref",
    "key",
    "kind"
  ],
  "additionalProperties": false
}

`update_flag` Change a feature flag

Destructive

Changes the description and the variants. variants is the whole list; a variant an environment uses cannot be removed, and each value must suit the flag's kind. A field left out keeps its value. Variants are served in every environment, so only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`description`	`string`, max length 500	No	Up to 500 characters.
`variants`	`array<object>`	No	For example [{"id": "control", "value": "blue"}, {"id": "test", "value": "green"}].

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Up to 500 characters."
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "value": {}
        },
        "required": [
          "id",
          "value"
        ]
      },
      "description": "For example [{\"id\": \"control\", \"value\": \"blue\"}, {\"id\": \"test\", \"value\": \"green\"}]."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`set_flag_environment` Flag settings in an environment

Destructive

Sets, in one environment, whether the flag is on (enabled), the variant served when off (off_variant) and what is served when no rule matches (serve). A field left out keeps its value. Production takes owners and admins; any other environment, developers and above.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`environment`	`string`	Yes	The environment: production, preview, development, or one the project made (list_environments).
`enabled`	`boolean`	No	On or off.
`off_variant`	`string`	No	A variant id served while the flag is off.
`serve`	`object`	No	What to serve. One variant: {"variant": "on"}. A split: {"rollout": [{"variant": "on", "weight": 20}, {"variant": "off", "weight": 80}], "bucket_by": "user.id"} (weights add up to 100).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "environment": {
      "type": "string",
      "description": "The environment: production, preview, development, or one the project made (list_environments)."
    },
    "enabled": {
      "type": "boolean",
      "description": "On or off."
    },
    "off_variant": {
      "type": "string",
      "description": "A variant id served while the flag is off."
    },
    "serve": {
      "type": "object",
      "description": "What to serve. One variant: {\"variant\": \"on\"}. A split: {\"rollout\": [{\"variant\": \"on\", \"weight\": 20}, {\"variant\": \"off\", \"weight\": 80}], \"bucket_by\": \"user.id\"} (weights add up to 100).",
      "properties": {
        "variant": {
          "type": "string"
        },
        "rollout": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "variant": {
                "type": "string"
              },
              "weight": {
                "type": "number"
              }
            },
            "required": [
              "variant",
              "weight"
            ]
          }
        },
        "bucket_by": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "ref",
    "key",
    "environment"
  ],
  "additionalProperties": false
}

`add_flag_rule` Add a flag rule

Destructive

Adds a rule at the bottom of one environment's rules: a context that meets every condition is served serve. For example, on when user.email ends with @example.com. Production takes owners and admins; any other environment, developers and above.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`environment`	`string`	Yes	The environment: production, preview, development, or one the project made (list_environments).
`conditions`	`array<object>`, min items 1, max items 3	Yes	1 to 3 conditions that must all hold. attribute is a dot path into the context (user.email); a value cannot contain a comma. For in_segment and not_in_segment, values are segment keys.
`serve`	`object`	Yes	What to serve. One variant: {"variant": "on"}. A split: {"rollout": [{"variant": "on", "weight": 20}, {"variant": "off", "weight": 80}], "bucket_by": "user.id"} (weights add up to 100).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "environment": {
      "type": "string",
      "description": "The environment: production, preview, development, or one the project made (list_environments)."
    },
    "conditions": {
      "type": "array",
      "minItems": 1,
      "maxItems": 3,
      "description": "1 to 3 conditions that must all hold. attribute is a dot path into the context (user.email); a value cannot contain a comma. For in_segment and not_in_segment, values are segment keys.",
      "items": {
        "type": "object",
        "properties": {
          "attribute": {
            "type": "string"
          },
          "op": {
            "type": "string",
            "enum": [
              "is",
              "is_not",
              "contains",
              "not_contains",
              "starts_with",
              "ends_with",
              "domain_is",
              "gt",
              "lt",
              "exists",
              "not_exists",
              "in_segment",
              "not_in_segment"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "op"
        ]
      }
    },
    "serve": {
      "type": "object",
      "description": "What to serve. One variant: {\"variant\": \"on\"}. A split: {\"rollout\": [{\"variant\": \"on\", \"weight\": 20}, {\"variant\": \"off\", \"weight\": 80}], \"bucket_by\": \"user.id\"} (weights add up to 100).",
      "properties": {
        "variant": {
          "type": "string"
        },
        "rollout": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "variant": {
                "type": "string"
              },
              "weight": {
                "type": "number"
              }
            },
            "required": [
              "variant",
              "weight"
            ]
          }
        },
        "bucket_by": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "ref",
    "key",
    "environment",
    "conditions",
    "serve"
  ],
  "additionalProperties": false
}

`move_flag_rule` Reorder a flag rule

Destructive

Moves a rule one place up or down; a rule higher up matches first. Production takes owners and admins; any other environment, developers and above.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`environment`	`string`	Yes	The environment: production, preview, development, or one the project made (list_environments).
`rule_id`	`string`	Yes	A rules[].id under environments.<environment> from get_flag.
`direction`	`string`, up \| down	Yes	up or down.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "environment": {
      "type": "string",
      "description": "The environment: production, preview, development, or one the project made (list_environments)."
    },
    "rule_id": {
      "type": "string",
      "description": "A rules[].id under environments.<environment> from get_flag."
    },
    "direction": {
      "type": "string",
      "enum": [
        "up",
        "down"
      ],
      "description": "up or down."
    }
  },
  "required": [
    "ref",
    "key",
    "environment",
    "rule_id",
    "direction"
  ],
  "additionalProperties": false
}

`remove_flag_rule` Remove a flag rule

Destructive

Removes one rule from one environment. Production takes owners and admins; any other environment, developers and above.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`environment`	`string`	Yes	The environment: production, preview, development, or one the project made (list_environments).
`rule_id`	`string`	Yes	A rules[].id under environments.<environment> from get_flag.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "environment": {
      "type": "string",
      "description": "The environment: production, preview, development, or one the project made (list_environments)."
    },
    "rule_id": {
      "type": "string",
      "description": "A rules[].id under environments.<environment> from get_flag."
    }
  },
  "required": [
    "ref",
    "key",
    "environment",
    "rule_id"
  ],
  "additionalProperties": false
}

`set_flag_archived` Archive a feature flag

Destructive

Archives a flag that is done with (archived: true), or brings it back. An archived flag serves its off value in every environment. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The flag key.
`archived`	`boolean`	Yes	true archives, false restores.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The flag key."
    },
    "archived": {
      "type": "boolean",
      "description": "true archives, false restores."
    }
  },
  "required": [
    "ref",
    "key",
    "archived"
  ],
  "additionalProperties": false
}

`list_flag_segments` Flag segments

Read-only

Returns the groups of users (segments) flag rules share: their conditions, the ids always in them (included), the ids never in them (excluded) and the flags using them (used_by).

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_flag_segment` Create a flag segment

Only adds

Creates an empty segment. Fill in its conditions and lists with update_flag_segment, then name it in a rule with in_segment. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The segment key, by the same rule as a flag key.
`description`	`string`, max length 500	No	Up to 500 characters.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The segment key, by the same rule as a flag key."
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Up to 500 characters."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`update_flag_segment` Change a flag segment

Destructive

Changes a segment's conditions (1 to 3, all must hold), the ids always in it, the ids never in it (up to 1,000 each) and its description. Conditions and included cannot both be empty. A field left out keeps its value. Segments decide production rules too, so only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The key from list_flag_segments.
`conditions`	`array<object>`, min items 0, max items 3	No	1 to 3 conditions that must all hold. attribute is a dot path into the context (user.email); a value cannot contain a comma. For in_segment and not_in_segment, values are segment keys.
`included`	`array<string>`	No	Ids always in the segment.
`excluded`	`array<string>`	No	Ids never in the segment.
`description`	`string`, max length 500	No	Up to 500 characters.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The key from list_flag_segments."
    },
    "conditions": {
      "type": "array",
      "minItems": 0,
      "maxItems": 3,
      "description": "1 to 3 conditions that must all hold. attribute is a dot path into the context (user.email); a value cannot contain a comma. For in_segment and not_in_segment, values are segment keys.",
      "items": {
        "type": "object",
        "properties": {
          "attribute": {
            "type": "string"
          },
          "op": {
            "type": "string",
            "enum": [
              "is",
              "is_not",
              "contains",
              "not_contains",
              "starts_with",
              "ends_with",
              "domain_is",
              "gt",
              "lt",
              "exists",
              "not_exists",
              "in_segment",
              "not_in_segment"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "op"
        ]
      }
    },
    "included": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ids always in the segment."
    },
    "excluded": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ids never in the segment."
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Up to 500 characters."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`remove_flag_segment` Remove a flag segment

Destructive

Removes a segment. One a rule uses cannot be removed (used_by in list_flag_segments). Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`key`	`string`, max length 64	Yes	The key from list_flag_segments.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "key": {
      "type": "string",
      "maxLength": 64,
      "description": "The key from list_flag_segments."
    }
  },
  "required": [
    "ref",
    "key"
  ],
  "additionalProperties": false
}

`list_flag_sdk_keys` Flag SDK keys

Read-only

Returns the keys that call /flags/v1/evaluate: environment, kind (server or client), label, prefix and last use. A value is shown only when it is made. Developers and above can see this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_flag_sdk_key` Create a flag SDK key

Only adds

Creates a key that reads one environment's flags. Keep a server key on servers; a client key may go to browsers. The value is in this response only. Up to 50 per project. A production key takes owners and admins; any other environment, developers and above.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`environment`	`string`	Yes	The environment: production, preview, development, or one the project made (list_environments).
`kind`	`string`, server \| client	Yes	server or client.
`label`	`string`, max length 60	No	What the key is for, up to 60 characters.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "environment": {
      "type": "string",
      "description": "The environment: production, preview, development, or one the project made (list_environments)."
    },
    "kind": {
      "type": "string",
      "enum": [
        "server",
        "client"
      ],
      "description": "server or client."
    },
    "label": {
      "type": "string",
      "maxLength": 60,
      "description": "What the key is for, up to 60 characters."
    }
  },
  "required": [
    "ref",
    "environment",
    "kind"
  ],
  "additionalProperties": false
}

`revoke_flag_sdk_key` Revoke a flag SDK key

Destructive

Revokes an SDK key. Requests carrying it are refused at once. Production takes owners and admins; any other environment, developers and above.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_flag_sdk_keys.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_flag_sdk_keys."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_alert_rules` Alert rules

Read-only

Returns the alert rules and where each stands (state: ok or firing, last_value, last_fired_at). Alerts go to the organisation's notification channels and by mail.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_alert_rule` Create an alert rule

Only adds

Checks a value every minute and alerts when it passes threshold. kind: error_rate (5xx rate in %), p95 (p95 response time in ms), function_errors (function 5xx count), usage (plan limit used in %), firewall_blocks (requests the firewall denied or challenged). target: for error_rate and p95 a service (all, api, auth, functions, realtime, site, server), for function_errors a function name, for usage a limit, for firewall_blocks a firewall rule id. Empty means all. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 80	Yes	A name, 1 to 80 characters.
`kind`	`string`, error_rate \| p95 \| function_errors \| usage \| firewall_blocks	Yes	error_rate, p95, function_errors, usage or firewall_blocks.
`target`	`string`	No	A service (all, api, auth, functions, realtime, site, server), a function name, a limit or a rule id. Empty means all.
`threshold`	`number`, min 0	Yes	The alert fires above this value. Rates are 0 to 1000.
`window_minutes`	`integer`, min 1, max 1440	Yes	Minutes of values to look at.
`severity`	`string`, warning \| critical	No	warning (the default) or critical.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "A name, 1 to 80 characters."
    },
    "kind": {
      "type": "string",
      "enum": [
        "error_rate",
        "p95",
        "function_errors",
        "usage",
        "firewall_blocks"
      ],
      "description": "error_rate, p95, function_errors, usage or firewall_blocks."
    },
    "target": {
      "type": [
        "string",
        "null"
      ],
      "description": "A service (all, api, auth, functions, realtime, site, server), a function name, a limit or a rule id. Empty means all."
    },
    "threshold": {
      "type": "number",
      "minimum": 0,
      "description": "The alert fires above this value. Rates are 0 to 1000."
    },
    "window_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1440,
      "description": "Minutes of values to look at."
    },
    "severity": {
      "type": "string",
      "enum": [
        "warning",
        "critical"
      ],
      "description": "warning (the default) or critical."
    }
  },
  "required": [
    "ref",
    "name",
    "kind",
    "threshold",
    "window_minutes"
  ],
  "additionalProperties": false
}

`set_alert_rule_enabled` Turn an alert rule on or off

Destructive

Pauses an alert rule or turns it back on. Turning it off puts its state back to ok. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_alert_rules.
`enabled`	`boolean`	Yes	On or off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_alert_rules."
    },
    "enabled": {
      "type": "boolean",
      "description": "On or off."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_alert_rule` Remove an alert rule

Destructive

Removes an alert rule. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_alert_rules.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_alert_rules."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_project_webhooks` Project webhooks

Read-only

Returns the webhooks that send the project's events (a deployment starting, ready, failed or promoted, environment variables, domains, backups, sign-ups and so on), their signing secrets (signing_secret) and the events to choose from (events). Row changes in the database are list_db_webhooks. Developers and above can see this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_project_webhook` Create a project webhook

Only adds Reaches outside

Creates a webhook that sends the project's events to a public https address (outside automation such as Make, Zapier or Slack). Empty events is every event; <family>.* (for example deployment.*) is all of a family. The signing secret is signing_secret in the response. Up to 10 per project. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 60	Yes	A name, 1 to 60 characters.
`url`	`string`	Yes	A public https address. Private and internal addresses are refused.
`events`	`array<string>`	No	For example ["deployment.ready", "deployment.error"]. Families: deployment., project., env., domain., backup., auth..

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "A name, 1 to 60 characters."
    },
    "url": {
      "type": "string",
      "description": "A public https address. Private and internal addresses are refused."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "For example [\"deployment.ready\", \"deployment.error\"]. Families: deployment.*, project.*, env.*, domain.*, backup.*, auth.*."
    }
  },
  "required": [
    "ref",
    "name",
    "url"
  ],
  "additionalProperties": false
}

`set_project_webhook_enabled` Turn a project webhook on or off

Destructive

Pauses a webhook or lets it send again. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_project_webhooks.
`enabled`	`boolean`	Yes	On or off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_project_webhooks."
    },
    "enabled": {
      "type": "boolean",
      "description": "On or off."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`test_project_webhook` Test a project webhook

Only adds Reaches outside

Sends one signed ping event. The result shows in list_project_webhook_deliveries. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_project_webhooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_project_webhooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_project_webhook_deliveries` Project webhook deliveries

Read-only

The last 100 deliveries of a webhook: event, status (pending, sent or failed), attempts and why it failed. Developers and above can see this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_project_webhooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_project_webhooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`retry_project_webhook_delivery` Send a project webhook delivery again

Only adds Reaches outside

Sends a finished delivery again, as a new delivery. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`delivery_id`	`integer`, min 1	Yes	An id from list_project_webhook_deliveries.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "delivery_id": {
      "type": "integer",
      "minimum": 1,
      "description": "An id from list_project_webhook_deliveries."
    }
  },
  "required": [
    "ref",
    "delivery_id"
  ],
  "additionalProperties": false
}

`remove_project_webhook` Remove a project webhook

Destructive

Removes a webhook. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_project_webhooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_project_webhooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_firewall` Firewall rules

Read-only

Returns the firewall draft (draft: rules and managed rules), the published version (published_version, published), what the draft changes (changes), attack challenge mode and the version history. Rules are looked at from the top; the first one whose action ends the request (deny, challenge, redirect, bypass, an exceeded rate_limit) is the last. IP deny and allow lists are get_edge.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`save_firewall_rule` Save a firewall rule

Destructive

Saves one rule into the draft. Without id it is added at the end; with id that rule is replaced. A rule the gateway cannot compile (a slow regular expression, a bad CIDR and so on) is refused in the console's words. It applies once published with publish_firewall. Up to 100 per project. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	No	The id of the rule to change (draft.rules[].id from get_firewall). Leave it out for a new rule.
`name`	`string`, min length 1, max length 80	Yes	The rule's name, up to 80 characters.
`enabled`	`boolean`	No	true by default. false saves it without applying it.
`groups`	`array<array>`, min items 1, max items 10	Yes	1 to 10 groups of conditions. Groups are OR'd; the conditions in one (up to 10) are AND'd. A condition is {field, op, value, key?, negate?}: field is path, method, host, header, query, user_agent, ip, country, op is eq, prefix, suffix, contains, regex, in, exists. path, host and user_agent take eq, prefix, suffix, contains or regex; method, ip and country take in (several values, comma separated); header and query name the header or parameter in key and also take exists. For example [[{"field": "path", "op": "prefix", "value": "/admin"}, {"field": "ip", "op": "in", "value": "203.0.113.0/24", "negate": true}]]
`action`	`object`	Yes	What a match does. type: log (write a line and go on), deny (403), challenge (a browser check), bypass (skip the remaining rules, the managed rules and attack mode), redirect (location, status 301, 302, 307 or 308), rate_limit (limit 1 to 100000, window_seconds 1 to 3600, key ip or header with the header's name, then deny, challenge or log). For example {"type": "rate_limit", "limit": 100, "window_seconds": 60, "key": "ip", "then": "deny"}

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "The id of the rule to change (draft.rules[].id from get_firewall). Leave it out for a new rule."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "The rule's name, up to 80 characters."
    },
    "enabled": {
      "type": "boolean",
      "description": "true by default. false saves it without applying it."
    },
    "groups": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "description": "1 to 10 groups of conditions. Groups are OR'd; the conditions in one (up to 10) are AND'd. A condition is {field, op, value, key?, negate?}: field is path, method, host, header, query, user_agent, ip, country, op is eq, prefix, suffix, contains, regex, in, exists. path, host and user_agent take eq, prefix, suffix, contains or regex; method, ip and country take in (several values, comma separated); header and query name the header or parameter in key and also take exists. For example [[{\"field\": \"path\", \"op\": \"prefix\", \"value\": \"/admin\"}, {\"field\": \"ip\", \"op\": \"in\", \"value\": \"203.0.113.0/24\", \"negate\": true}]]",
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "field": {
              "type": "string",
              "enum": [
                "path",
                "method",
                "host",
                "header",
                "query",
                "user_agent",
                "ip",
                "country"
              ]
            },
            "op": {
              "type": "string",
              "enum": [
                "eq",
                "prefix",
                "suffix",
                "contains",
                "regex",
                "in",
                "exists"
              ]
            },
            "value": {
              "type": "string"
            },
            "key": {
              "type": "string"
            },
            "negate": {
              "type": "boolean"
            }
          },
          "required": [
            "field",
            "op"
          ]
        }
      }
    },
    "action": {
      "type": "object",
      "description": "What a match does. type: log (write a line and go on), deny (403), challenge (a browser check), bypass (skip the remaining rules, the managed rules and attack mode), redirect (location, status 301, 302, 307 or 308), rate_limit (limit 1 to 100000, window_seconds 1 to 3600, key ip or header with the header's name, then deny, challenge or log). For example {\"type\": \"rate_limit\", \"limit\": 100, \"window_seconds\": 60, \"key\": \"ip\", \"then\": \"deny\"}",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "log",
            "deny",
            "challenge",
            "bypass",
            "redirect",
            "rate_limit"
          ]
        },
        "location": {
          "type": "string"
        },
        "status": {
          "type": "integer",
          "enum": [
            301,
            302,
            307,
            308
          ]
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100000
        },
        "window_seconds": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3600
        },
        "key": {
          "type": "string",
          "enum": [
            "ip",
            "header"
          ]
        },
        "header": {
          "type": "string"
        },
        "then": {
          "type": "string",
          "enum": [
            "deny",
            "challenge",
            "log"
          ]
        }
      },
      "required": [
        "type"
      ]
    }
  },
  "required": [
    "ref",
    "name",
    "groups",
    "action"
  ],
  "additionalProperties": false
}

`move_firewall_rule` Move a firewall rule

Destructive

Moves a rule one place up or down in the draft. Rules are looked at from the top. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	A draft.rules[].id from get_firewall.
`direction`	`string`, up \| down	Yes	up moves it one place up, down one place down.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "A draft.rules[].id from get_firewall."
    },
    "direction": {
      "type": "string",
      "enum": [
        "up",
        "down"
      ],
      "description": "up moves it one place up, down one place down."
    }
  },
  "required": [
    "ref",
    "id",
    "direction"
  ],
  "additionalProperties": false
}

`set_firewall_rule_enabled` Turn a firewall rule on or off

Destructive

Turns a rule on or off in the draft. It applies once published. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	A draft.rules[].id from get_firewall.
`enabled`	`boolean`	Yes	true turns it on, false off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "A draft.rules[].id from get_firewall."
    },
    "enabled": {
      "type": "boolean",
      "description": "true turns it on, false off."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`remove_firewall_rule` Remove a firewall rule

Destructive

Removes a rule from the draft. Until published, reset_firewall_draft brings it back. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	A draft.rules[].id from get_firewall.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "A draft.rules[].id from get_firewall."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`set_firewall_managed` Bots and managed rules

Destructive

Sets the mode (off, log, deny) of the managed rules, which block without a rule, in the draft. bots are SEO crawlers, scrapers and attack tools, ai_bots AI training crawlers such as GPTBot and ClaudeBot, ai_search_bots AI search and answer bots such as ChatGPT search and Perplexity (denying them takes the site out of AI answers), rulesets the attack patterns (sensitive_files, wordpress, traversal, sqli, xss, shell). What is left out stays as it is; it applies once published. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bots`	`string`, off \| log \| deny	No	Known bots: off, log (log only) or deny.
`ai_bots`	`string`, off \| log \| deny	No	AI training crawlers: off, log (log only) or deny.
`ai_search_bots`	`string`, off \| log \| deny	No	AI search and answer bots; deny takes the site out of ChatGPT search and Perplexity answers: off, log (log only) or deny.
`rulesets`	`object`	No	The mode for each attack pattern. For example {"sqli": "deny", "wordpress": "log"}. Names: sensitive_files, wordpress, traversal, sqli, xss, shell.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bots": {
      "type": "string",
      "enum": [
        "off",
        "log",
        "deny"
      ],
      "description": "Known bots: off, log (log only) or deny."
    },
    "ai_bots": {
      "type": "string",
      "enum": [
        "off",
        "log",
        "deny"
      ],
      "description": "AI training crawlers: off, log (log only) or deny."
    },
    "ai_search_bots": {
      "type": "string",
      "enum": [
        "off",
        "log",
        "deny"
      ],
      "description": "AI search and answer bots; deny takes the site out of ChatGPT search and Perplexity answers: off, log (log only) or deny."
    },
    "rulesets": {
      "type": "object",
      "properties": {
        "sensitive_files": {
          "type": "string",
          "enum": [
            "off",
            "log",
            "deny"
          ]
        },
        "wordpress": {
          "type": "string",
          "enum": [
            "off",
            "log",
            "deny"
          ]
        },
        "traversal": {
          "type": "string",
          "enum": [
            "off",
            "log",
            "deny"
          ]
        },
        "sqli": {
          "type": "string",
          "enum": [
            "off",
            "log",
            "deny"
          ]
        },
        "xss": {
          "type": "string",
          "enum": [
            "off",
            "log",
            "deny"
          ]
        },
        "shell": {
          "type": "string",
          "enum": [
            "off",
            "log",
            "deny"
          ]
        }
      },
      "additionalProperties": false,
      "description": "The mode for each attack pattern. For example {\"sqli\": \"deny\", \"wordpress\": \"log\"}. Names: sensitive_files, wordpress, traversal, sqli, xss, shell."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`publish_firewall` Publish the firewall

Destructive

Publishes the draft as a new version. Within seconds every server blocks or lets requests through by these rules. Check what changes first with changes from get_firewall. A wrong publish is undone by loading an earlier version with restore_firewall_version and publishing again. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`note`	`string`, max length 200	No	What changed and why. Kept in the version history.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "note": {
      "type": "string",
      "maxLength": 200,
      "description": "What changed and why. Kept in the version history."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`reset_firewall_draft` Discard the firewall draft

Destructive

Throws away every unpublished change in the draft, back to the rules in force. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`restore_firewall_version` Load an earlier firewall version

Destructive

Loads a published version into the draft. The current draft is overwritten, and it applies once published with publish_firewall. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`version`	`integer`, min 1	Yes	A versions[].version from get_firewall.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "version": {
      "type": "integer",
      "minimum": 1,
      "description": "A versions[].version from get_firewall."
    }
  },
  "required": [
    "ref",
    "version"
  ],
  "additionalProperties": false
}

`set_attack_mode` Attack challenge mode

Destructive

Turned on, every visitor gets a browser check at once (no publish needed). For a DDoS or heavy scraping. Programs that call the API are stopped too, so turn it off when the attack is over. With hours it turns itself off after that long (up to 720 hours). Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true turns it on, false off.
`hours`	`string`, min 0, max 720	No	How long to keep it on. Left out or null: until turned off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true turns it on, false off."
    },
    "hours": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 720,
      "description": "How long to keep it on. Left out or null: until turned off."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

`get_bulk_redirects` Bulk redirects

Read-only

Returns the bulk redirect versions uploaded (sets, the one applied is active) and the first 100 rows of the one chosen (left out: the one applied). One or two rules are get_routing_rules.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`set_id`	`string`	No	A sets[].id from get_bulk_redirects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "set_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "A sets[].id from get_bulk_redirects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`upload_bulk_redirects` Upload bulk redirects

Destructive

Uploads redirects as a CSV, as a new version (up to 10,000 rows, 5 MB). One row is source,destination[,status (308 by default)[,preserve query true|false]]. The source is a /path or domain/path, the destination a /path or an http(s) address. activate set to true applies it at once; otherwise activate_bulk_redirects applies it. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`csv`	`string`	Yes	The CSV. For example "/old,/new,301\n/blog/a,https://blog.example.com/a"
`note`	`string`, max length 200	No	A note for the version.
`activate`	`boolean`	No	true applies it as soon as it is uploaded. false by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "csv": {
      "type": "string",
      "description": "The CSV. For example \"/old,/new,301\\n/blog/a,https://blog.example.com/a\""
    },
    "note": {
      "type": "string",
      "maxLength": 200,
      "description": "A note for the version."
    },
    "activate": {
      "type": "boolean",
      "description": "true applies it as soon as it is uploaded. false by default."
    }
  },
  "required": [
    "ref",
    "csv"
  ],
  "additionalProperties": false
}

`activate_bulk_redirects` Apply bulk redirects

Destructive

Applies one uploaded version (set_id), or turns bulk redirects off with null. Every server has it within a minute. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`set_id`	`string`	Yes	A sets[].id from get_bulk_redirects. null turns them off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "set_id": {
      "type": [
        "integer",
        "null"
      ],
      "description": "A sets[].id from get_bulk_redirects. null turns them off."
    }
  },
  "required": [
    "ref",
    "set_id"
  ],
  "additionalProperties": false
}

`get_skew_protection` Skew protection

Read-only

Returns whether skew protection is on (a tab already open keeps getting the scripts and data of the deployment it started on after a new one goes out) and its maximum age in seconds.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_skew_protection` Change skew protection

Destructive

Turns skew protection on or off and sets its maximum age. A deployment older than that is not pinned. What is left out stays as it is. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	true turns it on, false off.
`max_age_seconds`	`integer`, 300 \| 1800 \| 3600 \| 21600 \| 43200 \| 86400 \| 259200 \| 604800	No	The maximum age in seconds: 300, 1800, 3600, 21600, 43200, 86400, 259200, 604800.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true turns it on, false off."
    },
    "max_age_seconds": {
      "type": "integer",
      "enum": [
        300,
        1800,
        3600,
        21600,
        43200,
        86400,
        259200,
        604800
      ],
      "description": "The maximum age in seconds: 300, 1800, 3600, 21600, 43200, 86400, 259200, 604800."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_remote_cache_tokens` Remote cache tokens

Read-only

Returns the Turborepo remote cache tokens (name, when made, last used) and the api and team to give turbo. A token's value is shown once, when it is made.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_remote_cache_token` Create a remote cache token

Only adds

Creates a token turbo in CI or a terminal uses to reach this project's remote cache. The value and the environment variables to set (env) are shown in this answer only. Up to 20. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 80	Yes	What the token is for. For example github-actions.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "What the token is for. For example github-actions."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`revoke_remote_cache_token` Revoke a remote cache token

Destructive

Removes a token. turbo using it loses the cache at once. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_remote_cache_tokens.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_remote_cache_tokens."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_build_settings` More build settings

Read-only

Returns, for each app, the build settings update_app does not set: the development command (dev_command), the Node.js version, the ignored build step (ignored_build_step), the build machine, production first (production_first), required checks (required_checks), Git LFS and verified commits only (verified_commits). Whether system environment variables are set (expose_system_env) comes too.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_build_dev_settings` Development command and Node.js version

Destructive

Sets an app's development command (what oneend dev runs) and the Node.js major version its builds use. The framework and the build, install and output settings are update_app. What is left out stays as it is; null is detected again. It applies from the next build. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`dev_command`	`string`, max length 1024	No	A one line command, for example npm run dev. null: the preset's default.
`node_version`	`string`, 18 \| 20 \| 22 \| 24 \| null	No	The Node.js major version: 18, 20, 22, 24. null: engines in package.json, or the default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "dev_command": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 1024,
      "description": "A one line command, for example npm run dev. null: the preset's default."
    },
    "node_version": {
      "type": [
        "integer",
        "null"
      ],
      "enum": [
        18,
        20,
        22,
        24,
        null
      ],
      "description": "The Node.js major version: 18, 20, 22, 24. null: engines in package.json, or the default."
    }
  },
  "required": [
    "ref",
    "app"
  ],
  "additionalProperties": false
}

`set_ignored_build_step` Ignored build step

Destructive

Sets which pushes are built. mode: automatic (the default; in a monorepo, a push that changes only another app's folder is skipped), every (every push), production (production only), preview (previews only), folder (only when a file under folder changed), command (skipped when command exits 0). A skipped push is still in the deployment history. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`mode`	`string`, automatic \| every \| production \| preview \| folder \| command	Yes	How pushes are skipped.
`folder`	`string`	No	For mode folder: the folder to look at, relative to the repository (for example apps/web).
`command`	`string`, max length 1024	No	For mode command: a one line command run in the build sandbox. Exit 0 skips the build.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "mode": {
      "type": "string",
      "enum": [
        "automatic",
        "every",
        "production",
        "preview",
        "folder",
        "command"
      ],
      "description": "How pushes are skipped."
    },
    "folder": {
      "type": "string",
      "description": "For mode folder: the folder to look at, relative to the repository (for example apps/web)."
    },
    "command": {
      "type": "string",
      "maxLength": 1024,
      "description": "For mode command: a one line command run in the build sandbox. Exit 0 skips the build."
    }
  },
  "required": [
    "ref",
    "app",
    "mode"
  ],
  "additionalProperties": false
}

`set_production_first` Production builds first

Destructive

Sets whether production builds run ahead of previews in the queue. The build machine's size is build_machine in update_app. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`enabled`	`boolean`	Yes	true runs production first (the default), false in the order they came.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "enabled": {
      "type": "boolean",
      "description": "true runs production first (the default), false in the order they came."
    }
  },
  "required": [
    "ref",
    "app",
    "enabled"
  ],
  "additionalProperties": false
}

`set_git_checks` Required checks and Git LFS

Destructive

Sets the GitHub checks that must pass before a build goes to production (required_checks, up to 20), whether Git LFS files are fetched, and whether only signed commits are built. Required checks and verified commits are for GitHub repositories only. What is left out stays as it is. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`app`	`string`	Yes	The name from list_apps.
`required_checks`	`array<string>`, max items 20	No	GitHub check names, for example ["test", "lint"]. [] removes them all.
`git_lfs`	`boolean`	No	true fetches Git LFS files when building.
`verified_commits`	`boolean`	No	true builds only commits GitHub verified as signed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "app": {
      "type": "string",
      "description": "The name from list_apps."
    },
    "required_checks": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "maxItems": 20,
      "description": "GitHub check names, for example [\"test\", \"lint\"]. [] removes them all."
    },
    "git_lfs": {
      "type": "boolean",
      "description": "true fetches Git LFS files when building."
    },
    "verified_commits": {
      "type": "boolean",
      "description": "true builds only commits GitHub verified as signed."
    }
  },
  "required": [
    "ref",
    "app"
  ],
  "additionalProperties": false
}

`set_expose_system_env` System environment variables

Destructive

Sets whether builds and servers get system environment variables such as BLACKWALL_ENV, BLACKWALL_URL and BLACKWALL_GIT_COMMIT_SHA. The current value is expose_system_env in list_environments. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true sets them, false leaves them out.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true sets them, false leaves them out."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

`set_directory_listing` Folder listings

Destructive

Sets whether a static site shows the files of a folder with no index.html (true) or answers 404 (false). Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true shows the listing.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true shows the listing."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

`get_deployment_security` Deployment security

Read-only

Returns who sees build logs and deployment output (members, writers, admins), whether pull requests from forks wait for approval before building (fork_protection), and whether OIDC tokens are given and how they are issued.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_deployment_security` Change deployment security

Destructive

Sets who can see build logs (logs_access) and deployment output (source_access), fork protection, and OIDC (a token clouds trust given to builds and servers; oidc_issuer_mode team or global). What is left out stays as it is. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`logs_access`	`string`, members \| writers \| admins	No	Who can see build logs: members (every member), writers (developers and above) or admins (owners and admins).
`source_access`	`string`, members \| writers \| admins	No	Who can see the files a deployment put out: members (every member), writers (developers and above) or admins (owners and admins).
`fork_protection`	`boolean`	No	true holds pull requests from forks until approved, so environment variables do not leak.
`oidc_enabled`	`boolean`	No	true gives builds and servers an OIDC token.
`oidc_issuer_mode`	`string`, team \| global	No	The issuer: team is the organisation's own, global the platform's shared one.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "logs_access": {
      "type": "string",
      "enum": [
        "members",
        "writers",
        "admins"
      ],
      "description": "Who can see build logs: members (every member), writers (developers and above) or admins (owners and admins)."
    },
    "source_access": {
      "type": "string",
      "enum": [
        "members",
        "writers",
        "admins"
      ],
      "description": "Who can see the files a deployment put out: members (every member), writers (developers and above) or admins (owners and admins)."
    },
    "fork_protection": {
      "type": "boolean",
      "description": "true holds pull requests from forks until approved, so environment variables do not leak."
    },
    "oidc_enabled": {
      "type": "boolean",
      "description": "true gives builds and servers an OIDC token."
    },
    "oidc_issuer_mode": {
      "type": "string",
      "enum": [
        "team",
        "global"
      ],
      "description": "The issuer: team is the organisation's own, global the platform's shared one."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_routing_rules` Routing rules

Read-only

Returns the versions (the last 30) of the redirect, rewrite and header rules set in the console, the active one (active, null for none) and domain redirects. These rules apply ahead of each deployment's blackwall.json.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`save_routing_rules` Save routing rules

Destructive

Saves rules shaped like blackwall.json as a new version and applies it at once, checked by the same rules a build checks blackwall.json with. Send all the rules (a list left out is empty). activate_routing_rules goes back to an earlier version. Hundreds of redirects are upload_bulk_redirects. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`redirects`	`array<object>`	No	For example [{"source": "/old/:path", "destination": "/new/:path", "statusCode": 308}]. statusCode 301, 302, 307 or 308; without it, permanent (true 308, otherwise 307).
`rewrites`	`array<object>`	No	For example [{"source": "/docs/:path", "destination": "/help/:path"}]
`headers`	`array<object>`	No	For example [{"source": "/:path*", "headers": [{"key": "X-Frame-Options", "value": "DENY"}]}]
`note`	`string`, max length 200	No	A note for the version.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "redirects": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "For example [{\"source\": \"/old/:path*\", \"destination\": \"/new/:path*\", \"statusCode\": 308}]. statusCode 301, 302, 307 or 308; without it, permanent (true 308, otherwise 307)."
    },
    "rewrites": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "For example [{\"source\": \"/docs/:path*\", \"destination\": \"/help/:path*\"}]"
    },
    "headers": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "For example [{\"source\": \"/:path*\", \"headers\": [{\"key\": \"X-Frame-Options\", \"value\": \"DENY\"}]}]"
    },
    "note": {
      "type": "string",
      "maxLength": 200,
      "description": "A note for the version."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`activate_routing_rules` Apply a routing rules version

Destructive

Applies a saved version again, or turns the console's rules off with null (only each deployment's blackwall.json then). Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`version`	`string`, min 1	Yes	A versions[].version from get_routing_rules. null turns them off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "version": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "A versions[].version from get_routing_rules. null turns them off."
    }
  },
  "required": [
    "ref",
    "version"
  ],
  "additionalProperties": false
}

`purge_edge_cache_item` Purge part of the cache

Destructive

Throws away one path (a trailing * takes everything under it) or one Cache-Tag from the edge cache. Give one of the two. The whole cache is purge_edge_cache. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`path`	`string`, max length 512	No	A path starting with /, for example /blog/* or /index.html.
`tag`	`string`, max length 512	No	One tag set in a response's Cache-Tag header.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "path": {
      "type": "string",
      "maxLength": 512,
      "description": "A path starting with /, for example /blog/* or /index.html."
    },
    "tag": {
      "type": "string",
      "maxLength": 512,
      "description": "One tag set in a response's Cache-Tag header."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_job_retention` Job run history kept

Destructive

Sets how many days scheduled jobs' runs are kept: 1, 3, 7, 14, 30, 90 days, or null for the plan's default. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`string`, 1 \| 3 \| 7 \| 14 \| 30 \| 90 \| null	Yes	Days to keep. null: the default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": [
        "integer",
        "null"
      ],
      "enum": [
        1,
        3,
        7,
        14,
        30,
        90,
        null
      ],
      "description": "Days to keep. null: the default."
    }
  },
  "required": [
    "ref",
    "days"
  ],
  "additionalProperties": false
}

`get_storage_settings` Storage settings

Read-only

Returns the largest single file for the whole project (file_size_limit; null is the server's limit, host_max_bytes), whether image transformation is on and the sizes it allows, whether the S3 endpoint is on, and for each bucket whether it keeps earlier versions (versioning).

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_storage_settings` Change storage settings

Destructive

Sets the largest single file for the whole project and image transformation (on, and the widths allowed). One bucket's limit is update_bucket. What is left out stays as it is. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`file_size_limit`	`string`	No	A number of bytes or a size such as 5MB. null: up to the server's limit.
`image_transform`	`boolean`	No	true transforms images on request, such as ?width=.
`image_sizes`	`array<integer>`, max items 20	No	The widths in px transformation is allowed for. [] allows any.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "file_size_limit": {
      "type": [
        "string",
        "integer",
        "null"
      ],
      "description": "A number of bytes or a size such as 5MB. null: up to the server's limit."
    },
    "image_transform": {
      "type": "boolean",
      "description": "true transforms images on request, such as ?width=."
    },
    "image_sizes": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 2500
      },
      "maxItems": 20,
      "description": "The widths in px transformation is allowed for. [] allows any."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_s3_enabled` Turn the S3 endpoint on or off

Destructive

Sets whether the S3 compatible endpoint takes requests. Off, every request made with an S3 key (list_s3_keys) is refused, and the keys are kept. Developers and above, who may read the secret key, can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	Yes	true turns it on, false off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "true turns it on, false off."
    }
  },
  "required": [
    "ref",
    "enabled"
  ],
  "additionalProperties": false
}

`set_bucket_versioning` Bucket versioning

Destructive

Sets whether a bucket keeps files that were overwritten or deleted as earlier versions, and for how many days. What is left out stays as it is. Earlier versions count toward storage. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	A bucket name from list_buckets.
`enabled`	`boolean`	No	true keeps earlier versions.
`noncurrent_days`	`string`, min 1, max 3650	No	Days to keep an earlier version. null: until removed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "A bucket name from list_buckets."
    },
    "enabled": {
      "type": "boolean",
      "description": "true keeps earlier versions."
    },
    "noncurrent_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 3650,
      "description": "Days to keep an earlier version. null: until removed."
    }
  },
  "required": [
    "ref",
    "bucket"
  ],
  "additionalProperties": false
}

`list_object_versions` Earlier versions of files

Read-only

Returns up to 200 earlier versions in a bucket, newest first. With name, only that file's. deleted true is the last version of a deleted file.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	A bucket name from list_buckets.
`name`	`string`, max length 1024	No	A file path in the bucket, for example avatars/a.png.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "A bucket name from list_buckets."
    },
    "name": {
      "type": "string",
      "maxLength": 1024,
      "description": "A file path in the bucket, for example avatars/a.png."
    }
  },
  "required": [
    "ref",
    "bucket"
  ],
  "additionalProperties": false
}

`restore_object_version` Restore an earlier version of a file

Destructive

Makes an earlier version the current file of its name again. The file that held the name becomes an earlier version, as the bucket keeps them. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_object_versions.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_object_versions."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`remove_object_version` Remove an earlier version for good

Destructive

Removes one earlier version for good. The current file stays. It cannot be undone, so confirm must be the file's name exactly. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_object_versions.
`confirm`	`string`	Yes	The file name of the version (name from list_object_versions).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_object_versions."
    },
    "confirm": {
      "type": "string",
      "description": "The file name of the version (name from list_object_versions)."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`list_bucket_connections` Buckets connected to deployments

Read-only

Returns each bucket connected to deployments: its prefix, the environments it goes to, the S3 key it uses and the environment variables it sets. targets are the environments to choose from.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`connect_bucket` Connect a bucket to deployments

Destructive

Makes an S3 key that opens this one bucket and puts it into the chosen environments' deployments as <prefix>_BUCKET, _ENDPOINT, _REGION, _ACCESS_KEY_ID and _SECRET_ACCESS_KEY. The S3 endpoint is turned on too. It is there from the next deployment. Developers and above can do this. Production takes owners and admins.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`bucket`	`string`	Yes	A bucket name from list_buckets.
`prefix`	`string`, pattern ^[A-Za-z][A-Za-z0-9_]{0,30}$	No	The environment variables' prefix, made upper case. BLOB by default; it cannot start with BLACKWALL.
`targets`	`array<string>`, min items 1	Yes	The environments: production, preview, development, env:<environment name>. targets from list_bucket_connections.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "bucket": {
      "type": "string",
      "description": "A bucket name from list_buckets."
    },
    "prefix": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,30}$",
      "description": "The environment variables' prefix, made upper case. BLOB by default; it cannot start with BLACKWALL."
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "description": "The environments: production, preview, development, env:<environment name>. targets from list_bucket_connections."
    }
  },
  "required": [
    "ref",
    "bucket",
    "targets"
  ],
  "additionalProperties": false
}

`disconnect_bucket` Disconnect a bucket

Destructive

Revokes the connection's S3 key at once and takes the variables out of the next deployment. Code using them fails, so confirm must be the prefix exactly. One connected to production takes owners and admins.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_bucket_connections.
`confirm`	`string`	Yes	The connection's prefix.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_bucket_connections."
    },
    "confirm": {
      "type": "string",
      "description": "The connection's prefix."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`list_storage_policies` File access rules

Read-only

The access rules of the file table (objects) and the bucket table (buckets): command, roles, conditions, and whether it is one of the platform's own (built_in). Rules on data tables are list_policies.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_storage_policy` Create a file access rule

Only adds

Makes a file access rule from the console's templates. template: public-read (anyone reads), signed-in-read (only signed in users read), signed-in-upload (signed in users upload), own-folder (a folder per person), images-only (only images uploaded), custom (command, roles, using and check written out). A template needs bucket. auth.uid() is written uid(). run_sql cannot make rules on the file table. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`template`	`string`, public-read \| signed-in-read \| signed-in-upload \| own-folder \| images-only \| custom	No	The template. custom by default.
`bucket`	`string`	No	The bucket the template applies to (needed for all but custom).
`name`	`string`, max length 63	No	The rule's name. Empty: the template's.
`table`	`string`, objects \| buckets	No	For custom: the table. objects by default; buckets takes select only.
`command`	`string`, select \| insert \| update \| delete \| all	No	For custom: the command.
`roles`	`array<string>`, anon \| authenticated	No	For custom: who it applies to.
`restrictive`	`boolean`	No	true makes it restrictive (AND with the other rules).
`using`	`string`	No	For custom: the using condition. For example bucket_id = 'avatars' and owner = uid()
`check`	`string`	No	For custom: the with check condition.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "template": {
      "type": "string",
      "enum": [
        "public-read",
        "signed-in-read",
        "signed-in-upload",
        "own-folder",
        "images-only",
        "custom"
      ],
      "description": "The template. custom by default."
    },
    "bucket": {
      "type": "string",
      "description": "The bucket the template applies to (needed for all but custom)."
    },
    "name": {
      "type": "string",
      "maxLength": 63,
      "description": "The rule's name. Empty: the template's."
    },
    "table": {
      "type": "string",
      "enum": [
        "objects",
        "buckets"
      ],
      "description": "For custom: the table. objects by default; buckets takes select only."
    },
    "command": {
      "type": "string",
      "enum": [
        "select",
        "insert",
        "update",
        "delete",
        "all"
      ],
      "description": "For custom: the command."
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "anon",
          "authenticated"
        ]
      },
      "description": "For custom: who it applies to."
    },
    "restrictive": {
      "type": "boolean",
      "description": "true makes it restrictive (AND with the other rules)."
    },
    "using": {
      "type": "string",
      "description": "For custom: the using condition. For example bucket_id = 'avatars' and owner = uid()"
    },
    "check": {
      "type": "string",
      "description": "For custom: the with check condition."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`remove_storage_policy` Remove a file access rule

Destructive

Removes a file access rule the project made. The platform's own (built_in) cannot be removed. confirm must be the rule's name exactly. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`table`	`string`, objects \| buckets	No	The table the rule is on. objects by default.
`name`	`string`	Yes	A name from list_storage_policies.
`confirm`	`string`	Yes	The rule's name, the same as name.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "table": {
      "type": "string",
      "enum": [
        "objects",
        "buckets"
      ],
      "description": "The table the rule is on. objects by default."
    },
    "name": {
      "type": "string",
      "description": "A name from list_storage_policies."
    },
    "confirm": {
      "type": "string",
      "description": "The rule's name, the same as name."
    }
  },
  "required": [
    "ref",
    "name",
    "confirm"
  ],
  "additionalProperties": false
}

`get_realtime_settings` Realtime settings

Read-only

Returns whether realtime is on, whether public channels are allowed, the limits on connections, messages per second, presence updates per second and message size, and the range of each (bounds).

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_realtime_settings` Change realtime settings

Destructive

Turns realtime on or off, allows public channels and changes the limits for the whole project. Only what is given changes; the rest stays as it is. With allow_public off, only private channels (people the realtime_messages table's rules let in) can be used. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	Off takes no new connections.
`allow_public`	`boolean`	No	Whether public channels are allowed.
`max_clients`	`integer`, min 1, max 10000	No	Concurrent connections, 1 to 10000.
`max_events_per_second`	`integer`, min 1, max 10000	No	Broadcasts per second, 1 to 10000.
`max_presence_per_second`	`integer`, min 1, max 1000	No	Presence updates per second, 1 to 1000.
`max_payload_kb`	`integer`, min 1, max 3072	No	Largest message in KB, 1 to 3072.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "Off takes no new connections."
    },
    "allow_public": {
      "type": "boolean",
      "description": "Whether public channels are allowed."
    },
    "max_clients": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Concurrent connections, 1 to 10000."
    },
    "max_events_per_second": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Broadcasts per second, 1 to 10000."
    },
    "max_presence_per_second": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000,
      "description": "Presence updates per second, 1 to 1000."
    },
    "max_payload_kb": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3072,
      "description": "Largest message in KB, 1 to 3072."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_realtime_policies` Private channel rules

Read-only

Returns the rules on the realtime_messages table, which decide who may join and send in private channels, and the rule templates to choose from (templates).

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_realtime_messages_table` Create the private channel rules table

Only adds

Creates the realtime_messages table that private channels' rules are written on, with row level security on. Left as it is when it exists. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`add_realtime_policy` Add a private channel rule

Only adds

Adds a common rule to the realtime_messages table (making the table first when there is none). template: signed-in-read (signed-in people join private channels), signed-in-write (signed-in people send), own-channel (only the user:<their id> channel). Write other rules with run_sql. Developers and above can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`template`	`string`, signed-in-read \| signed-in-write \| own-channel	Yes	signed-in-read, signed-in-write or own-channel.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "template": {
      "type": "string",
      "enum": [
        "signed-in-read",
        "signed-in-write",
        "own-channel"
      ],
      "description": "signed-in-read, signed-in-write or own-channel."
    }
  },
  "required": [
    "ref",
    "template"
  ],
  "additionalProperties": false
}

`get_passkey_settings` Passkey settings

Read-only

Returns whether users can sign in with a passkey, the RP name, RP ID, allowed origins and whether user verification is required. An empty RP ID uses the Site URL's host.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_passkey_settings` Change passkey settings

Destructive

Turns passkey sign-in on or off for users and changes the RP name, RP ID and allowed origins. Only what is given changes. Every origin must be an https address under the RP ID (or the Site URL's host when there is none). Changing the RP ID makes passkeys already registered unusable. Owners, admins and developers can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`enabled`	`boolean`	No	Whether passkey sign-in is on.
`rp_name`	`string`	No	The service name the browser shows.
`rp_id`	`string`	No	The domain passkeys are bound to (for example example.com). Empty uses the Site URL's host.
`origins`	`array<string>`	No	The https origins that use passkeys (for example ["https://app.example.com"]). Empty uses the Site URL.
`require_user_verification`	`boolean`	No	Whether a fingerprint, PIN or the like is always required.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether passkey sign-in is on."
    },
    "rp_name": {
      "type": "string",
      "description": "The service name the browser shows."
    },
    "rp_id": {
      "type": "string",
      "description": "The domain passkeys are bound to (for example example.com). Empty uses the Site URL's host."
    },
    "origins": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The https origins that use passkeys (for example [\"https://app.example.com\"]). Empty uses the Site URL."
    },
    "require_user_verification": {
      "type": "boolean",
      "description": "Whether a fingerprint, PIN or the like is always required."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`list_user_factors` A user's second factors and passkeys

Read-only

Returns the second factors (factors: totp, phone) and passkeys (passkeys) one user has registered.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_users (a UUID).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_users (a UUID)."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`remove_user_factors` Remove a user's second factors

Destructive

Removes all of one user's second factors, for someone who lost their phone. They sign in with a password alone until they enrol again. Put that user's email (or id) in confirm. Use only when asked. Owners, admins and developers can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_users (a UUID).
`confirm`	`string`	Yes	The user's email (or id), exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_users (a UUID)."
    },
    "confirm": {
      "type": "string",
      "description": "The user's email (or id), exactly."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`remove_user_passkey` Remove a user's passkey

Destructive

Removes one passkey of one user. It can no longer sign in. Owners, admins and developers can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`id`	`string`	Yes	An id from list_users (a UUID).
`passkey_id`	`string`	Yes	A passkeys[].id from list_user_factors.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "id": {
      "type": "string",
      "description": "An id from list_users (a UUID)."
    },
    "passkey_id": {
      "type": "string",
      "description": "A passkeys[].id from list_user_factors."
    }
  },
  "required": [
    "ref",
    "id",
    "passkey_id"
  ],
  "additionalProperties": false
}

`list_oauth_apps` OAuth apps

Read-only

Returns the other apps (clients) that use this project as their OAuth server to "sign in with" it, whether the OAuth server is on, and the authorization, token and userinfo addresses (endpoints). Secrets are not returned. OAUTH_SERVER_ENABLED in update_auth_config turns it on and off.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_oauth_app` Create an OAuth app

Only adds

Registers an app (client) that signs in with this project. With public false (the default) client_secret is in the response this once. With public true it is a mobile or single page app that signs in with PKCE and no secret. Redirect URIs must be https, http on localhost, or the app's own scheme (com.example.app:). Owners, admins and developers can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`name`	`string`, min length 1, max length 120	Yes	The app name shown on the sign-in screen.
`redirect_uris`	`array<string>`, min items 1, max items 20	Yes	Where to go back to after signing in.
`public`	`boolean`	No	True for a public client with no secret. The default is false.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The app name shown on the sign-in screen."
    },
    "redirect_uris": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Where to go back to after signing in."
    },
    "public": {
      "type": "boolean",
      "description": "True for a public client with no secret. The default is false."
    }
  },
  "required": [
    "ref",
    "name",
    "redirect_uris"
  ],
  "additionalProperties": false
}

`reset_oauth_app_secret` Make a new OAuth app secret

Destructive

Makes a new client_secret for the app and shows it this once. The old one stops working at once, so the app's settings must change too. Owners, admins and developers can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`client_id`	`string`	Yes	A client_id from list_oauth_apps.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "client_id": {
      "type": "string",
      "description": "A client_id from list_oauth_apps."
    }
  },
  "required": [
    "ref",
    "client_id"
  ],
  "additionalProperties": false
}

`remove_oauth_app` Remove an OAuth app

Destructive

Removes the app's registration. It can no longer sign in. Put the app's name (client_name) in confirm. Owners, admins and developers can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`client_id`	`string`	Yes	A client_id from list_oauth_apps.
`confirm`	`string`	Yes	The app's name (client_name), exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "client_id": {
      "type": "string",
      "description": "A client_id from list_oauth_apps."
    },
    "confirm": {
      "type": "string",
      "description": "The app's name (client_name), exactly."
    }
  },
  "required": [
    "ref",
    "client_id",
    "confirm"
  ],
  "additionalProperties": false
}

`list_shared_env_vars` Shared environment variables

Read-only

Returns the environment variables the organization gives several projects together, their values (hidden when sensitive), targets (production, preview) and linked projects. Owners, admins and developers can see this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_shared_env_var` Create a shared environment variable

Only adds

Creates an environment variable that several of the organization's projects receive. It reaches linked projects from their next deployment, and a project variable of the same name wins. Only projects you can open are linked. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`key`	`string`	Yes	The name (letters, digits, _).
`value`	`string`	Yes	The value.
`targets`	`array<string>`, production \| preview	No	Both by default.
`sensitive`	`boolean`	No	True never shows the value again. Once on, it cannot be turned off.
`note`	`string`	No	A note, up to 200 characters.
`projects`	`array<string>`	No	Refs of the projects to link.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "key": {
      "type": "string",
      "description": "The name (letters, digits, _)."
    },
    "value": {
      "type": "string",
      "description": "The value."
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "production",
          "preview"
        ]
      },
      "description": "Both by default."
    },
    "sensitive": {
      "type": "boolean",
      "description": "True never shows the value again. Once on, it cannot be turned off."
    },
    "note": {
      "type": "string",
      "description": "A note, up to 200 characters."
    },
    "projects": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Refs of the projects to link."
    }
  },
  "required": [
    "ref",
    "key",
    "value"
  ],
  "additionalProperties": false
}

`update_shared_env_var` Change a shared environment variable

Destructive

Changes a shared variable's value, targets, note and linked projects. Only what is given changes; without value the value stays. projects is the whole list, and links to projects you cannot open stay. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_shared_env_vars.
`value`	`string`	No	The new value.
`targets`	`array<string>`, production \| preview	No	All the targets.
`sensitive`	`boolean`	No	True hides the value. It cannot be turned off.
`note`	`string`	No	The note.
`projects`	`array<string>`	No	Refs of all the projects to link.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_shared_env_vars."
    },
    "value": {
      "type": "string",
      "description": "The new value."
    },
    "targets": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "production",
          "preview"
        ]
      },
      "description": "All the targets."
    },
    "sensitive": {
      "type": "boolean",
      "description": "True hides the value. It cannot be turned off."
    },
    "note": {
      "type": "string",
      "description": "The note."
    },
    "projects": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Refs of all the projects to link."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`remove_shared_env_var` Remove a shared environment variable

Destructive

Removes a shared variable. Linked projects lose it from their next deployment. Put the variable name in confirm. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_shared_env_vars.
`confirm`	`string`	Yes	The variable name (key), exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_shared_env_vars."
    },
    "confirm": {
      "type": "string",
      "description": "The variable name (key), exactly."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`list_access_groups` Access groups

Read-only

Returns the access groups, which give a set of the organization's members a role (developer, billing, viewer) on chosen projects, with their members (emails) and projects.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_access_group` Create an access group

Only adds

Creates an empty access group. Add members and projects with update_access_group. Up to 50 per organization. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`name`	`string`, min length 1, max length 60	Yes	The group name.
`description`	`string`	No	A description, up to 300 characters.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "The group name."
    },
    "description": {
      "type": "string",
      "description": "A description, up to 300 characters."
    }
  },
  "required": [
    "ref",
    "name"
  ],
  "additionalProperties": false
}

`update_access_group` Change an access group

Destructive

Changes a group's name, description, members and role on each project. Only what is given changes. members is the whole list of member emails; projects is the whole {ref: role} map (developer, billing or viewer; a project left out gets none). A group cannot give the owner or admin role. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_access_groups.
`name`	`string`, min length 1, max length 60	No	The new name.
`description`	`string`	No	The new description.
`members`	`array<string>`	No	All the member emails. Only people in list_team.
`projects`	`object`	No	A map of project ref to role (developer, billing or viewer; a project left out gets none), for example {"abcdefghijklmnopqrst": "developer"}.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_access_groups."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "The new name."
    },
    "description": {
      "type": "string",
      "description": "The new description."
    },
    "members": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "All the member emails. Only people in list_team."
    },
    "projects": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "developer",
          "billing",
          "viewer"
        ]
      },
      "description": "A map of project ref to role (developer, billing or viewer; a project left out gets none), for example {\"abcdefghijklmnopqrst\": \"developer\"}."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`remove_access_group` Remove an access group

Destructive

Removes an access group. People who opened projects through it lose that access. Put the group name in confirm. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_access_groups.
`confirm`	`string`	Yes	The group name, exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_access_groups."
    },
    "confirm": {
      "type": "string",
      "description": "The group name, exactly."
    }
  },
  "required": [
    "ref",
    "id",
    "confirm"
  ],
  "additionalProperties": false
}

`get_member_access` A member's project access

Read-only

Returns whether one member opens every project in the organization (scoped false) or only chosen ones (scoped true), the role on each, and the access groups they are in. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`email`	`string`	Yes	A member's email from list_team.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "email": {
      "type": "string",
      "description": "A member's email from list_team."
    }
  },
  "required": [
    "ref",
    "email"
  ],
  "additionalProperties": false
}

`set_member_access` Change a member's project access

Destructive

With scoped false the member opens every project with their organization role. With scoped true only projects ({ref: developer, billing or viewer}) and what access groups give. Owners and admins cannot be narrowed. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`email`	`string`	Yes	A member's email from list_team.
`scoped`	`boolean`	Yes	True for chosen projects only.
`projects`	`object`	No	With scoped true, the whole map. A map of project ref to role (developer, billing or viewer; a project left out gets none), for example {"abcdefghijklmnopqrst": "developer"}.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "email": {
      "type": "string",
      "description": "A member's email from list_team."
    },
    "scoped": {
      "type": "boolean",
      "description": "True for chosen projects only."
    },
    "projects": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "developer",
          "billing",
          "viewer"
        ]
      },
      "description": "With scoped true, the whole map. A map of project ref to role (developer, billing or viewer; a project left out gets none), for example {\"abcdefghijklmnopqrst\": \"developer\"}."
    }
  },
  "required": [
    "ref",
    "email",
    "scoped"
  ],
  "additionalProperties": false
}

`list_audit_drains` Audit log drains

Read-only

Returns where the organization's audit log is sent to security tools (https, Datadog, Splunk, syslog), how far behind each is, failures, the https signing secret (signing_secret), and whether the plan allows it (allowed). Only owners and admins can see this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_audit_drain` Create an audit log drain

Only adds Reaches outside

Adds a place the audit log is sent to from now on. kind: https (signed JSON), datadog (API key in secret), splunk (the HEC address, token in secret), syslog (syslog+tls://host:port). Up to 5 per organization, and the plan must include it. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`name`	`string`, min length 1, max length 60	Yes	A name.
`kind`	`string`, https \| datadog \| splunk \| syslog	Yes	Where it goes: https, datadog, splunk or syslog.
`url`	`string`	Yes	The address to send to.
`secret`	`string`	No	The Datadog or Splunk key or token. Only its last four characters are shown after saving.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "A name."
    },
    "kind": {
      "type": "string",
      "enum": [
        "https",
        "datadog",
        "splunk",
        "syslog"
      ],
      "description": "Where it goes: https, datadog, splunk or syslog."
    },
    "url": {
      "type": "string",
      "description": "The address to send to."
    },
    "secret": {
      "type": "string",
      "description": "The Datadog or Splunk key or token. Only its last four characters are shown after saving."
    }
  },
  "required": [
    "ref",
    "name",
    "kind",
    "url"
  ],
  "additionalProperties": false
}

`set_audit_drain_enabled` Turn an audit log drain on or off

Destructive

Pauses a drain or turns it back on. Back on, it sends from where it stopped. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_audit_drains.
`enabled`	`boolean`	Yes	On or off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_audit_drains."
    },
    "enabled": {
      "type": "boolean",
      "description": "On or off."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`test_audit_drain` Test an audit log drain

Only adds Reaches outside

Sends one made-up test record now and returns the receiver's answer (HTTP status). The real log is untouched. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_audit_drains.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_audit_drains."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`remove_audit_drain` Remove an audit log drain

Destructive

Removes a drain. What was already sent stays with the receiver. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_audit_drains.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_audit_drains."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_org_webhooks` Organization webhooks

Read-only

Returns the webhooks that send the organization's notices (deployments, domains, usage, billing), their signing secrets (signing_secret) and the events to choose from (events). One project's own webhooks are list_project_webhooks. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`create_org_webhook` Create an organization webhook

Only adds Reaches outside

Creates a webhook that sends the organization's notices to a public https address. Empty events is every event; empty projects is every project and the organization's own notices. Up to 20 per organization together with notification channels. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`name`	`string`, min length 1, max length 60	Yes	A name.
`url`	`string`	Yes	A public https address.
`events`	`array<string>`, deployments.deploy-failed \| deployments.deploy-ready \| deployments.deploy-succeeded \| domains.domain-verified \| domains.domain-unverified \| domains.domain-tls \| domains.domain-cert-expiring \| usage.usage \| billing.charge-paid \| billing.charge-failed \| billing.no-card \| billing.plan \| billing.subscription	No	The events to send. Empty is all.
`projects`	`array<string>`	No	Only these projects' notices. Empty is all.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "A name."
    },
    "url": {
      "type": "string",
      "description": "A public https address."
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "deployments.deploy-failed",
          "deployments.deploy-ready",
          "deployments.deploy-succeeded",
          "domains.domain-verified",
          "domains.domain-unverified",
          "domains.domain-tls",
          "domains.domain-cert-expiring",
          "usage.usage",
          "billing.charge-paid",
          "billing.charge-failed",
          "billing.no-card",
          "billing.plan",
          "billing.subscription"
        ]
      },
      "description": "The events to send. Empty is all."
    },
    "projects": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Only these projects' notices. Empty is all."
    }
  },
  "required": [
    "ref",
    "name",
    "url"
  ],
  "additionalProperties": false
}

`set_org_webhook_enabled` Turn an organization webhook on or off

Destructive

Pauses an organization webhook or lets it send again. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_org_webhooks.
`enabled`	`boolean`	Yes	On or off.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_org_webhooks."
    },
    "enabled": {
      "type": "boolean",
      "description": "On or off."
    }
  },
  "required": [
    "ref",
    "id",
    "enabled"
  ],
  "additionalProperties": false
}

`test_org_webhook` Test an organization webhook

Only adds Reaches outside

Sends one signed test event. The result shows in list_org_webhook_deliveries. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_org_webhooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_org_webhooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`list_org_webhook_deliveries` Organization webhook deliveries

Read-only

The last 100 deliveries of an organization webhook: event, project, status (pending, sent or failed), attempts and why it failed. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_org_webhooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_org_webhooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`retry_org_webhook_delivery` Send an organization webhook delivery again

Only adds Reaches outside

Sends a finished delivery again, as a new delivery. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`delivery_id`	`integer`, min 1	Yes	An id from list_org_webhook_deliveries.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "delivery_id": {
      "type": "integer",
      "minimum": 1,
      "description": "An id from list_org_webhook_deliveries."
    }
  },
  "required": [
    "ref",
    "delivery_id"
  ],
  "additionalProperties": false
}

`remove_org_webhook` Remove an organization webhook

Destructive

Removes an organization webhook. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from list_org_webhooks.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from list_org_webhooks."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_committer_settings` Outside committer settings

Read-only

Returns whether previews committed by people outside the organization build at once (policy: auto) or wait for approval (require), the trusted committers (trusted), and the waiting previews you can answer (waiting).

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_committer_policy` Change the outside committer policy

Destructive

With auto previews build whoever committed. With require a preview by someone who is neither a member nor a trusted committer waits for approval. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`policy`	`string`, auto \| require	Yes	auto or require.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "policy": {
      "type": "string",
      "enum": [
        "auto",
        "require"
      ],
      "description": "auto or require."
    }
  },
  "required": [
    "ref",
    "policy"
  ],
  "additionalProperties": false
}

`trust_committer` Trust a committer

Only adds

Previews committed with this email build without approval. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`email`	`string`	Yes	The commit author's email.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "email": {
      "type": "string",
      "description": "The commit author's email."
    }
  },
  "required": [
    "ref",
    "email"
  ],
  "additionalProperties": false
}

`remove_trusted_committer` Stop trusting a committer

Destructive

This email's next previews wait for approval again. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`email`	`string`	Yes	A trusted[].email from get_committer_settings.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "email": {
      "type": "string",
      "description": "A trusted[].email from get_committer_settings."
    }
  },
  "required": [
    "ref",
    "email"
  ],
  "additionalProperties": false
}

`answer_preview_approval` Answer a waiting preview

Destructive

Approves (builds), trusts (builds and trusts the author) or declines (cancels) an outside committer's preview. It builds someone else's code, so approve only after checking it. Only people who can write to that project (developers and above) can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from get_committer_settings's waiting[].
`verdict`	`string`, approve \| trust \| decline	Yes	approve, trust or decline.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from get_committer_settings's waiting[]."
    },
    "verdict": {
      "type": "string",
      "enum": [
        "approve",
        "trust",
        "decline"
      ],
      "description": "approve, trust or decline."
    }
  },
  "required": [
    "ref",
    "id",
    "verdict"
  ],
  "additionalProperties": false
}

`get_org_sso` Organization SSO

Read-only

Returns how members sign in to the console with the company identity provider (Okta, Entra and so on, OpenID Connect; only the secret's last four characters), the callback address, and the domains with the TXT record that proves each.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_org_sso` Set up organization SSO

Destructive Reaches outside

Creates or changes the organization's OpenID Connect sign-in. Only what is given changes; without client_secret the current one stays. Given issuer or discovery_url, the other addresses are read from the provider's document. With require_sso on, members sign in only through SSO. Register get_org_sso's callback_url with the identity provider. The plan must include it. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`issuer`	`string`	No	The issuer address (https).
`discovery_url`	`string`	No	The .../.well-known/openid-configuration address.
`authorization_url`	`string`	No	The authorization address. Usually left empty.
`token_url`	`string`	No	The token address. Usually left empty.
`userinfo_url`	`string`	No	The userinfo address. Usually left empty.
`jwks_url`	`string`	No	The signing keys address. Usually left empty.
`client_id`	`string`	No	The client ID.
`client_secret`	`string`	No	The client secret. Needed the first time.
`scopes`	`string`	No	Scopes, separated by spaces. Must include openid. The default is openid email profile.
`default_role`	`string`, admin \| developer \| billing \| viewer	No	The role of someone who first arrives through SSO.
`jit`	`boolean`	No	Whether to make an account for someone new. The default is true.
`require_sso`	`boolean`	No	Whether members sign in only through SSO. The default is false.
`enabled`	`boolean`	No	Whether SSO sign-in is on. The default is true.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "issuer": {
      "type": "string",
      "description": "The issuer address (https)."
    },
    "discovery_url": {
      "type": "string",
      "description": "The .../.well-known/openid-configuration address."
    },
    "authorization_url": {
      "type": "string",
      "description": "The authorization address. Usually left empty."
    },
    "token_url": {
      "type": "string",
      "description": "The token address. Usually left empty."
    },
    "userinfo_url": {
      "type": "string",
      "description": "The userinfo address. Usually left empty."
    },
    "jwks_url": {
      "type": "string",
      "description": "The signing keys address. Usually left empty."
    },
    "client_id": {
      "type": "string",
      "description": "The client ID."
    },
    "client_secret": {
      "type": "string",
      "description": "The client secret. Needed the first time."
    },
    "scopes": {
      "type": "string",
      "description": "Scopes, separated by spaces. Must include openid. The default is openid email profile."
    },
    "default_role": {
      "type": "string",
      "enum": [
        "admin",
        "developer",
        "billing",
        "viewer"
      ],
      "description": "The role of someone who first arrives through SSO."
    },
    "jit": {
      "type": "boolean",
      "description": "Whether to make an account for someone new. The default is true."
    },
    "require_sso": {
      "type": "boolean",
      "description": "Whether members sign in only through SSO. The default is false."
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether SSO sign-in is on. The default is true."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`remove_org_sso` Remove organization SSO

Destructive

Removes the organization's SSO connection. Members sign in with a password or another way. Put the issuer in confirm. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`confirm`	`string`	Yes	get_org_sso's connection.issuer, exactly.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "confirm": {
      "type": "string",
      "description": "get_org_sso's connection.issuer, exactly."
    }
  },
  "required": [
    "ref",
    "confirm"
  ],
  "additionalProperties": false
}

`add_org_sso_domain` Add an organization SSO domain

Only adds

Sends people signing in with an email at this domain to the organization's SSO. It works once the response's txt_record is in DNS and verify_org_sso_domain has checked it. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`domain`	`string`	Yes	For example example.com.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "domain": {
      "type": "string",
      "description": "For example example.com."
    }
  },
  "required": [
    "ref",
    "domain"
  ],
  "additionalProperties": false
}

`verify_org_sso_domain` Verify an organization SSO domain

Destructive Reaches outside

Looks up the TXT record in DNS to prove the domain. Once proved, people at this domain sign in through the organization's SSO. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from get_org_sso's domains[].

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from get_org_sso's domains[]."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`remove_org_sso_domain` Remove an organization SSO domain

Destructive

Removes a domain. People at it are no longer sent to SSO. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`id`	`string`	Yes	An id from get_org_sso's domains[].

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "id": {
      "type": "string",
      "description": "An id from get_org_sso's domains[]."
    }
  },
  "required": [
    "ref",
    "id"
  ],
  "additionalProperties": false
}

`get_org_policies` Organization deployment policies

Read-only

Returns new projects' default deployment protection (default_protection, default_scope), the ways a deployment may start (allow_git, cli, api, hooks), branch previews, and the preview domain (preview_suffix) with the TXT record that proves it.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_org_policies` Change organization deployment policies

Destructive

Changes the organization's deployment policies. Only what is given changes. default_protection and default_scope are new projects' defaults; existing projects stay as they are. With an allow_* off, deployments started that way are refused (allow_api includes MCP; the console's deploy button always works). Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`default_protection`	`string`, members \| off	No	Who sees new projects' previews.
`default_scope`	`string`, previews \| generated \| all	No	Which addresses new projects protect.
`allow_git`	`boolean`	No	Deploy by Git push.
`allow_cli`	`boolean`	No	Deploy with the CLI.
`allow_api`	`boolean`	No	Deploy through the API and MCP.
`allow_hooks`	`boolean`	No	Deploy with deploy hooks.
`branch_previews`	`boolean`	No	Build a preview for every branch push.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "default_protection": {
      "type": "string",
      "enum": [
        "members",
        "off"
      ],
      "description": "Who sees new projects' previews."
    },
    "default_scope": {
      "type": "string",
      "enum": [
        "previews",
        "generated",
        "all"
      ],
      "description": "Which addresses new projects protect."
    },
    "allow_git": {
      "type": "boolean",
      "description": "Deploy by Git push."
    },
    "allow_cli": {
      "type": "boolean",
      "description": "Deploy with the CLI."
    },
    "allow_api": {
      "type": "boolean",
      "description": "Deploy through the API and MCP."
    },
    "allow_hooks": {
      "type": "boolean",
      "description": "Deploy with deploy hooks."
    },
    "branch_previews": {
      "type": "boolean",
      "description": "Build a preview for every branch push."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`set_preview_suffix` Set the preview domain

Destructive

Opens the organization's previews under your own domain too (for example preview.example.com). It works once the response's preview_suffix_record is in DNS and verify_preview_suffix has checked it. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.
`suffix`	`string`	Yes	For example preview.example.com.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    },
    "suffix": {
      "type": "string",
      "description": "For example preview.example.com."
    }
  },
  "required": [
    "ref",
    "suffix"
  ],
  "additionalProperties": false
}

`verify_preview_suffix` Verify the preview domain

Destructive Reaches outside

Looks up the TXT record in DNS to prove the preview domain. When it is not there yet, call again in a few minutes. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`remove_preview_suffix` Remove the preview domain

Destructive

Removes the preview domain. Previews open only on the platform's addresses. Only owners and admins can do this.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The identifier of one of the organization's projects. Its organization is the one changed.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The identifier of one of the organization's projects. Its organization is the one changed."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`get_server` Dedicated server

Read-only

Shows the project's dedicated server: size (tier), location, status, address, monthly price, standby, automatic failover, restore days, when it may next move, and jobs in progress. server is null when the project uses the shared server; offered is false while dedicated servers are not open.

Name	Description
Token scope	`read`
Roles	Any member of the organisation
Console assistant confirmation	Does not ask
REST	GET `/projects/{ref}/server`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}

`request_server` Rent a dedicated server

Destructive

Rents a server for this project alone. Show sizes and monthly prices per location with list_server_sizes first, and pass only what the user chose. Usually ready within 10 minutes; the database and app move onto it, then the address switches. From the Pro plan. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/server`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`tier`	`string`, pattern ^[0-9]+gb$	Yes	Server size: a tier from list_server_sizes (for example 4gb).
`region`	`string`, pattern ^[a-z]{2}-[a-z]+-[0-9]$	No	Location; the project's own when absent. A region from list_server_sizes.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "tier": {
      "type": "string",
      "pattern": "^[0-9]+gb$",
      "description": "Server size: a tier from list_server_sizes (for example 4gb)."
    },
    "region": {
      "type": "string",
      "pattern": "^[a-z]{2}-[a-z]+-[0-9]$",
      "description": "Location; the project's own when absent. A region from list_server_sizes."
    }
  },
  "required": [
    "ref",
    "tier"
  ],
  "additionalProperties": false
}

`resize_server` Change the server size

Destructive

Changes the dedicated server's size. when=now does it now, tonight between 03:00 and 05:00 in the server location's time. Without a standby the server does not answer for 3 to 5 minutes; with one, only the few seconds of the switch. Changing size is free; the monthly price is the new size's (list_server_sizes). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PATCH `/projects/{ref}/server`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`tier`	`string`, pattern ^[0-9]+gb$	Yes	Server size: a tier from list_server_sizes (for example 4gb).
`when`	`string`, now \| tonight	No	now (default) or tonight (03:00 to 05:00).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "tier": {
      "type": "string",
      "pattern": "^[0-9]+gb$",
      "description": "Server size: a tier from list_server_sizes (for example 4gb)."
    },
    "when": {
      "type": "string",
      "enum": [
        "now",
        "tonight"
      ],
      "description": "now (default) or tonight (03:00 to 05:00)."
    }
  },
  "required": [
    "ref",
    "tier"
  ],
  "additionalProperties": false
}

`set_standby` Standby server

Destructive

Turns a standby server of the same size in the same location on or off. It replicates the database continuously and costs the same as its size a month (list_server_sizes). With auto_failover=true the project switches to it on its own once the primary has not answered for 60 seconds (needs a standby). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/server/standby`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`standby`	`boolean`	Yes	Whether to keep a standby server.
`auto_failover`	`boolean`	No	Automatic failover. false by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "standby": {
      "type": "boolean",
      "description": "Whether to keep a standby server."
    },
    "auto_failover": {
      "type": "boolean",
      "description": "Automatic failover. false by default."
    }
  },
  "required": [
    "ref",
    "standby"
  ],
  "additionalProperties": false
}

`move_server` Move the server

Destructive

Moves the dedicated server to another location. Free, once a month (next_move_at). A server is made there and replicated; writes pause for a few seconds when the address switches. The old server is kept for 7 days. The monthly price is the new location's (list_server_sizes). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	POST `/projects/{ref}/server/move`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`region`	`string`, pattern ^[a-z]{2}-[a-z]+-[0-9]$	Yes	Location: a region from list_server_sizes (for example kr-seoul-1).

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "region": {
      "type": "string",
      "pattern": "^[a-z]{2}-[a-z]+-[0-9]$",
      "description": "Location: a region from list_server_sizes (for example kr-seoul-1)."
    }
  },
  "required": [
    "ref",
    "region"
  ],
  "additionalProperties": false
}

`release_server` Give back the dedicated server

Destructive

Gives the dedicated server back: a last backup, the database and app moved to the shared server, then the server (and its standby) deleted. Writes pause during the move. Use it only when the user asks, and put the ref exactly in confirm. Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	DELETE `/projects/{ref}/server`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`confirm`	`string`	Yes	The project ID (ref). Must equal ref.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "confirm": {
      "type": "string",
      "description": "The project ID (ref). Must equal ref."
    }
  },
  "required": [
    "ref",
    "confirm"
  ],
  "additionalProperties": false
}

`set_restore_days` Restore days

Destructive

Sets how far back the project can be restored to a moment: 7 or 28 days. 28 is only on a dedicated server and adds a monthly charge (get_server options, get_billing). Only owners and admins can do this.

Name	Description
Token scope	`write`
Roles	`project.admin` owner or admin
Console assistant confirmation	Does not ask
REST	PUT `/projects/{ref}/server/restore-days`

Input

Name	Type	Required	Description
`ref`	`string`, pattern ^[a-z]{20}$	Yes	The project identifier. Find it with list_projects.
`days`	`integer`, 7 \| 28	Yes	7 or 28.

JSON Schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "pattern": "^[a-z]{20}$",
      "description": "The project identifier. Find it with list_projects."
    },
    "days": {
      "type": "integer",
      "enum": [
        7,
        28
      ],
      "description": "7 or 28."
    }
  },
  "required": [
    "ref",
    "days"
  ],
  "additionalProperties": false
}

`list_platform_settings` Platform settings

Read-only

For each platform setting an operator can change without a redeploy (the two values of the Supabase OAuth app for importing from another server, and the switches of server-change requests), returns whether a value is in force (set), where it comes from (source: env is the server's environment, stored is the saved value), whether a saved value exists (stored), and when (updated_at) and by whom (updated_by) it was last saved. Never returns a value. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`set_platform_setting` Save a platform setting

Destructive

Seals and saves the value of one platform setting. It applies within 30 seconds, with no redeploy. If the server's environment sets the same setting, the environment's value is used first (source in list_platform_settings). The value is never shown again; the audit log records who changed it. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`key`	`string`, BLACKWALL_IMPORT_SUPABASE_CLIENT_ID \| BLACKWALL_IMPORT_SUPABASE_CLIENT_SECRET \| BLACKWALL_SERVER_REQUESTS \| BLACKWALL_SERVER_NIGHT_UPSCALE \| BLACKWALL_SERVER_REQUESTS_REPO \| BLACKWALL_POOL_URL \| BLACKWALL_POOL_SECRET \| BLACKWALL_POOL_LABEL \| BLACKWALL_CI_POOL \| BLACKWALL_FUNCTION_AGENTS \| BLACKWALL_FUNCTION_HOST \| BLACKWALL_APP_AGENTS \| BLACKWALL_APP_HOST \| BLACKWALL_PROJECT_NETWORKS \| BLACKWALL_PROJECT_DISK_LIMITS \| BLACKWALL_PROJECT_SLICES \| BLACKWALL_SERVER_AUTOSCALE \| BLACKWALL_PROJECT_READS_PER_MINUTE \| BLACKWALL_PROJECT_WRITES_PER_MINUTE \| BLACKWALL_PARKING_HOSTS \| BLACKWALL_BUILD_CACHE_BUCKET	Yes	The setting. list_platform_settings returns them.
`value`	`string`, min length 1, max length 2000	Yes	The value to save. One line, no spaces.

JSON Schema

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "enum": [
        "BLACKWALL_IMPORT_SUPABASE_CLIENT_ID",
        "BLACKWALL_IMPORT_SUPABASE_CLIENT_SECRET",
        "BLACKWALL_SERVER_REQUESTS",
        "BLACKWALL_SERVER_NIGHT_UPSCALE",
        "BLACKWALL_SERVER_REQUESTS_REPO",
        "BLACKWALL_POOL_URL",
        "BLACKWALL_POOL_SECRET",
        "BLACKWALL_POOL_LABEL",
        "BLACKWALL_CI_POOL",
        "BLACKWALL_FUNCTION_AGENTS",
        "BLACKWALL_FUNCTION_HOST",
        "BLACKWALL_APP_AGENTS",
        "BLACKWALL_APP_HOST",
        "BLACKWALL_PROJECT_NETWORKS",
        "BLACKWALL_PROJECT_DISK_LIMITS",
        "BLACKWALL_PROJECT_SLICES",
        "BLACKWALL_SERVER_AUTOSCALE",
        "BLACKWALL_PROJECT_READS_PER_MINUTE",
        "BLACKWALL_PROJECT_WRITES_PER_MINUTE",
        "BLACKWALL_PARKING_HOSTS",
        "BLACKWALL_BUILD_CACHE_BUCKET"
      ],
      "description": "The setting. list_platform_settings returns them."
    },
    "value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The value to save. One line, no spaces."
    }
  },
  "required": [
    "key",
    "value"
  ],
  "additionalProperties": false
}

`clear_platform_setting` Clear a platform setting

Destructive

Removes the saved value. If the server's environment sets the same setting, that value keeps being used. With nothing saved, nothing changes. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`key`	`string`, BLACKWALL_IMPORT_SUPABASE_CLIENT_ID \| BLACKWALL_IMPORT_SUPABASE_CLIENT_SECRET \| BLACKWALL_SERVER_REQUESTS \| BLACKWALL_SERVER_NIGHT_UPSCALE \| BLACKWALL_SERVER_REQUESTS_REPO \| BLACKWALL_POOL_URL \| BLACKWALL_POOL_SECRET \| BLACKWALL_POOL_LABEL \| BLACKWALL_CI_POOL \| BLACKWALL_FUNCTION_AGENTS \| BLACKWALL_FUNCTION_HOST \| BLACKWALL_APP_AGENTS \| BLACKWALL_APP_HOST \| BLACKWALL_PROJECT_NETWORKS \| BLACKWALL_PROJECT_DISK_LIMITS \| BLACKWALL_PROJECT_SLICES \| BLACKWALL_SERVER_AUTOSCALE \| BLACKWALL_PROJECT_READS_PER_MINUTE \| BLACKWALL_PROJECT_WRITES_PER_MINUTE \| BLACKWALL_PARKING_HOSTS \| BLACKWALL_BUILD_CACHE_BUCKET	Yes	The setting. list_platform_settings returns them.

JSON Schema

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "enum": [
        "BLACKWALL_IMPORT_SUPABASE_CLIENT_ID",
        "BLACKWALL_IMPORT_SUPABASE_CLIENT_SECRET",
        "BLACKWALL_SERVER_REQUESTS",
        "BLACKWALL_SERVER_NIGHT_UPSCALE",
        "BLACKWALL_SERVER_REQUESTS_REPO",
        "BLACKWALL_POOL_URL",
        "BLACKWALL_POOL_SECRET",
        "BLACKWALL_POOL_LABEL",
        "BLACKWALL_CI_POOL",
        "BLACKWALL_FUNCTION_AGENTS",
        "BLACKWALL_FUNCTION_HOST",
        "BLACKWALL_APP_AGENTS",
        "BLACKWALL_APP_HOST",
        "BLACKWALL_PROJECT_NETWORKS",
        "BLACKWALL_PROJECT_DISK_LIMITS",
        "BLACKWALL_PROJECT_SLICES",
        "BLACKWALL_SERVER_AUTOSCALE",
        "BLACKWALL_PROJECT_READS_PER_MINUTE",
        "BLACKWALL_PROJECT_WRITES_PER_MINUTE",
        "BLACKWALL_PARKING_HOSTS",
        "BLACKWALL_BUILD_CACHE_BUCKET"
      ],
      "description": "The setting. list_platform_settings returns them."
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false
}

`list_platform_servers` Platform servers

Read-only

For each of our own servers (the service host, the build host, the Actions pool, the always-on Actions machine, the database standby, the static outbound address and backup storage), returns its size now, its use over the last 24 hours, its monthly cost in USD, the change Raise and Lower would request (raise, lower), and open and recent requests. Machines are read from Google as asked (machines: name, zone, status, size, last start); a row with source unread is one Google did not answer for, with the reason in read_error. quota is the project's CPU allowance and its use (all regions, asia-northeast3, us-west1). Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`get_platform_cpu_history` Service host CPU history

Read-only

Reads the service host's recent CPU from its minute samples (host_samples). Returns the average and peak per step (buckets), and for 80% and 95% the minutes at or above it, how many separate times it happened, and the longest run with its start (over). Use it to see how often and how long the host is busy before deciding to size it up. If samples is far below expected_samples, nothing was recorded for the gap. Samples are kept 48 hours. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`hours`	`integer`, min 1, max 48	No	How many hours back. 24 by default.
`bucket_minutes`	`integer`, min 1, max 60	No	Step length in minutes. 5 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 48,
      "description": "How many hours back. 24 by default."
    },
    "bucket_minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 60,
      "description": "Step length in minutes. 5 by default."
    }
  },
  "additionalProperties": false
}

`request_platform_server_change` Request a platform server change

Destructive

Requests one change to one server: the service host's size (main, resize), the build host on, off or its size (build), the database standby on or off (standby), a backup copy in another region (backup, replica), one machine by name started, stopped or resized (vm), the always-on Actions machine retired (runner, retire: RUNNER is deleted in the five repositories and checked before the machine is stopped), the Actions pool reset (pool, reset: every machine that is on but running no check is stopped), the Actions pool's image baked (pool, bake: a temporary machine prepared by startup.sh, imaged into the family oneserver-pool, the machine deleted), a Cloud NAT made (network, nat: the region's router and NAT made where missing), or the build machines' image baked (build-image, bake: docker, node, the platform and the build image installed on a temporary machine, imaged into the family blackwall-build, the machine deleted; new build machines then boot from it in seconds). The reconciler carries it out through the deploy workflow, and vm, runner, pool, network and build-image with this server's own service account. Resizing the service host stops every site for 3 to 5 minutes, so it needs confirm=true, and runs tonight (03:00 to 05:00 KST) unless when=now. One open request per server. Only while BLACKWALL_SERVER_REQUESTS=on. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`server`	`string`, main \| build \| standby \| backup \| vm \| runner \| pool \| network \| build-image	Yes	The server to change.
`action`	`string`, resize \| on \| off \| replica \| start \| stop \| retire \| reset \| nat \| bake	Yes	resize for main; on, off or resize for build; on or off for standby; replica for backup; start, stop or resize for vm; retire for runner; reset or bake for pool; nat for network; bake for build-image.
`region`	`string`, us-west1	No	For network nat: the region. us-west1 (the Actions pool's region) by default.
`to`	`string`, e2-medium \| e2-standard-2 \| e2-standard-4 \| e2-standard-8	No	The new size, for resize.
`instance`	`string`	No	For vm: the machine, one of blackwall-build, blackwall-db-standby, oneserver-runner, oneserver-pool-1 to 6.
`zone`	`string`	No	For vm: its zone. Empty is the machine's own.
`repos`	`array<string>`	No	For runner retire: the repositories (owner/name) RUNNER is deleted in. Empty is the five.
`when`	`string`, now \| tonight	No	now, or tonight (03:00 to 05:00 KST). tonight is the default for main, now for the rest.
`confirm`	`boolean`	No	Needed for a main resize: the caller knows every site stops for 3 to 5 minutes.
`no_downtime`	`boolean`	No	Resize main without a pause. Needs a healthy standby and a second host serving the sites, so it is refused today.
`location`	`string`	No	The region of the backup copy. us-west1 (Oregon) by default; none stops the copy.
`reason`	`string`, max length 300	No	Why. Kept in the audit log.

JSON Schema

{
  "type": "object",
  "properties": {
    "server": {
      "type": "string",
      "enum": [
        "main",
        "build",
        "standby",
        "backup",
        "vm",
        "runner",
        "pool",
        "network",
        "build-image"
      ],
      "description": "The server to change."
    },
    "action": {
      "type": "string",
      "enum": [
        "resize",
        "on",
        "off",
        "replica",
        "start",
        "stop",
        "retire",
        "reset",
        "nat",
        "bake"
      ],
      "description": "resize for main; on, off or resize for build; on or off for standby; replica for backup; start, stop or resize for vm; retire for runner; reset or bake for pool; nat for network; bake for build-image."
    },
    "region": {
      "type": "string",
      "enum": [
        "us-west1"
      ],
      "description": "For network nat: the region. us-west1 (the Actions pool's region) by default."
    },
    "to": {
      "type": "string",
      "enum": [
        "e2-medium",
        "e2-standard-2",
        "e2-standard-4",
        "e2-standard-8"
      ],
      "description": "The new size, for resize."
    },
    "instance": {
      "type": "string",
      "description": "For vm: the machine, one of blackwall-build, blackwall-db-standby, oneserver-runner, oneserver-pool-1 to 6."
    },
    "zone": {
      "type": "string",
      "description": "For vm: its zone. Empty is the machine's own."
    },
    "repos": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "For runner retire: the repositories (owner/name) RUNNER is deleted in. Empty is the five."
    },
    "when": {
      "type": "string",
      "enum": [
        "now",
        "tonight"
      ],
      "description": "now, or tonight (03:00 to 05:00 KST). tonight is the default for main, now for the rest."
    },
    "confirm": {
      "type": "boolean",
      "description": "Needed for a main resize: the caller knows every site stops for 3 to 5 minutes."
    },
    "no_downtime": {
      "type": "boolean",
      "description": "Resize main without a pause. Needs a healthy standby and a second host serving the sites, so it is refused today."
    },
    "location": {
      "type": "string",
      "description": "The region of the backup copy. us-west1 (Oregon) by default; none stops the copy."
    },
    "reason": {
      "type": "string",
      "maxLength": 300,
      "description": "Why. Kept in the audit log."
    }
  },
  "required": [
    "server",
    "action"
  ],
  "additionalProperties": false
}

`get_platform_server_request` Platform server change request

Read-only

One request's status (queued, dispatched, done, failed, refused, canceled), every step so far, and the workflow run's address (run_url). Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`id`	`string`	Yes	The request id. request_platform_server_change and list_platform_servers return it.

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The request id. request_platform_server_change and list_platform_servers return it."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

`cancel_platform_server_request` Cancel a platform server change request

Destructive

Cancels a request that has not started (queued). One already started is stopped from the run's page on GitHub. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`id`	`string`	Yes	The request id. request_platform_server_change and list_platform_servers return it.

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The request id. request_platform_server_change and list_platform_servers return it."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

`list_github_variables` GitHub repository variables

Read-only

Returns the Actions variables (such as vars.RUNNER) of a repository the platform's GitHub App is installed on, with their values and when they changed. When the App lacks the Variables permission, says how to grant it. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`repo`	`string`, pattern ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$	Yes	The repository, owner/name. For example Blackkyle8/BlackAll.

JSON Schema

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
      "description": "The repository, owner/name. For example Blackkyle8/BlackAll."
    }
  },
  "required": [
    "repo"
  ],
  "additionalProperties": false
}

`set_github_variable` Save a GitHub repository variable

Destructive

Saves one Actions variable of a repository, making it when it is not there. The audit log records who changed which variable of which repository. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`repo`	`string`, pattern ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$	Yes	The repository, owner/name. For example Blackkyle8/BlackAll.
`name`	`string`, pattern ^[A-Za-z_][A-Za-z0-9_]*$	Yes	The variable. For example RUNNER.
`value`	`string`, max length 48000	Yes	The value.

JSON Schema

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
      "description": "The repository, owner/name. For example Blackkyle8/BlackAll."
    },
    "name": {
      "type": "string",
      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      "description": "The variable. For example RUNNER."
    },
    "value": {
      "type": "string",
      "maxLength": 48000,
      "description": "The value."
    }
  },
  "required": [
    "repo",
    "name",
    "value"
  ],
  "additionalProperties": false
}

`delete_github_variable` Delete a GitHub repository variable

Destructive

Deletes one Actions variable of a repository. For example, with RUNNER deleted the repository's checks go to GitHub's machines (ubuntu-latest). Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`repo`	`string`, pattern ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$	Yes	The repository, owner/name. For example Blackkyle8/BlackAll.
`name`	`string`, pattern ^[A-Za-z_][A-Za-z0-9_]*$	Yes	The variable. For example RUNNER.

JSON Schema

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$",
      "description": "The repository, owner/name. For example Blackkyle8/BlackAll."
    },
    "name": {
      "type": "string",
      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      "description": "The variable. For example RUNNER."
    }
  },
  "required": [
    "repo",
    "name"
  ],
  "additionalProperties": false
}

`list_platform_operators` Platform operators

Read-only

For each operator address, returns where it comes from (source: env is the server's BLACKWALL_OPERATOR_EMAILS, stored is one an operator added) and who added it and when. To use the operator tools an account also needs two-step verification on. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`add_platform_operator` Add a platform operator

Destructive

Adds one address to the operator list. It applies within 30 seconds with no redeploy, and is kept in the audit log. An address already there changes nothing. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`email`	`string`, max length 320	Yes	The address, such as [email protected].

JSON Schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 320,
      "description": "The address, such as [email protected]."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

`remove_platform_operator` Remove a platform operator

Destructive

Removes one address an operator added (source stored). An address in the server's environment, and your own, cannot be removed here. Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`email`	`string`, max length 320	Yes	The address, such as [email protected].

JSON Schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 320,
      "description": "The address, such as [email protected]."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

`list_platform_runs` Platform workflow runs

Read-only

Returns the recent runs of the checks, deploy, ops and static-egress workflows of One Server's repository, newest first: id, status, conclusion, age_minutes, url. A run waiting for a machine (queued) for more than 15 minutes has stuck: true. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`workflow`	`string`, checks.yml \| deploy.yml \| ops.yml \| static-egress.yml	No	One workflow only. Empty is all four.
`per_workflow`	`integer`, min 1, max 20	No	How many of each workflow. 5 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "workflow": {
      "type": "string",
      "enum": [
        "checks.yml",
        "deploy.yml",
        "ops.yml",
        "static-egress.yml"
      ],
      "description": "One workflow only. Empty is all four."
    },
    "per_workflow": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "How many of each workflow. 5 by default."
    }
  },
  "additionalProperties": false
}

`cancel_platform_run` Cancel a platform workflow run

Destructive

Cancels one run that has not finished. A deploy run cancelled midway can leave that deploy half done. Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Always asks

Input

Name	Type	Required	Description
`id`	`integer`, min 1	Yes	The run id. list_platform_runs returns it.

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1,
      "description": "The run id. list_platform_runs returns it."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

`rerun_platform_run` Re-run a platform workflow run

Destructive

Runs one finished run again; with failed_only=true, only its failed jobs. Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`id`	`integer`, min 1	Yes	The run id. list_platform_runs returns it.
`failed_only`	`boolean`	No	Only the failed jobs. false by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1,
      "description": "The run id. list_platform_runs returns it."
    },
    "failed_only": {
      "type": "boolean",
      "description": "Only the failed jobs. false by default."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

`list_platform_checks` Platform checks

Read-only

Returns the recent runs of the repository checks One Server runs itself, without GitHub Actions (BLACKWALL_OWN_CI), newest first: kind (main, pr, merge), commit, state, each job's state, step and machine, broke_main (the commit that broke main) and had_stuck (a stuck machine was run again). Also which controller is acting (controller: seoul or tokyo) and the pull requests waiting to merge when green (merge_when_green). Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`limit`	`integer`, min 1, max 50	No	How many. 20 by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "How many. 20 by default."
    }
  },
  "additionalProperties": false
}

`set_merge_when_green` Merge when green

Destructive

Puts one pull request of the platform's repository in the merge-when-green queue (enabled=true) or takes it out (false). Waiting pull requests are checked together on top of main and, when green, merged in the order they were added. When red, the batch is split in half and checked again to send back the one that fails; the rest merge. One that conflicts with main is sent back with the names of the conflicting files. Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`pr`	`integer`, min 1	Yes	The pull request number, such as 431.
`enabled`	`boolean`	Yes	true adds it, false takes it out.

JSON Schema

{
  "type": "object",
  "properties": {
    "pr": {
      "type": "integer",
      "minimum": 1,
      "description": "The pull request number, such as 431."
    },
    "enabled": {
      "type": "boolean",
      "description": "true adds it, false takes it out."
    }
  },
  "required": [
    "pr",
    "enabled"
  ],
  "additionalProperties": false
}

`get_ci_machines` CI machines

Read-only

Returns the machines that run checks and deploys: the always-on deploy machine (oneserver-runner), the Actions pool (oneserver-pool-N) and the Tokyo standby controller of our own checks (oneserver-ci-standby). For each: status, zone, last_start, registration (its GitHub runner registration) and last_job (the last job it took); and the checks controller acting now (controller). Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`restart_ci_machine` Restart a CI machine

Destructive

Restarts one CI machine (Google's reset, like the power button). A job running on it is cut. Only oneserver-runner, oneserver-pool-<number> and oneserver-ci-standby; any other name is refused before Google is asked. Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`name`	`string`, pattern ^(oneserver-runner(-[a-z0-9-]+)?\|oneserver-pool-[0-9]+\|oneserver-ci-standby)$	Yes	The machine, such as oneserver-runner. get_ci_machines returns them.

JSON Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^(oneserver-runner(-[a-z0-9-]+)?|oneserver-pool-[0-9]+|oneserver-ci-standby)$",
      "description": "The machine, such as oneserver-runner. get_ci_machines returns them."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

`renew_ci_registration` Register a CI machine again

Destructive

Registers a machine's GitHub runners again with the platform's GitHub App token (no personal token). oneserver-runner gets a fresh registration token for each repository and restarts; oneserver-pool-<number> has its leftover registration removed and is stopped, so the controller registers it anew. Kept in the audit log. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`name`	`string`, pattern ^(oneserver-runner(-[a-z0-9-]+)?\|oneserver-pool-[0-9]+\|oneserver-ci-standby)$	Yes	The machine, such as oneserver-runner. get_ci_machines returns them.

JSON Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^(oneserver-runner(-[a-z0-9-]+)?|oneserver-pool-[0-9]+|oneserver-ci-standby)$",
      "description": "The machine, such as oneserver-runner. get_ci_machines returns them."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

`set_up_build_cache_bucket` Set up the build cache bucket

Destructive

Makes the build cache's own Google Cloud Storage bucket in the region the build machines run in (only if it is not there), sets the rule that deletes copies after 14 days, lets the build machines' service account create and read objects in it (never delete), and saves it as the platform setting BLACKWALL_BUILD_CACHE_BUCKET. The name is derived from the project and the region, never typed. Regions: asia-northeast1 (Tokyo), asia-northeast3 (Seoul), us-west1 (Oregon). Calling it again changes nothing. If the main host's Google account may not create buckets it stops with 403 and names the permission to give in the console. The setting is saved only once the build machines are confirmed able to use the bucket. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`region`	`string`, asia-northeast1 \| asia-northeast3 \| us-west1	Yes	The region the build machines run in. asia-northeast1 while the pool is in Tokyo.
`service_account`	`string`, max length 320	No	The service account to grant. Empty: the blackwall-build template machine's account.

JSON Schema

{
  "type": "object",
  "properties": {
    "region": {
      "type": "string",
      "enum": [
        "asia-northeast1",
        "asia-northeast3",
        "us-west1"
      ],
      "description": "The region the build machines run in. asia-northeast1 while the pool is in Tokyo."
    },
    "service_account": {
      "type": "string",
      "maxLength": 320,
      "description": "The service account to grant. Empty: the blackwall-build template machine's account."
    }
  },
  "required": [
    "region"
  ],
  "additionalProperties": false
}

`get_platform_overview` Platform overview

Read-only

Returns the whole platform at once: organisations and projects counted (by status and plan), projects not ready, rented servers and their jobs (queued, running, failed in the last 7 days, with id and age in minutes), dedicated disk and dedicated server requests (dedicated_requests: id, target disk or vm, status, age in minutes), the last 24 hours of deployments (by status, failed, and stuck for over 30 minutes), a summary of the CI machines (ci_machines), the server sales switches, and the list of what needs attention (attention: what, id, detail, age_minutes, next_tool). Changes nothing. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`find_customer` Find a customer

Read-only

Finds organisations (up to 10) by an address (email), an organisation id, a user id, a project ref or id, a domain, or an organisation or project name. For each: matched_by, the owners' addresses, plan, status and whether it is suspended; for each of its projects: status, region, last deployment, domains, rented servers and open dedicated requests. Changes nothing. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`query`	`string`, min length 2, max length 320	Yes	What to look for, such as [email protected], a project ref, example.com or an organisation name.

JSON Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 320,
      "description": "What to look for, such as [email protected], a project ref, example.com or an organisation name."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

`list_parking_hosts` Free servers

Read-only

Returns each region's free servers, which hold free projects together: for each its region, machine name (machine), zone, status, projects held and the most it takes (projects, max_projects), memory (memory_used_mb, memory_mb), how many are still moving in (moving), and projects now on a paid plan that need a database server of their own (paid); per region how many projects wait for a place (waiting), and the switch (switch: BLACKWALL_PARKING_HOSTS). Changes nothing. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`list_project_placements` Project placements

Read-only

Returns where each project's production database is: the project's region (region), where it is placed (placed_on: machine, a database server of its own; free_server; disk, a disk of its own on the main host; main_host; shared_cluster; none, not made yet), the machine name (machine), the zone and that zone's region (zone_region), whether that is inside the project's region (in_region), and the zone of a database server still being made for it (pending_zone). Also each zone with its region, whether database servers are made there (machines) and how many projects are placed in it, the switch (switch: machines_follow_region), how many are outside their region (outside_region) and how many are still on the main host (on_main_host). Changes nothing. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`get_platform_server_pricing` Customer server sizes and prices

Read-only

Returns the switches that sell customer servers (policy: customer_hosts, server_sizes_listed, customer_host_regions, krw_per_usd and the rest) and, for each size, its machine, memory, listed (shown to customers and rentable), plan, margin_floor and the servers rented on it; per region the machine's cost and the whole cost (USD), the prices (usd_minor in cents, krw_minor in won), what is received (received_usd: the lower of won and dollars after VAT and fees), the margin and for_sale. A non-empty violations means a price under its margin floor. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

No input.

JSON Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

`set_platform_server_pricing` Change the customer server switches

Destructive

Changes one or more fields of server_pricing_policy. For example, with customer_hosts=true and server_sizes_listed=true customers see the server sizes and can rent one. Only the fields given change, at once. The audit log records who changed which field from what to what, and when. A rate that would put a price under its margin floor is refused. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`customer_hosts`	`boolean`	No	Customers may rent a server of their own. Off, new requests are refused.
`server_sizes_listed`	`boolean`	No	Customers are shown the server sizes and their prices (console, CLI, MCP and REST).
`region_rates`	`boolean`	No	A region's own usage rates apply.
`build_machine_plans`	`boolean`	No	Enhanced and turbo build machines only on Pro and above.
`customer_host_regions`	`array<string>`, min items 1, max items 20	No	The region codes servers are rented in, such as ["kr-seoul-1"]. Only regions with costs.
`krw_per_usd`	`number`, min 100, max 10000	No	The won per dollar the margin check and won prices use. 1475 by default.
`customer_host_grace_days`	`integer`, min 1, max 30	No	Days a server stays read-only after payment stops.
`customer_host_create_minutes`	`integer`, min 3, max 60	No	Minutes a new machine may stay silent before it is deleted and made again.
`customer_host_max_attempts`	`integer`, min 1, max 10	No	How many times making a server is tried.
`customer_host_disk_gb`	`integer`, min 10, max 2000	No	A new server's disk, in GB.
`customer_host_move_days`	`integer`, min 1, max 365	No	Days between two moves of a server to another region.
`customer_host_retired_days`	`integer`, min 0, max 30	No	Days the old server is kept after a move.

JSON Schema

{
  "type": "object",
  "properties": {
    "customer_hosts": {
      "type": "boolean",
      "description": "Customers may rent a server of their own. Off, new requests are refused."
    },
    "server_sizes_listed": {
      "type": "boolean",
      "description": "Customers are shown the server sizes and their prices (console, CLI, MCP and REST)."
    },
    "region_rates": {
      "type": "boolean",
      "description": "A region's own usage rates apply."
    },
    "build_machine_plans": {
      "type": "boolean",
      "description": "Enhanced and turbo build machines only on Pro and above."
    },
    "customer_host_regions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "The region codes servers are rented in, such as [\"kr-seoul-1\"]. Only regions with costs."
    },
    "krw_per_usd": {
      "type": "number",
      "minimum": 100,
      "maximum": 10000,
      "description": "The won per dollar the margin check and won prices use. 1475 by default."
    },
    "customer_host_grace_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 30,
      "description": "Days a server stays read-only after payment stops."
    },
    "customer_host_create_minutes": {
      "type": "integer",
      "minimum": 3,
      "maximum": 60,
      "description": "Minutes a new machine may stay silent before it is deleted and made again."
    },
    "customer_host_max_attempts": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "How many times making a server is tried."
    },
    "customer_host_disk_gb": {
      "type": "integer",
      "minimum": 10,
      "maximum": 2000,
      "description": "A new server's disk, in GB."
    },
    "customer_host_move_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365,
      "description": "Days between two moves of a server to another region."
    },
    "customer_host_retired_days": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30,
      "description": "Days the old server is kept after a move."
    }
  },
  "minProperties": 1,
  "additionalProperties": false
}

`set_platform_server_size` Make or change a customer server size

Destructive

Makes or changes one customer server size: its Google machine (machine), whether customers see it (listed), the plan it is part of (plan), its margin floor (margin_floor), and per region its machine cost and prices (regions). A size is named by its memory, which must be the machine's (1gb is e2-micro). A new size stays hidden unless listed=true. Every price must clear the size's margin floor; selling under cost needs allow_loss=true, which lowers the floor as far as needed and is kept in the audit log. With no won price, it is usd × krw_per_usd rounded up to ₩1,000. The audit log records every change from what to what. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`size`	`string`, pattern ^[1-9][0-9]{0,3}gb$	Yes	The size, by its memory, such as 1gb or 2gb.
`machine`	`string`, e2-micro \| e2-small \| e2-medium \| e2-standard-2 \| e2-standard-4 \| e2-standard-8 \| e2-standard-16 \| e2-standard-32 \| e2-highmem-2 \| e2-highmem-4 \| e2-highmem-8 \| e2-highmem-16 \| e2-highcpu-8 \| e2-highcpu-16 \| e2-highcpu-32	No	The Google machine. Needed for a new size, such as e2-micro.
`listed`	`boolean`	No	Shown to customers and rentable. false by default for a new size.
`plan`	`string`	No	The plan this size is part of, such as pro: that plan's invoice credits this size. null takes it out.
`margin_floor`	`number`, min -1, max 1	No	The margin every price must clear (0.3 is 30%). Under 0 needs allow_loss=true.
`allow_loss`	`boolean`	No	Selling under cost, on purpose. The floor comes down as far as needed.
`regions`	`array<object>`, max items 20	No	Cost and prices per region. Only the regions given change.
`cost_source`	`string`, max length 200	No	Where the cost was measured, such as gcp list price asia-northeast3 2026-10. Empty is the operator address.

JSON Schema

{
  "type": "object",
  "properties": {
    "size": {
      "type": "string",
      "pattern": "^[1-9][0-9]{0,3}gb$",
      "description": "The size, by its memory, such as 1gb or 2gb."
    },
    "machine": {
      "type": "string",
      "enum": [
        "e2-micro",
        "e2-small",
        "e2-medium",
        "e2-standard-2",
        "e2-standard-4",
        "e2-standard-8",
        "e2-standard-16",
        "e2-standard-32",
        "e2-highmem-2",
        "e2-highmem-4",
        "e2-highmem-8",
        "e2-highmem-16",
        "e2-highcpu-8",
        "e2-highcpu-16",
        "e2-highcpu-32"
      ],
      "description": "The Google machine. Needed for a new size, such as e2-micro."
    },
    "listed": {
      "type": "boolean",
      "description": "Shown to customers and rentable. false by default for a new size."
    },
    "plan": {
      "type": [
        "string",
        "null"
      ],
      "description": "The plan this size is part of, such as pro: that plan's invoice credits this size. null takes it out."
    },
    "margin_floor": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "The margin every price must clear (0.3 is 30%). Under 0 needs allow_loss=true."
    },
    "allow_loss": {
      "type": "boolean",
      "description": "Selling under cost, on purpose. The floor comes down as far as needed."
    },
    "regions": {
      "type": "array",
      "maxItems": 20,
      "description": "Cost and prices per region. Only the regions given change.",
      "items": {
        "type": "object",
        "properties": {
          "region": {
            "type": "string",
            "pattern": "^[a-z]{2}-[a-z]+-[0-9]+$",
            "description": "The region code, such as kr-seoul-1. get_platform_server_pricing lists them under regions."
          },
          "machine_cost_usd": {
            "type": "number",
            "minimum": 0,
            "description": "The Google machine's monthly cost alone (USD, 730 hours at list price). What every server carries (disk, address, backups) is added from the region."
          },
          "usd": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "The customer's monthly price in dollars, to the cent, before tax. For example 39."
          },
          "krw": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "The customer's monthly price in won, VAT included. Empty is usd × krw_per_usd rounded up to ₩1,000."
          }
        },
        "required": [
          "region"
        ],
        "additionalProperties": false
      }
    },
    "cost_source": {
      "type": "string",
      "maxLength": 200,
      "description": "Where the cost was measured, such as gcp list price asia-northeast3 2026-10. Empty is the operator address."
    }
  },
  "required": [
    "size"
  ],
  "additionalProperties": false
}

`start_support_session` Start a support session

Destructive

Joins a customer's organisation as an owner so you can act for them when they ask for help. While it is open the organisation's projects show in list_projects, and every other tool (deploys, databases, domains, billing, the team, moving a project and the rest) works with the customer's own rights. A reason is required; the start and the end go to the customer's audit log with your address. 60 minutes by default, at most 480, and it ends by itself. Calling it again on an open session lengthens it. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`target`	`string`, max length 320	Yes	What finds the customer's organisation: a project ref, an organisation id, or the customer's email (when they own one organisation).
`reason`	`string`, min length 4, max length 500	Yes	Why you are going in, such as ticket #123 or a request to move a project. It goes to the customer's audit log.
`minutes`	`integer`, min 5, max 480	No	For how long. 60 when empty.

JSON Schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "maxLength": 320,
      "description": "What finds the customer's organisation: a project ref, an organisation id, or the customer's email (when they own one organisation)."
    },
    "reason": {
      "type": "string",
      "minLength": 4,
      "maxLength": 500,
      "description": "Why you are going in, such as ticket #123 or a request to move a project. It goes to the customer's audit log."
    },
    "minutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 480,
      "description": "For how long. 60 when empty."
    }
  },
  "required": [
    "target",
    "reason"
  ],
  "additionalProperties": false
}

`end_support_session` End a support session

Destructive

Ends a support session and leaves the owner seat in the customer's organisation. Give id or target. The end goes to the customer's audit log too. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`id`	`string`	No	The support session id. start_support_session and list_support_sessions return it.
`target`	`string`, max length 320	No	What finds the customer's organisation: a project ref, an organisation id, or the customer's email.

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The support session id. start_support_session and list_support_sessions return it."
    },
    "target": {
      "type": "string",
      "maxLength": 320,
      "description": "What finds the customer's organisation: a project ref, an organisation id, or the customer's email."
    }
  },
  "additionalProperties": false
}

`list_support_sessions` Support sessions

Read-only

Returns the open support sessions (every operator's) with the customer organisation, operator, reason and when each ends. With all=true, the last 50 ended ones too. Operators only.

Name	Description
Token scope	None
Roles	Any member of the organisation
Console assistant confirmation	Does not ask

Input

Name	Type	Required	Description
`all`	`boolean`	No	Ended sessions too. false by default.

JSON Schema

{
  "type": "object",
  "properties": {
    "all": {
      "type": "boolean",
      "description": "Ended sessions too. false by default."
    }
  },
  "additionalProperties": false
}

MCP server

Connecting

MCP address

Address options

Tool groups

Claude and ChatGPT

Claude Code

Connecting with a token

OAuth (ADR 0016)

Protocol

Supported methods

Documents and procedures

Tools

Account and regions

whoami My account

Input

list_regions Regions

Input

list_server_sizes Server sizes and prices

Input

request_region Request a region

Input

import_sources Import sources

Input

start_import Start an import

Input

get_import Import progress

Input

Projects

list_projects Projects

Input

create_project Create a project

Input

pause_project Pause a project

Input

resume_project Resume a project

Input

delete_project Delete a project

Input

retry_provisioning Retry a project that failed to set up

Input

rename_project Rename

Input

get_project_archive Database archive status

Input

restore_project_archive Restore an archived database

Input

create_archive_download_url Archive download address

Input

Keys and signing

get_project_keys Get API keys

Input

list_api_keys Named API keys

Input

create_api_key Create an API key

Input

revoke_api_key Revoke an API key

Input

get_jwt_signing Token signing

Input

set_jwt_signing Change token signing

Input

rotate_signing_key Rotate the key

Input

retire_signing_key Retire an old key

Input

Database

get_advisors Security and performance check

Input

list_tables Tables

Input

list_policies Access rules

Input

query_sql Query SQL (read-only)

Input

run_sql Run SQL (changes)

Input

read_rows Read a table

Input

export_table_csv Export a table as CSV

`whoami` My account

`list_regions` Regions

`list_server_sizes` Server sizes and prices

`request_region` Request a region

`import_sources` Import sources

`start_import` Start an import

`get_import` Import progress

`list_projects` Projects

`create_project` Create a project

`pause_project` Pause a project

`resume_project` Resume a project

`delete_project` Delete a project

`retry_provisioning` Retry a project that failed to set up

`rename_project` Rename

`get_project_archive` Database archive status

`restore_project_archive` Restore an archived database

`create_archive_download_url` Archive download address

`get_project_keys` Get API keys

`list_api_keys` Named API keys

`create_api_key` Create an API key

`revoke_api_key` Revoke an API key

`get_jwt_signing` Token signing

`set_jwt_signing` Change token signing

`rotate_signing_key` Rotate the key

`retire_signing_key` Retire an old key

`get_advisors` Security and performance check

`list_tables` Tables

`list_policies` Access rules

`query_sql` Query SQL (read-only)

`run_sql` Run SQL (changes)

`read_rows` Read a table

`export_table_csv` Export a table as CSV

`import_table_csv` Import CSV into a table

`get_database_connection` Database connection details

`reset_database_password` New database password

`list_extensions` Database extensions

`enable_extension` Turn on a database extension

`disable_extension` Turn off a database extension

`get_database_move` Move to a dedicated database: status

`move_to_dedicated_database` Move to a dedicated database

`get_dedicated_disk` Dedicated disk

`request_dedicated_disk` Move to a dedicated disk

`shrink_dedicated_disk` Make the disk smaller

`list_realtime_tables` Tables with realtime on

`set_realtime` Turn realtime on or off for a table

`list_migrations` Migration history

`apply_migrations` Apply migrations

`remove_migration_record` Remove a migration record

`dump_schema` The schema as SQL

`generate_typescript_types` Generate TypeScript types

`list_mysql_databases` List MySQL databases

`create_mysql_database` Create a MySQL database

`bind_mysql_database` Connect a MySQL database to an app

`delete_mysql_database` Delete a MySQL database

`get_mysql_connection` MySQL connection

`create_mysql_backup` Back up MySQL now

`list_mysql_backups` List MySQL backups

`restore_mysql_backup` Restore MySQL from a backup

`list_users` The service's users

`add_user` Add a user

`import_users` Import users

`update_user` Change a user

`generate_link` Make a sign-in link

`list_auth_providers` Social sign-in settings