API reference

Databases

Serverless SQL databases with branches and restore to a point in time.

GET/v1/db/projects

List databases#

Credential: An API key or a dashboard session
Roles: Any role

Response

200object

projectsDatabase[]required
- namestringrequired
- hoststringrequired
- portintegerrequired
- pooled_portinteger
  the pooled port (transaction pooling), 6432
- databasestringrequired
  database name for branch main; <branch>--<name> for others
- userstringrequired
- history_hoursinteger
- max_connectionsinteger
- created_atstring (date-time)
- password_set_atstring (date-time)
- statusstring
  active: ran in the last 3 minutes; idle: scaled to zero, starts on the next connection
  one of active, idle, moving
- storage_change_pendingboolean
  a change to the database's storage waits for its next start; it keeps running meanwhile
- projectsConnected[]

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/db/projects" \
  -H "Authorization: Bearer $KEY"

POST/v1/db/projects

Create a database#

With branch main; the password is returned once.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Request body`application/json`

namestringrequired
one DNS label: lowercase letters, digits and hyphens, 1-63 characters, no --
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

201DatabaseWithPassword

namestringrequired
hoststringrequired
portintegerrequired
pooled_portinteger
the pooled port (transaction pooling), 6432
databasestringrequired
database name for branch main; <branch>--<name> for others
userstringrequired
history_hoursinteger
max_connectionsinteger
created_atstring (date-time)
password_set_atstring (date-time)
statusstring
active: ran in the last 3 minutes; idle: scaled to zero, starts on the next connection
one of active, idle, moving
storage_change_pendingboolean
a change to the database's storage waits for its next start; it keeps running meanwhile
projectsConnected[]
- namestringrequired
- kindstringrequired
  one of function, app
- environmentsstring[]required
- bindingsstring[]required
branchstring
passwordstringrequired
shown once
connection_stringstringrequired
pooled_connection_stringstring
the same database through the pooled port
notestring

Errors

Status	Description
400	Bad request: `bad_name`, `storage_refused`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `storage_not_found`
409	Conflict: `name_taken`, `storage_busy`, `has_branches`, `archived`
500	`internal`: an unexpected failure
502	Upstream failure: `storage_bad_answer`
503	Unavailable: `storage_unreachable`, `storage_unavailable`

Example

curl -X POST "https://api.ibel.ai/v1/db/projects" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"shop"}'

GET/v1/db/projects/{name}

Get a database#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Database

namestringrequired
hoststringrequired
portintegerrequired
pooled_portinteger
the pooled port (transaction pooling), 6432
databasestringrequired
database name for branch main; <branch>--<name> for others
userstringrequired
history_hoursinteger
max_connectionsinteger
created_atstring (date-time)
password_set_atstring (date-time)
statusstring
active: ran in the last 3 minutes; idle: scaled to zero, starts on the next connection
one of active, idle, moving
storage_change_pendingboolean
a change to the database's storage waits for its next start; it keeps running meanwhile
projectsConnected[]
- namestringrequired
- kindstringrequired
  one of function, app
- environmentsstring[]required
- bindingsstring[]required

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/db/projects/shop" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/db/projects/{name}

Delete a database#

With all its branches and history. Refused while a live version binds it (checked after the role and the name).

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Deleted

namestring
deletedbooleanrequired

Errors

