Skip to content
cloudhostDocs
API reference

Projects

A project holds an app's parts: its apps and functions, SQL databases, caches, buckets, queues, flags and secrets, with environments (production, development, a preview per branch). Names are unique within a project; every resource's routes sit under its project, /v1/projects/{project}/..., and each product has a team list with ?project=.

GET/v1/projects

List the team's projects#

With the number of apps, functions and resources in each.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • any

Response

200object

  • projectsProjectSummary[]required
    • idstringrequired
    • namestringrequired
    • created_atstring (date-time)
    • appsintegerrequired
    • functionsintegerrequired
    • resourcesintegerrequired

      its SQL databases, caches, buckets and queues

  • next_cursorstring | null

    send as cursor for the next page; null on the last page

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
500internal: an unexpected failure

Example

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

Create a project#

Made with its production environment and its own secrets (D191).

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

Request bodyapplication/json

  • namestringrequired

    lowercase letters, digits and single hyphens, 1-63 characters; unique in the team, whatever its case

Response

201ProjectSummary

  • idstringrequired
  • namestringrequired
  • created_atstring (date-time)
  • appsintegerrequired
  • functionsintegerrequired
  • resourcesintegerrequired

    its SQL databases, caches, buckets and queues

  • environmentsstring[]

Errors

StatusDescription
400Bad request: bad_name, bad_json
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden
409Conflict: name_taken
500internal: an unexpected failure

Example

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

Get a project and what it holds#

Its apps, functions and resources, and the other projects' resources connected to it.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any

Response

200ProjectDetail

  • idstringrequired
  • namestringrequired
  • created_atstring (date-time)
  • appsobject[]required
  • functionsobject[]required
  • databasesResourceRef[]required
  • cachesResourceRef[]required
  • bucketsResourceRef[]required
  • queuesResourceRef[]required
  • connectionsobject[]required

    other projects' resources this project uses, each with its owner

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api" \
  -H "Authorization: Bearer $KEY"
DELETE/v1/projects/{project}

Delete an empty project#

Refused while it holds anything (delete or move it first) or while one of its resources is connected to another project.

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

  • any

Response

200object

  • idstring
  • namestring
  • deletedbooleanrequired

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden, step_up_required
404Not found: not_found
409Conflict: not_empty, connected, has_deleted_items
500internal: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/projects/my-api" \
  -H "Authorization: Bearer $KEY"
PATCH/v1/projects/{project}

Rename a project#

Its id, contents and addresses stay.

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

Parameters

  • any

Request bodyapplication/json

  • namestringrequired

Response

200object

  • idstring
  • namestring
  • created_atstring (date-time)

Errors

StatusDescription
400Bad request: bad_name
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden
404Not found: not_found
409Conflict: name_taken
500internal: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/projects/my-api" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"my-api"}'
GET/v1/projects/{project}/members

Who may use a project#

The team's unlimited members, and limited members through a grant on the project (their own or a group's). A grant on a project reaches everything in it.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • any
  • any

Response

200ResourceMembers

  • resourceobject
  • teamobject[]
  • limitedobject[]
  • next_cursorstring | null

    send as cursor for the next page; null on the last page

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api/members" \
  -H "Authorization: Bearer $KEY"
GET/v1/projects/{project}/usage

A project's usage and cost#

Every app's, function's and resource's meters at list price, with their environment instances, summed.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • daysintegerquery

    1–90 · default 30

Response

200ProjectUsage

  • projectProjectRefrequired
  • daysintegerrequired
  • fromstring (date-time)
  • tostring (date-time)
  • per_environmentboolean
  • list_rialsintegerrequired
  • itemsobject[]required
  • notestring

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api/usage" \
  -H "Authorization: Bearer $KEY"
GET/v1/projects/{project}/environments

List a project's environments#

production, development once used, and each live or kept preview, with its addresses and the instance of each resource it uses.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • any
  • any

Response

200object

  • environmentsEnvironment[]required
    • namestringrequired

      production, development or preview-<label>

    • kindstringrequired

      one of production, development, preview

    • keptboolean

      a preview kept past its branch (staging); previews only

    • created_atstring (date-time) | null
    • last_used_atstring (date-time) | null
    • addressesstring[]required
    • instancesobjectrequired
  • next_cursorstring | null

    send as cursor for the next page; null on the last page

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api/environments" \
  -H "Authorization: Bearer $KEY"
GET/v1/projects/{project}/environments/{environment}

Get an environment#

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • environmentstringpathrequired

    production, development or preview-<label>

Response

200Environment

  • namestringrequired

    production, development or preview-<label>

  • kindstringrequired

    one of production, development, preview

  • keptboolean

    a preview kept past its branch (staging); previews only

  • created_atstring (date-time) | null
  • last_used_atstring (date-time) | null
  • addressesstring[]required
  • instancesobjectrequired

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api/environments/environment" \
  -H "Authorization: Bearer $KEY"
DELETE/v1/projects/{project}/environments/{environment}

Delete a preview#

Its addresses, its caches and queues, and its database branches.

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

