Previews
Disposable preview/branch databases.
AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
projectID*stringProject id.
Preview databases.
application/json- response
preview_databases*array<>curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/preview-databases'{ "preview_databases": [ { "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "id": "string", "last_error": "string", "mode": "empty", "name": "string", "pooled_port": 0, "project_id": "string", "public_host": "string", "role_name": "string", "source_backup_key": "string", "source_database": "string", "source_kind": "backup", "source_restore_time": "2019-08-24T14:15:22Z", "ssl_mode": "string", "state": "string", "ttl_expires_at": "2019-08-24T14:15:22Z", "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
mode?stringData source mode for the preview (e.g. empty, clone).
"empty""clone"name?stringttl_hours?integerTime to live in hours before the preview expires.
Preview database created; provisioning runs asynchronously via the returned job.
application/json- response
job*preview*curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/preview-databases' \ -H 'Content-Type: application/json' \ -d '{}'{ "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" }, "preview": { "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "id": "string", "last_error": "string", "mode": "empty", "name": "string", "pooled_port": 0, "project_id": "string", "public_host": "string", "role_name": "string", "source_backup_key": "string", "source_database": "string", "source_kind": "backup", "source_restore_time": "2019-08-24T14:15:22Z", "ssl_mode": "string", "state": "string", "ttl_expires_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
previewID*stringPreview database id.
Deletion job enqueued.
application/json- response
job*curl -X DELETE 'https://capydb.dev/api/capydb/v1/preview-databases/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.
previewID*stringPreview database id.
Reset job enqueued.
application/json- response
job*curl -X POST 'https://capydb.dev/api/capydb/v1/preview-databases/string/reset'{ "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.
previewID*stringPreview database id.
application/json- body
ttl_hours*integerNew TTL window in hours measured from now (not added to the time remaining). Clamped server-side to 1..168.
Updated preview database.
application/json- response
preview*curl -X POST 'https://capydb.dev/api/capydb/v1/preview-databases/string/extend' \ -H 'Content-Type: application/json' \ -d '{ "ttl_hours": 0}'{ "preview": { "created_at": "2019-08-24T14:15:22Z", "database_name": "string", "direct_port": 0, "id": "string", "last_error": "string", "mode": "empty", "name": "string", "pooled_port": 0, "project_id": "string", "public_host": "string", "role_name": "string", "source_backup_key": "string", "source_database": "string", "source_kind": "backup", "source_restore_time": "2019-08-24T14:15:22Z", "ssl_mode": "string", "state": "string", "ttl_expires_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
previewID*stringPreview database id.
application/json- body
allow_unqualified_writes?booleanPermit statements the destructive-statement guard would otherwise refuse: an UPDATE or DELETE with no top-level WHERE (including one in a WITH clause), a MERGE that updates or deletes rows its join does not scope (ON TRUE, or WHEN NOT MATCHED BY SOURCE with no AND condition), and TRUNCATE. Defaults to false, so callers are guarded unless they opt out. Intended for an interactive console where a person has already expressed intent; automated and agent callers should leave it unset.
max_rows?integerRow cap for the result (default 200, max 1000).
query*stringSQL statement to execute.
read_only?booleanRun the statement inside a READ ONLY transaction so the server itself refuses every write (DML, DDL, TRUNCATE, SELECT INTO, sequence advancement) with SQLSTATE 25006, surfaced as a 400 carrying the refusal. Executor-proven, unlike client-side statement inspection. Defaults to false; agent callers exploring data should set it to true.
Query result.
application/json- response
result*curl -X POST 'https://capydb.dev/api/capydb/v1/preview-databases/string/sql' \ -H 'Content-Type: application/json' \ -d '{ "query": "string"}'{ "result": { "columns": [ "string" ], "duration_ms": 0, "rows": [ {} ], "row_count": 0, "truncated": true }}AuthorizationBearer <token>Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.
previewID*stringPreview database id.
Lint report.
application/json- response
lint*curl -X GET 'https://capydb.dev/api/capydb/v1/preview-databases/string/lint'{ "lint": { "findings": [ { "fix": "string", "message": "string", "object": "string", "rule": "missing_primary_key", "severity": "warning" } ], "skipped": [ "string" ] }}K V
Key-value stores and rate limiting - CapyDB Knight/Valkyrie ("K/V"). One store per project, in its own KV cell; Upstash-REST and RESP compatible.
Ephemeral
Ephemeral databases: a throwaway Postgres database created without an account, destroyed after 72 hours unless it is claimed into an organization.