Status	Description
400	Bad request: `storage_refused`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`, `storage_not_found`
409	Conflict: `bound`, `storage_busy`, `has_branches`, `archived`
500	`internal`: an unexpected failure
502	Upstream failure: `storage_bad_answer`
503	Unavailable: `storage_unreachable`, `storage_unavailable`

Example

curl -X DELETE "https://api.ibel.ai/v1/db/projects/shop" \
  -H "Authorization: Bearer $KEY"

POST/v1/db/projects/{name}/password

New password#

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200DatabaseWithPassword

namestringrequired
hoststringrequired
portintegerrequired
pooled_portinteger
the pooled port (transaction pooling), 6432
databasestringrequired
database name for branch main; <branch>--<name> for others
userstringrequired
history_hoursinteger
max_connectionsinteger
created_atstring (date-time)
password_set_atstring (date-time)
statusstring
active: ran in the last 3 minutes; idle: scaled to zero, starts on the next connection
one of active, idle, moving
storage_change_pendingboolean
a change to the database's storage waits for its next start; it keeps running meanwhile
projectsConnected[]
- namestringrequired
- kindstringrequired
  one of function, app
- environmentsstring[]required
- bindingsstring[]required
branchstring
passwordstringrequired
shown once
connection_stringstringrequired
pooled_connection_stringstring
the same database through the pooled port
notestring

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/db/projects/shop/password" \
  -H "Authorization: Bearer $KEY"

GET/v1/db/projects/{name}/branches

List branches#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

branchesBranch[]required
- namestringrequired
- kindstringrequired
  one of branch, preview, backup
- previewstring
- backup_atstring (date-time)
- history_idstring
  the id of the branch's current history; a restore gives it a new one
  pattern ^[0-9a-f]{32}$
- parentstring | nullrequired
- branch_lsnstring | null
  a position in the database history, e.g. 0/1FA2728
  pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
- branch_timestring (date-time) | null
- created_atstring (date-time)required
- restored_atstring (date-time) | null
- head_lsnstring
  a position in the database history, e.g. 0/1FA2728
  pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
- size_bytesinteger | null
  the branch's data size, history apart
storagestring
one of unavailable

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/db/projects/shop/branches" \
  -H "Authorization: Bearer $KEY"

POST/v1/db/projects/{name}/branches

Make a branch#

From from (default main) at at, at lsn, or at its latest state. At most 50 branches and previews.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

namestringrequired
one DNS label: lowercase letters, digits and hyphens, 1-63 characters, no --
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
fromstring
parent branch, default main
atstring (date-time)
RFC 3339 time with a zone, e.g. 2026-11-04T09:30:00Z
lsnstring
a position in the database history, e.g. 0/1FA2728
pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$

Response

201Branch

namestringrequired
kindstringrequired
one of branch, preview, backup
previewstring
backup_atstring (date-time)
history_idstring
the id of the branch's current history; a restore gives it a new one
pattern ^[0-9a-f]{32}$
parentstring | nullrequired
branch_lsnstring | null
a position in the database history, e.g. 0/1FA2728
pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
branch_timestring (date-time) | null
created_atstring (date-time)required
restored_atstring (date-time) | null
head_lsnstring
a position in the database history, e.g. 0/1FA2728
pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
size_bytesinteger | null
the branch's data size, history apart

Errors

Status	Description
400	Bad request: `bad_name`, `reserved_name`, `bad_from`, `bad_point`, `bad_time`, `time_in_future`, `bad_lsn`, `too_old`, `before_branch`, `lsn_ahead`, `too_new`, `no_data`, `storage_refused`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`, `storage_not_found`
409	Conflict: `name_taken`, `too_many_branches`, `storage_busy`, `has_branches`, `archived`
500	`internal`: an unexpected failure
502	Upstream failure: `storage_bad_answer`
503	Unavailable: `storage_unreachable`, `storage_unavailable`

Example

curl -X POST "https://api.ibel.ai/v1/db/projects/shop/branches" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"shop"}'

POST/v1/db/projects/{name}/branches/{branch}/restore

Restore a branch to a point in time#

The state before is kept as the backup branch <branch>-before-<time>; the restored branch is then detached from it (detached), so the backup can be deleted. At most 20 backups.

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
branchstringpathrequired
the branch's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

one of at or lsn

atstring (date-time)
RFC 3339 time with a zone, e.g. 2026-11-04T09:30:00Z
lsnstring
a position in the database history, e.g. 0/1FA2728
pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$

Response

200Restored

branchBranchrequired
- namestringrequired
- kindstringrequired
  one of branch, preview, backup
- previewstring
- backup_atstring (date-time)
- history_idstring
  the id of the branch's current history; a restore gives it a new one
  pattern ^[0-9a-f]{32}$
