مرجع API

دیتابیس

دیتابیس SQL بدون سرور با شاخه و بازگردانی به یک لحظه.

توضیح هر مسیر به انگلیسی است، همان متنی که مرجع از کد ساخته می‌شود. مسیرها، نام فیلدها و کدها همان‌اند که در درخواست می‌نویسید.

GET/v1/db/projects

List databases#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پاسخ

200object

projectsDatabase[]الزامی
- namestringالزامی
- hoststringالزامی
- portintegerالزامی
- pooled_portinteger
  the pooled port (transaction pooling), 6432
- databasestringالزامی
  database name for branch main; <branch>--<name> for others
- userstringالزامی
- 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[]

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

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.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، توسعه‌دهنده

بدنهٔ درخواست`application/json`

namestringالزامی
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

پاسخ

201DatabaseWithPassword

namestringالزامی
hoststringالزامی
portintegerالزامی
pooled_portinteger
the pooled port (transaction pooling), 6432
databasestringالزامی
database name for branch main; <branch>--<name> for others
userstringالزامی
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[]
- namestringالزامی
- kindstringالزامی
  one of function, app
- environmentsstring[]الزامی
- bindingsstring[]الزامی
branchstring
passwordstringالزامی
shown once
connection_stringstringالزامی
pooled_connection_stringstring
the same database through the pooled port
notestring

خطاها

وضعیت	توضیح
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`

نمونه

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#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

پاسخ

200Database

namestringالزامی
hoststringالزامی
portintegerالزامی
pooled_portinteger
the pooled port (transaction pooling), 6432
databasestringالزامی
database name for branch main; <branch>--<name> for others
userstringالزامی
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[]
- namestringالزامی
- kindstringالزامی
  one of function, app
- environmentsstring[]الزامی
- bindingsstring[]الزامی

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

نمونه

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

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، توسعه‌دهنده
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

پاسخ

200Deleted

namestring
deletedbooleanالزامی

خطاها

وضعیت	توضیح
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`

نمونه

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

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

New password#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، توسعه‌دهنده
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

پاسخ

200DatabaseWithPassword

namestringالزامی
hoststringالزامی
portintegerالزامی
pooled_portinteger
the pooled port (transaction pooling), 6432
databasestringالزامی
database name for branch main; <branch>--<name> for others
userstringالزامی
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[]
- namestringالزامی
- kindstringالزامی
  one of function, app
- environmentsstring[]الزامی
- bindingsstring[]الزامی
branchstring
passwordstringالزامی
shown once
connection_stringstringالزامی
pooled_connection_stringstring
the same database through the pooled port
notestring

خطاها

وضعیت	توضیح
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

نمونه

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

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

List branches#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

پاسخ

200object

branchesBranch[]الزامی
- namestringالزامی
- kindstringالزامی
  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 | nullالزامی
- 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)الزامی
- 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

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

نمونه

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.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، توسعه‌دهنده

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

بدنهٔ درخواست`application/json`

namestringالزامی
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}$

پاسخ

201Branch

namestringالزامی
kindstringالزامی
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 | nullالزامی
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)الزامی
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

خطاها

وضعیت	توضیح
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`

نمونه

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.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، توسعه‌دهنده
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
branchstringمسیرالزامی
the branch's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

بدنهٔ درخواست`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}$

پاسخ

200Restored

branchBranchالزامی
- namestringالزامی
- kindstringالزامی
  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 | nullالزامی
- 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)الزامی
- 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
backupBranchالزامی
- namestringالزامی
- kindstringالزامی
  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 | nullالزامی
- 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)الزامی
- 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
detachedbooleanالزامی

خطاها

وضعیت	توضیح
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`

نمونه

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#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، توسعه‌دهنده
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
branchstringمسیرالزامی
the branch's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

پاسخ

200Deleted

namestring
deletedbooleanالزامی

خطاها

وضعیت	توضیح
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`

نمونه

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#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پارامترها

namestringمسیرالزامی
the database's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
rangestringکوئری
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"

پاسخ

200ResourceObservability

rangestringالزامی
stepstringالزامی
totalsobjectالزامی
metricsobject[]الزامی
- keystringالزامی
- labelstringالزامی
- unitstringالزامی
seriesobject[]الزامی
- tstring (date-time)
tablesobject[]
databases only: the latest top statements
- keystring
- labelstring
- sampled_atstring (date-time)
- columnsobject[]
- rowsobject[]
notestring

خطاها

وضعیت	توضیح
400	Bad request: `bad_range`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

نمونه

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

List databases#

پاسخ

خطاها

نمونه

Create a database#

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

Get a database#

پارامترها

پاسخ

خطاها

نمونه

Delete a database#

پارامترها

پاسخ

خطاها

نمونه

New password#

پارامترها

پاسخ

خطاها

نمونه

List branches#

پارامترها

پاسخ

خطاها

نمونه

Make a branch#

پارامترها

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

Restore a branch to a point in time#

پارامترها

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

Delete a branch#

پارامترها

پاسخ

خطاها

نمونه

Compute, size, connections, top statements#

پارامترها

پاسخ

خطاها

نمونه

بدنهٔ درخواست`application/json`

بدنهٔ درخواست`application/json`

بدنهٔ درخواست`application/json`