Parameters

  • any
  • environmentstringpathrequired

    production, development or preview-<label>

Response

200object

  • namestringrequired
  • deletedbooleanrequired
  • database_branchesstring[]
  • cachesstring[]
  • queuesstring[]

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden
404Not found: not_found
409Conflict: not_a_preview
500internal: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/projects/my-api/environments/environment" \
  -H "Authorization: Bearer $KEY"
PATCH/v1/projects/{project}/environments/{environment}

Keep a preview, or let it expire#

A kept preview stays after its branch is merged or deleted, and is not deleted when idle (staging).

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

Parameters

  • any
  • environmentstringpathrequired

    production, development or preview-<label>

Request bodyapplication/json

  • keptbooleanrequired

Response

200Environment

  • namestringrequired

    production, development or preview-<label>

  • kindstringrequired

    one of production, development, preview

  • keptboolean

    a preview kept past its branch (staging); previews only

  • created_atstring (date-time) | null
  • last_used_atstring (date-time) | null
  • addressesstring[]required
  • instancesobjectrequired

Errors

StatusDescription
400Bad request: bad_kept
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden
404Not found: not_found
409Conflict: not_a_preview
500internal: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/projects/my-api/environments/environment" \
  -H "Authorization: Bearer $KEY" \
  -d '{"kept":true}'
POST/v1/projects/{project}/environments/development/reset

Reset development#

Each SQL database's development branch made again from main, and development's caches and queues emptied. The preview bucket it shares stays.

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

Parameters

  • any

Response

200object

  • environmentstringrequired
  • databasesobject[]required
  • cachesstring[]
  • queuesstring[]

Errors

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

Example

curl -X POST "https://api.ibel.ai/v1/projects/my-api/environments/development/reset" \
  -H "Authorization: Bearer $KEY"
GET/v1/deleted

The team's deleted items#

Functions, apps, databases, caches and queues deleted in the last 7 days, across the team's projects (?project= for one), newest first. Each is switched off and unreachable, its name reserved, until it is restored or the purge job removes it.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • kindstringquery

    only this kind's (functions, apps, databases, caches, queues)

  • limitintegerquery

    1–500 · default 100

  • cursorstringquery

    the next_cursor of the page before

Response

200DeletedItemList

  • itemsDeletedItem[]required
    • idstringrequired

      its id, as before it was deleted

    • kindstringrequired

      one of function, app, database, cache, queue

    • namestringrequired
    • projectProjectRefrequired
    • deleted_atstring (date-time)required
    • deleted_bystringrequired

      person:<id> or key:<id>, as in the audit log

    • purge_afterstring (date-time)required

      when the purge job removes it for good (7 days after deleted_at)

    • stored_bytesinteger | nullrequired

      the stored data that bills while it waits (a database's, a cache's), last measured; null for apps, functions and queues

  • next_cursorstring | nullrequired

    send as cursor for the next page; null on the last page

Errors

StatusDescription
400Bad request: bad_kind, bad_param, bad_cursor
401unauthorized: missing, invalid, expired or revoked credential
404Not found: not_found
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/deleted" \
  -H "Authorization: Bearer $KEY"
GET/v1/projects/{project}/deleted

A project's deleted items#

Its functions, apps, databases, caches and queues deleted in the last 7 days, newest first.

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • kindstringquery

    only this kind's (functions, apps, databases, caches, queues)

  • limitintegerquery

    1–500 · default 100

  • cursorstringquery

    the next_cursor of the page before

Response

200DeletedItemList

  • itemsDeletedItem[]required
    • idstringrequired

      its id, as before it was deleted

    • kindstringrequired

      one of function, app, database, cache, queue

    • namestringrequired
    • projectProjectRefrequired
    • deleted_atstring (date-time)required
    • deleted_bystringrequired

      person:<id> or key:<id>, as in the audit log

    • purge_afterstring (date-time)required

      when the purge job removes it for good (7 days after deleted_at)

    • stored_bytesinteger | nullrequired

      the stored data that bills while it waits (a database's, a cache's), last measured; null for apps, functions and queues

  • next_cursorstring | nullrequired

    send as cursor for the next page; null on the last page

Errors

StatusDescription
400Bad request: bad_kind, bad_param, bad_cursor
401unauthorized: missing, invalid, expired or revoked credential
404Not found: not_found
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/projects/my-api/deleted" \
  -H "Authorization: Bearer $KEY"
GET/v1/projects/{project}/deleted/{kind}/{name}

A deleted item#

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • kindstringpathrequired

    functions, apps, databases, caches or queues

    one of functions, apps, databases, caches, queues

  • namestringpathrequired

    the deleted item's name (any case) or its id

Response

200DeletedItem

  • idstringrequired

    its id, as before it was deleted

  • kindstringrequired

    one of function, app, database, cache, queue

  • namestringrequired
  • projectProjectRefrequired
  • deleted_atstring (date-time)required
  • deleted_bystringrequired

    person:<id> or key:<id>, as in the audit log

  • purge_afterstring (date-time)required

    when the purge job removes it for good (7 days after deleted_at)

  • stored_bytesinteger | nullrequired

    the stored data that bills while it waits (a database's, a cache's), last measured; null for apps, functions and queues

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api/deleted/kind/my-api" \
  -H "Authorization: Bearer $KEY"