- parentstring | nullrequired
- branch_lsnstring | null
  a position in the database history, e.g. 0/1FA2728
  pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
- branch_timestring (date-time) | null
- created_atstring (date-time)required
- restored_atstring (date-time) | null
- head_lsnstring
  a position in the database history, e.g. 0/1FA2728
  pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
- size_bytesinteger | null
  the branch's data size, history apart
backupBranchrequired
- namestringrequired
- kindstringrequired
  one of branch, preview, backup
- previewstring
- backup_atstring (date-time)
- history_idstring
  the id of the branch's current history; a restore gives it a new one
  pattern ^[0-9a-f]{32}$
- parentstring | nullrequired
- branch_lsnstring | null
  a position in the database history, e.g. 0/1FA2728
  pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
- branch_timestring (date-time) | null
- created_atstring (date-time)required
- restored_atstring (date-time) | null
- head_lsnstring
  a position in the database history, e.g. 0/1FA2728
  pattern ^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$
- size_bytesinteger | null
  the branch's data size, history apart
detachedbooleanrequired

Errors

Status	Description
400	Bad request: `bad_point`, `bad_time`, `time_in_future`, `bad_lsn`, `too_old`, `before_branch`, `lsn_ahead`, `too_new`, `no_data`, `storage_refused`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`, `storage_not_found`
409	Conflict: `backup_branch`, `too_many_backups`, `storage_busy`, `has_branches`, `archived`
500	`internal`: an unexpected failure
502	Upstream failure: `storage_bad_answer`
503	Unavailable: `storage_unreachable`, `storage_unavailable`

Example

curl -X POST "https://api.ibel.ai/v1/db/projects/shop/branches/dev/restore" \
  -H "Authorization: Bearer $KEY" \
  -d '{"at":"2026-11-04T09:30:00Z","lsn":"…"}'

DELETE/v1/db/projects/{name}/branches/{branch}

Delete a branch#

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
branchstringpathrequired
the branch's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Deleted

namestring
deletedbooleanrequired

Errors

Status	Description
400	Bad request: `storage_refused`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`, `storage_not_found`
409	Conflict: `main_branch`, `in_use`, `has_branches`, `storage_busy`, `archived`
500	`internal`: an unexpected failure
502	Upstream failure: `storage_bad_answer`
503	Unavailable: `storage_unreachable`, `storage_unavailable`

Example

curl -X DELETE "https://api.ibel.ai/v1/db/projects/shop/branches/dev" \
  -H "Authorization: Bearer $KEY"

GET/v1/db/projects/{name}/observability

Compute, size, connections, top statements#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
rangestringquery
1h (1-minute steps), 24h (15 minutes) or 7d (2 hours); any other value is 400 bad_range
one of 1h, 24h, 7d · default "1h"

Response

200ResourceObservability

rangestringrequired
stepstringrequired
totalsobjectrequired
metricsobject[]required
- keystringrequired
- labelstringrequired
- unitstringrequired
seriesobject[]required
- tstring (date-time)
tablesobject[]
databases only: the latest top statements
- keystring
- labelstring
- sampled_atstring (date-time)
- columnsobject[]
- rowsobject[]
notestring

Errors

Status	Description
400	Bad request: `bad_range`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/db/projects/shop/observability" \
  -H "Authorization: Bearer $KEY"

List databases#

Response

Errors

Example

Create a database#

Request bodyapplication/json

Response

Errors

Example

Get a database#

Parameters

Response

Errors

Example

Delete a database#

Parameters

Response

Errors

Example

New password#

Parameters

Response

Errors

Example

List branches#

Parameters

Response

Errors

Example

Make a branch#

Parameters

Request bodyapplication/json

Response

Errors

Example

Restore a branch to a point in time#

Parameters

Request bodyapplication/json

Response

Errors

Example

Delete a branch#

Parameters

Response

Errors

Example

Compute, size, connections, top statements#

Parameters

Response

Errors

Example

Request body`application/json`

Request body`application/json`

Request body`application/json`