CapyDB
Start free
CapyDB/ docs
ReferenceAPI

Studio

SQL console and table data browser/editor.

All docs

Run a SQL query

POST
/v1/projects/{projectID}/sql

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Request Body

application/json
  1. body
allow_unqualified_writes?boolean

Permit 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?integer

Row cap for the result (default 200, max 1000).

query*string

SQL statement to execute.

read_only?boolean

Run 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.

Response Body

Query result.

application/json
  1. response
result*
curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/sql' \  -H 'Content-Type: application/json' \  -d '{  "query": "string"}'
{  "result": {    "columns": [      "string"    ],    "duration_ms": 0,    "rows": [      {}    ],    "row_count": 0,    "truncated": true  }}

List tables

GET
/v1/projects/{projectID}/tables

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Response Body

Tables.

application/json
  1. response
tables*array<>
curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/tables'
{  "tables": [    {      "schema": "string",      "table": "string",      "type": "string"    }  ]}

List table rows

GET
/v1/projects/{projectID}/tables/{schema}/{table}/rows

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

schema*string

Database schema name.

table*string

Table name.

Query Parameters

limit?integer

Maximum number of rows to return.

Range0 <= value

Response Body

Table rows.

application/json
  1. response
result*
curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/tables/string/string/rows'
{  "result": {    "columns": [      "string"    ],    "rows": [      {}    ]  }}

Insert a table row

POST
/v1/projects/{projectID}/tables/{schema}/{table}/rows

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

schema*string

Database schema name.

table*string

Table name.

Request Body

application/json
  1. body
primary_key?

Addresses the row(s) for update/delete: column name to value.

values?

Column values to insert or set.

Response Body

Row inserted.

application/json
  1. response
result*
curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/tables/string/string/rows' \  -H 'Content-Type: application/json' \  -d '{}'
{  "result": {    "rows_affected": 0,    "rows": [      {}    ]  }}

Update table rows

PATCH
/v1/projects/{projectID}/tables/{schema}/{table}/rows

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

schema*string

Database schema name.

table*string

Table name.

Request Body

application/json
  1. body
primary_key?

Addresses the row(s) for update/delete: column name to value.

values?

Column values to insert or set.

Response Body

Rows updated.

application/json
  1. response
result*
curl -X PATCH 'https://capydb.dev/api/capydb/v1/projects/string/tables/string/string/rows' \  -H 'Content-Type: application/json' \  -d '{}'
{  "result": {    "rows_affected": 0,    "rows": [      {}    ]  }}

Delete table rows

DELETE
/v1/projects/{projectID}/tables/{schema}/{table}/rows

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

schema*string

Database schema name.

table*string

Table name.

Request Body

application/json
  1. body
primary_key?

Addresses the row(s) for update/delete: column name to value.

values?

Column values to insert or set.

Response Body

Rows deleted.

application/json
  1. response
result*
curl -X DELETE 'https://capydb.dev/api/capydb/v1/projects/string/tables/string/string/rows' \  -H 'Content-Type: application/json' \  -d '{}'
{  "result": {    "rows_affected": 0,    "rows": [      {}    ]  }}

List table columns

GET
/v1/projects/{projectID}/tables/{schema}/{table}/columns

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

schema*string

Database schema name.

table*string

Table name.

Response Body

Column metadata.

application/json
  1. response
columns*array<>
curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/tables/string/string/columns'
{  "columns": [    {      "data_type": "string",      "default": "string",      "is_nullable": true,      "is_primary_key": true,      "name": "string",      "position": 0    }  ]}

List SQL history

GET
/v1/projects/{projectID}/sql/history

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Query Parameters

limit?integer

Maximum number of history entries to return (default 50).

Range0 <= value
Default50

Response Body

SQL execution history.

application/json
  1. response
history*array<>
curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/sql/history'
{  "history": [    {      "actor_id": "string",      "actor_kind": "string",      "created_at": "2019-08-24T14:15:22Z",      "duration_ms": 0,      "error": "string",      "id": "string",      "organization_id": "string",      "project_id": "string",      "query": "string",      "row_count": 0,      "success": true    }  ]}

Get AI query usage

GET
/v1/projects/{projectID}/ai-usage

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Response Body

Current AI query usage.

application/json
  1. response
usage*
curl -X GET 'https://capydb.dev/api/capydb/v1/projects/string/ai-usage'
{  "usage": {    "used": 0,    "limit": 0,    "remaining": 0,    "soft_cap_reached": true,    "period_start": "2019-08-24T14:15:22Z",    "period_end": "2019-08-24T14:15:22Z"  }}

Record an AI query

POST
/v1/projects/{projectID}/ai-usage

Authorization

headerAuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

Path Parameters

projectID*string

Project id.

Response Body

Updated AI query usage.

application/json
  1. response
usage*
curl -X POST 'https://capydb.dev/api/capydb/v1/projects/string/ai-usage'
{  "usage": {    "used": 0,    "limit": 0,    "remaining": 0,    "soft_cap_reached": true,    "period_start": "2019-08-24T14:15:22Z",    "period_end": "2019-08-24T14:15:22Z"  }}

Organizations

Organization profile and billing metadata.

Observability

Live database metrics for a project.