DELETE/v1/projects/{project}/deleted/{kind}/{name}

Delete a deleted item now#

Removes it for good without waiting for the purge job: its data and history are erased and it cannot be restored.

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

  • any
  • kindstringpathrequired

    functions, apps, databases, caches or queues

    one of functions, apps, databases, caches, queues

  • namestringpathrequired

    the deleted item's name (any case) or its id

Response

200object

  • idstringrequired
  • kindstringrequired
  • namestringrequired
  • deletedbooleanrequired
  • purgedbooleanrequired

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/projects/my-api/deleted/kind/my-api" \
  -H "Authorization: Bearer $KEY"
POST/v1/projects/{project}/deleted/{kind}/{name}/restore

Restore a deleted item#

Puts it back, switched on, under its own name and address, with its data, versions, variables, credentials and settings. Its name stayed reserved, so 409 name_taken cannot normally happen; when it does, or when an app's or function's address is in use (409 address_taken), the item stays in deleted items and nothing is renamed or overwritten. A plan that now allows fewer of them is refused as on create.

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

Parameters

  • any
  • kindstringpathrequired

    functions, apps, databases, caches or queues

    one of functions, apps, databases, caches, queues

  • namestringpathrequired

    the deleted item's name (any case) or its id

Response

200DeletedItem

  • idstringrequired

    its id, as before it was deleted

  • kindstringrequired

    one of function, app, database, cache, queue

  • namestringrequired
  • projectProjectRefrequired
  • deleted_atstring (date-time)required
  • deleted_bystringrequired

    person:<id> or key:<id>, as in the audit log

  • purge_afterstring (date-time)required

    when the purge job removes it for good (7 days after deleted_at)

  • stored_bytesinteger | nullrequired

    the stored data that bills while it waits (a database's, a cache's), last measured; null for apps, functions and queues

  • restoredbooleanrequired

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
402Payment required: free_limit_reached
403Not allowed: forbidden, limit
404Not found: not_found
409Conflict: name_taken, address_taken
500internal: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/projects/my-api/deleted/kind/my-api/restore" \
  -H "Authorization: Bearer $KEY"
GET/v1/projects/{project}/connections

A project's connections#

Both ways: this project's resources used by other projects (out), and other projects' resources used here (in).

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • any
  • any
  • any

Response

200object

  • connectionsConnection[]required
    • kindstringrequired

      one of database, cache, bucket, queue

    • idstringrequired
    • namestringrequired
    • refstringrequired

      how the connected project binds it: <owner>/<name>

    • directionstringrequired

      out: this project's resource used elsewhere; in: another project's used here

      one of in, out

    • projectProjectRefrequired

      the owning project

    • connected_toProjectRefrequired
    • created_atstring (date-time)
    • created_bystring | null
  • next_cursorstring | null

    send as cursor for the next page; null on the last page

Errors

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

Example

curl "https://api.ibel.ai/v1/projects/my-api/connections" \
  -H "Authorization: Bearer $KEY"
POST/v1/projects/{project}/connections

Connect a resource to another project#

The other project's apps and functions then bind it as <project>/<name>. Called on the owning project. Not for members limited to chosen projects.

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

Parameters

  • any

Request bodyapplication/json

  • kindstringrequired

    one of database, cache, bucket, queue

  • namestringrequired

    the resource's name or id in this project

  • projectstringrequired

    the other project's name or id

Response

201Connection

  • kindstringrequired

    one of database, cache, bucket, queue

  • idstringrequired
  • namestringrequired
  • refstringrequired

    how the connected project binds it: <owner>/<name>

  • directionstringrequired

    out: this project's resource used elsewhere; in: another project's used here

    one of in, out

  • projectProjectRefrequired

    the owning project

  • connected_toProjectRefrequired
  • created_atstring (date-time)
  • created_bystring | null

Errors

StatusDescription
400Bad request: bad_kind, bad_name, bad_project
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden
404Not found: not_found
409Conflict: same_project, connected
500internal: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/projects/my-api/connections" \
  -H "Authorization: Bearer $KEY" \
  -d '{"kind":"database","name":"my-api","project":"my-api"}'
DELETE/v1/projects/{project}/connections/{kind}/{name}/{to}

Remove a connection#

Refused while a live version (production or a preview) of the connected project binds it.

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

Parameters

  • any
  • kindstringpathrequired

    one of databases, caches, buckets, queues

  • namestringpathrequired

    the resource's name in the project (any case) or its id

  • tostringpathrequired

    the connected project's name or id

Response

200object

  • kindstring
  • idstring
  • namestring
  • projectProjectRef
  • connected_toProjectRef
  • removedboolean

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden
404Not found: not_found
409Conflict: bound
500internal: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/projects/my-api/connections/kind/my-api/2026-11-04T06%3A00%3A00Z" \
  -H "Authorization: Bearer $KEY"