Projects
Project (logical database) lifecycle.
AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
Postgres versions open for new databases.
application/json- response
The Postgres majors open for new databases, oldest first.
versions*array<>curl -X GET 'https://capydb.dev/api/capydb/v1/postgres-versions'{ "versions": [ { "channel": "previous", "default": true, "production_ready": true, "version": "17" } ]}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
organization_id?stringOrganization to list projects for (platform admins; org principals are always scoped to their own organization).
Projects.
application/json- response
projects*array<>curl -X GET 'https://capydb.dev/api/capydb/v1/projects'{ "projects": [ { "primary_instance_id": "string", "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "environment": "production", "id": "string", "idle_transaction_timeout": "string", "last_error": "string", "latest_job_id": "string", "max_connections": 0, "name": "string", "organization_id": "string", "plan": "string", "pooled_port": 0, "postgres_version": "string", "postgres_channel": "previous", "postgres_warning": "string", "public_host": "string", "region": "eu-north-1", "role_name": "string", "runtime_status": "active", "slug": "string", "ssl_mode": "string", "state": "provisioning", "statement_timeout": "string", "storage_limit_bytes": 0, "updated_at": "2019-08-24T14:15:22Z", "always_on": true } ]}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
application/json- body
environment?string"production""non_production"name*stringorganization_id?stringRequired only for platform admins acting on behalf of an organization.
postgres_version?stringPostgres major version for the new database (see GET /v1/postgres-versions). Omit for the default. 19 is a beta, accepted only while CapyDB offers it and not for production data. Immutable after creation; previews and restores inherit it.
"17""16""17""18""19"region?stringRegion to place the project in. Omit to let CapyDB pick a region with capacity. Region ids are CapyDB's own (eu-north-1); list them with GET /v1/regions. Deprecated: the former id hel1 is still accepted as an alias for eu-north-1 for one release and will then be rejected. An unknown region is a 400 that lists the valid ids.
slug?stringProject created; provisioning runs asynchronously via the returned job.
application/json- response
job*project*curl -X POST 'https://capydb.dev/api/capydb/v1/projects' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }, "project": { "primary_instance_id": "string", "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "environment": "production", "id": "string", "idle_transaction_timeout": "string", "last_error": "string", "latest_job_id": "string", "max_connections": 0, "name": "string", "organization_id": "string", "plan": "string", "pooled_port": 0, "postgres_version": "string", "postgres_channel": "previous", "postgres_warning": "string", "public_host": "string", "region": "eu-north-1", "role_name": "string", "runtime_status": "active", "slug": "string", "ssl_mode": "string", "state": "provisioning", "statement_timeout": "string", "storage_limit_bytes": 0, "updated_at": "2019-08-24T14:15:22Z", "always_on": true }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
The project.
application/json- response
project*curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string'{ "project": { "primary_instance_id": "string", "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "environment": "production", "id": "string", "idle_transaction_timeout": "string", "last_error": "string", "latest_job_id": "string", "max_connections": 0, "name": "string", "organization_id": "string", "plan": "string", "pooled_port": 0, "postgres_version": "string", "postgres_channel": "previous", "postgres_warning": "string", "public_host": "string", "region": "eu-north-1", "role_name": "string", "runtime_status": "active", "slug": "string", "ssl_mode": "string", "state": "provisioning", "statement_timeout": "string", "storage_limit_bytes": 0, "updated_at": "2019-08-24T14:15:22Z", "always_on": true }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
application/json- body
environment?|New environment label; null/omitted leaves it unchanged.
"production""non_production"nullalways_on?booleanExempt the project from the scale-to-zero idle sweep, or return it to sleeping when idle.
Updated project.
application/json- response
project*curl -X PATCH 'https://capydb.dev/api/capydb/v1/projects/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "project": { "primary_instance_id": "string", "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "environment": "production", "id": "string", "idle_transaction_timeout": "string", "last_error": "string", "latest_job_id": "string", "max_connections": 0, "name": "string", "organization_id": "string", "plan": "string", "pooled_port": 0, "postgres_version": "string", "postgres_channel": "previous", "postgres_warning": "string", "public_host": "string", "region": "eu-north-1", "role_name": "string", "runtime_status": "active", "slug": "string", "ssl_mode": "string", "state": "provisioning", "statement_timeout": "string", "storage_limit_bytes": 0, "updated_at": "2019-08-24T14:15:22Z", "always_on": true }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
approval_token?stringSingle-use approval token (action project.delete) required when deleting a production-environment project. Mint one via POST /v1/projects/{projectID}/approvals; tokens expire after 10 minutes.
Deletion job enqueued.
application/json- response
job*curl -X DELETE 'https://capydb.dev/api/capydb/v1/projects/string'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
application/json- body
action*stringThe destructive action this approval authorizes.
"project.delete""project.restore_overwrite""project.upgrade_major""project.upgrade_major_confirm""project.upgrade_major_rollback"Approval minted. The token appears only in this response.
application/json- response
approval*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/approvals' \ -H 'Content-Type: application/json' \ -d '{ "action": "project.delete"}'{ "approval": { "id": "string", "action": "string", "expires_at": "2019-08-24T14:15:22Z", "token": "string" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
Available extensions with enablement state.
application/json- response
extensions*array<>curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/extensions'{ "extensions": [ { "default_version": "string", "description": "string", "enabled": true, "name": "postgis", "requires_restart": true, "trusted": true, "installed_version": "string", "available_version": "string", "update_available": true, "category": "core" } ]}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
application/json- body
name*stringExtension name from the project's extension listing.
Extension enable job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/extensions' \ -H 'Content-Type: application/json' \ -d '{ "name": "postgis"}'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
name*stringPostgres extension name.
Extension disable job enqueued.
application/json- response
job*curl -X DELETE 'https://capydb.dev/api/capydb/v1/projects/string/extensions/string'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
name*stringPostgres extension name.
Extension update job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/extensions/string/update'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
force?booleanRestart even while sessions are active. Administrators only.
Minor upgrade job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/upgrade/minor'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
target_major*integerPostgreSQL major to evaluate, e.g. 18.
Major upgrade preflight job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/upgrade/major/preflight?target_major=0'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
Major upgrade status.
application/json- response
upgrade*|Null when no major upgrade is in flight.
curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/upgrade/major'{ "upgrade": { "created_at": "2019-08-24T14:15:22Z", "from_major": "17", "rollback_available_until": "2019-08-24T14:15:22Z", "state": "staging", "to_major": "18", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
target_major*integerPostgreSQL major to upgrade to, e.g. 18.
approval_token?stringSingle-use approval token (action project.upgrade_major), required unless the caller is a CapyDB platform administrator. Mint one via POST /v1/projects/{projectID}/approvals; tokens expire after 10 minutes. Presenting a token that already started an upgrade returns the job it started.
Major upgrade job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/upgrade/major?target_major=0'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
approval_token?stringSingle-use approval token (action project.upgrade_major_confirm), required unless the caller is a CapyDB platform administrator. Mint one via POST /v1/projects/{projectID}/approvals; tokens expire after 10 minutes. Presenting a token that already confirmed the upgrade returns the job it started.
Confirm job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/upgrade/major/confirm'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
approval_token?stringSingle-use approval token (action project.upgrade_major_rollback), required unless the caller is a CapyDB platform administrator. Mint one via POST /v1/projects/{projectID}/approvals; tokens expire after 10 minutes. Presenting a token that already rolled the upgrade back returns the job it started.
Rollback job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/upgrade/major/rollback'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
Provisioning job accepted (or the one already in flight).
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/retry-provisioning'{ "job": { "attempts": 0, "claimed_at": "2019-08-24T14:15:22Z", "claimed_by": "string", "host_id": "string", "instance_id": "string", "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "error": "string", "id": "string", "last_exit_code": 0, "last_stderr": "string", "last_stdout": "string", "locked_resource": "string", "max_attempts": 0, "organization_id": "string", "preview_database_id": "string", "project_id": "string", "result": null, "retry_classification": "string", "started_at": "2019-08-24T14:15:22Z", "state": "pending", "type": "project.apply_plan", "updated_at": "2019-08-24T14:15:22Z" }}