API reference

Functions

Web-standard functions at <name>.fn.trustpage.ir. Same routes as Apps.

GET/v1/functions

List functions#

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

Response

200object

functionsProject[]required
- idstring (uuid)required
- namestringrequired
- kindstringrequired
  one of function, app
- urlstringrequired
- active_versioninteger | nullrequired
- created_atstring (date-time)required
- statusstringrequired
  running: served a request (a static file or its code) in the last 3 minutes, or static files only (always running once deployed); idle: deployed and quiet, wakes on the next request
  one of running, idle, not_deployed
- created_byActor | null
  who created it; null when not known
- connectedobject[]
  the stores its production version uses
- last_buildobject | nullrequired

Errors

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

Example

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

POST/v1/functions

Create a function#

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

201Project

idstring (uuid)required
namestringrequired
kindstringrequired
one of function, app
urlstringrequired
active_versioninteger | nullrequired
created_atstring (date-time)required
statusstringrequired
running: served a request (a static file or its code) in the last 3 minutes, or static files only (always running once deployed); idle: deployed and quiet, wakes on the next request
one of running, idle, not_deployed
created_byActor | null
who created it; null when not known
- kindstring
  one of person, key, system
- idstring
- namestring | null
- emailstring | null
- avatarstring | null
  a small image as a data URL
- labelstring
- youboolean
connectedobject[]
the stores its production version uses
- kindstring
  one of database, cache, bucket, queue
- namestring
last_buildobject | nullrequired
- idstring (uuid)required
- branchstringrequired
  main for production
- productionbooleanrequired
- commitstring | null
- messagestring | null
  the commit's first line
- statusstringrequired
  one of queued, running, succeeded, failed
- triggerstringrequired
  one of cli, git
- created_atstring (date-time)required

Errors

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

Example

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

GET/v1/functions/{name}

Get a function#

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

Parameters

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

Response

200Project

idstring (uuid)required
namestringrequired
kindstringrequired
one of function, app
urlstringrequired
active_versioninteger | nullrequired
created_atstring (date-time)required
statusstringrequired
running: served a request (a static file or its code) in the last 3 minutes, or static files only (always running once deployed); idle: deployed and quiet, wakes on the next request
one of running, idle, not_deployed
created_byActor | null
who created it; null when not known
- kindstring
  one of person, key, system
- idstring
- namestring | null
- emailstring | null
- avatarstring | null
  a small image as a data URL
- labelstring
- youboolean
connectedobject[]
the stores its production version uses
- kindstring
  one of database, cache, bucket, queue
- namestring
last_buildobject | nullrequired
- idstring (uuid)required
- branchstringrequired
  main for production
- productionbooleanrequired
- commitstring | null
- messagestring | null
  the commit's first line
- statusstringrequired
  one of queued, running, succeeded, failed
- triggerstringrequired
  one of cli, git
- created_atstring (date-time)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/functions/my-api" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/functions/{name}

Delete a function#

With its versions, previews, secrets and logs; its address stops answering at once and the name is free again. Refused while it has cron triggers, or while its live version or a preview binds a database, cache or bucket (checked after the role and the name, before step-up).

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

Parameters

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

Response

200object

namestring
deletedbooleanrequired
versionsinteger
how many versions were removed

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/functions/{name}

Rename a function#

Its address and its previews' move to the new name at once and the old ones stop answering; custom domains stay. Its id, versions, variables, crons, alerts, logs and usage stay with it. The old name stays reserved for 15 minutes. Refused while a build is queued or running, or when a preview's address would pass 63 characters.

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

Parameters

namestringpathrequired
the function's or app'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

Response

200Project

idstring (uuid)required
namestringrequired
kindstringrequired
one of function, app
urlstringrequired
active_versioninteger | nullrequired
created_atstring (date-time)required
statusstringrequired
running: served a request (a static file or its code) in the last 3 minutes, or static files only (always running once deployed); idle: deployed and quiet, wakes on the next request
one of running, idle, not_deployed
created_byActor | null
who created it; null when not known
- kindstring
  one of person, key, system
- idstring
- namestring | null
- emailstring | null
- avatarstring | null
  a small image as a data URL
- labelstring
- youboolean
connectedobject[]
the stores its production version uses
- kindstring
  one of database, cache, bucket, queue
- namestring
last_buildobject | nullrequired
- idstring (uuid)required
- branchstringrequired
  main for production
- productionbooleanrequired
- commitstring | null
- messagestring | null
  the commit's first line
- statusstringrequired
  one of queued, running, succeeded, failed
- triggerstringrequired
  one of cli, git
- created_atstring (date-time)required

Errors

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

Example

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

GET/v1/functions/{name}/versions

List versions (newest 100)#

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

Parameters

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

Response

200object

versionsVersion[]required
- numberintegerrequired
- bundle_hashstring | null
  sha256, hex
  pattern ^[0-9a-f]{64}$
- manifest_hashstring | null
  sha256, hex
  pattern ^[0-9a-f]{64}$
- runtime_datestring
- created_bystring
- created_atstring (date-time)
- activebooleanrequired
  live in production

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/functions/my-api/versions" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/versions

Upload a version#

A function needs modules and no files. JSON body up to 20 MiB.

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

Parameters

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

Request body`application/json`

main_modulestring
entry module name; required with modules
pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\.m?js$
modulesobject
module name -> source; 1-50 modules, 10 MiB in all; required for a function
runtime_datestring (date)
YYYY-MM-DD, 2022-01-01 to today; default today
varsobject
up to 64; names ^[A-Za-z_][A-Za-z0-9_]{0,63}$
bindingsobject
env name -> the team's database, cache or bucket
filesobject
apps only: path -> file; the count, each size and the total by plan (GET /v1/limits)
headers_filestring
apps only: a _headers file
redirects_filestring
apps only: a _redirects file
spaboolean
apps only: serve /index.html for unknown paths

Response

201VersionCreated

versionintegerrequired
bundle_hashstring | null
sha256, hex
pattern ^[0-9a-f]{64}$
manifest_hashstring | null
sha256, hex
pattern ^[0-9a-f]{64}$
filesinteger
spaboolean
runtime_datestring
varsstring[]
bindingsstring[]
created_atstring (date-time)required

Errors

Status	Description
400	Bad request: `bad_bundle`, `bad_bindings`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `missing_assets`, `rotate_storage_key`
413	Body too large: `too_large`, `limit_exceeded` (over the plan's deployment limits, GET /v1/limits)
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/versions" \
  -H "Authorization: Bearer $KEY" \
  -d '{"main_module":"…","modules":{},"runtime_date":"2026-11-04","vars":{},"bindings":{},"files":{},"headers_file":"…","redirects_file":"…","spa":true}'

POST/v1/functions/{name}/deploy

Deploy a version (production or a preview)#

A branch other than main, master or production deploys the preview <branch>--<name>.

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

Parameters

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

Request body`application/json`

versioninteger
default: the newest
branchstring
git branch; default production

Response

200Deployed

namestringrequired
urlstringrequired
branchstring | null
preview label; null for production
active_versionintegerrequired
snapshotinteger | nullrequired
configuration revision; null when superseded
supersededboolean
only when true: a newer version is already live at that address, so this deploy changed nothing (concurrent deploys: the newest wins)
database_branchesDatabaseBranchRef[]
- databasestringrequired
- branchstringrequired

Errors

Status	Description
400	Bad request: `bad_branch`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`, `no_version`
409	Conflict: `binding_gone`, `too_many_branches`, `no_main`, `storage_busy`
500	`internal`: an unexpected failure
503	Unavailable: `storage_unavailable`, `storage_unreachable`

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/deploy" \
  -H "Authorization: Bearer $KEY" \
  -d '{"version":1,"branch":"dev"}'

GET/v1/starters

The starter functions, with their source#

hello, json-api, webhook, cron, database (env.DB) and cache (env.CACHE). Post a starter's files to POST /v1/functions/{name}/source.

Credential: An API key or a dashboard session

Response

200object

startersobject[]
- idstring
- titlestring
- main_modulestring
- filesmap of string
- bindingsobject[]
- cronsstring[]

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential

Example

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

GET/v1/source/limits

The plan's limits on function source and uploaded archives#

Credential: An API key or a dashboard session

Response

200object

planstring
functionobject
- filesinteger
- source_bytesinteger
uploadobject
- archive_bytesinteger
- filesinteger
- expanded_bytesinteger
- file_bytesinteger
- formatsstring[]

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential

Example

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

GET/v1/limits

Deployment size limits, the plan's and every plan's#

What one deployment may hold, by plan: static files, one file, all static files, the function's code compressed (gzip of the stored code) and before compression. Sizes are bytes. plan, function and upload are as in GET /v1/source/limits; deployment and run (copies of a function per server) are the caller's plan; plans is every plan, contract true where the limits are set by contract. The CLI checks a deployment against this before uploading; a deployment over a limit is refused with 413 limit_exceeded.

Credential: An API key or a dashboard session

Response

200object

planstring
functionobject
- filesinteger
- source_bytesinteger
uploadobject
- archive_bytesinteger
- filesinteger
- expanded_bytesinteger
- file_bytesinteger
- formatsstring[]
deploymentDeploymentLimits
- static_filesinteger
  static files in a deployment
- file_bytesinteger
  one static file
- static_bytesinteger
  all static files of a deployment, added up
- function_bytesinteger
  the function's code, gzip-compressed as stored
- function_raw_bytesinteger
  the function's code before compression
runobject
the caller's plan's run limits (D117)
- function_copiesinteger
  copies of one function a server runs at once
plansobject
- hobbyDeploymentPlanLimits
- proDeploymentPlanLimits
- enterpriseDeploymentPlanLimits

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential

Example

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

GET/v1/git/remote

Where git push goes, and how to sign in#

The username can be anything; the password is an API key (developer role or above).

Credential: An API key or a dashboard session

Response

200object

basestring
url_templatestring
e.g. https://git.ibel.ai/{name}.git
remotestring
usernamestring
passwordstring
one of api_key

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential

Example

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

GET/v1/functions/{name}/source

A version's source files (default the live version)#

A version a build or the CLI's bundler made has no plain source (editable false, reason built).

Credential: An API key or a dashboard session

Parameters

namestringpathrequired
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
versionintegerquery

Response

200object

namestring
versioninteger
liveboolean
editableboolean
reasonstring | null
one of built, null
main_modulestring | null
filesmap of string | null

Errors

Status	Description
400	Bad request: `bad_param`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`, `no_version`

Example

curl "https://api.ibel.ai/v1/functions/my-api/source" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/source

Deploy a function from source files as written (no bundling)#

Each file is parsed as an ES module first. The version keeps the text (editable). Bindings left out on an existing function keep the live version's.

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

Parameters

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

Request body`application/json`

filesmap of stringrequired
file name (.js or .mjs) → text; count and size by plan
main_modulestring
default worker.js, else the first file
bindingsobject
as on POST …/versions
varsmap of string
runtime_datestring (date)
createboolean
make the function if it does not exist
deployboolean
false: make the version only; default true

Response

201objectCreated

namestring
createdboolean
versioninteger
deployedboolean
urlstring
active_versioninteger | null
bundle_hashstring
bindingsstring[]
varsstring[]
created_atstring (date-time)

Errors

Status	Description
400	Bad request: `bad_files`, `bad_name`, `bad_main`, `syntax_error`, `bad_bindings`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `name_taken`
413	Too large: `too_large`, `too_many_files`, `limit_exceeded` (over the plan's deployment limits, GET /v1/limits)

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/source" \
  -H "Authorization: Bearer $KEY" \
  -d '{"files":{"KEY":"s3cr3t"}}'

POST/v1/functions/{name}/rollback

Roll production back#

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

Parameters

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

Request body`application/json`

versioninteger
default: the version live before the current one

Response

200RolledBack

namestringrequired
urlstringrequired
active_versionintegerrequired
snapshotinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`, `no_version`
409	Conflict: `not_deployed`, `binding_gone`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/rollback" \
  -H "Authorization: Bearer $KEY" \
  -d '{"version":1}'

GET/v1/functions/{name}/previews

List branch previews#

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

Parameters

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

Response

200object

previewsPreview[]required
- branchstringrequired
- urlstringrequired
- versionintegerrequired
- updated_atstring (date-time)
- git_branchstring | null
  the git branch the build came from
- commitstring | null
- messagestring | null
  the commit's first line

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/functions/my-api/previews" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/functions/{name}/previews/{branch}

Delete a preview#

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

Parameters

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

Response

200PreviewDeleted

branchstringrequired
deletedbooleanrequired
database_branchesobject[]
- databasestringrequired
- branchstringrequired
- deletedbooleanrequired
- reasonstring

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api/previews/dev" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/env

List environment variables#

The project's own and the team's shared ones linked to it. Values are masked unless revealed.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
environmentstringquery
the variables that apply there
one of production, preview, development
branchstringquery
with it: the variables for every preview and that branch's
keystringquery
one key
decryptstringquery
1: plain values (owner, admin, developer); sensitive ones never
one of 1

Response

200EnvVarList

variablesEnvVar[]required
- idstring (uuid)required
- keystringrequired
  pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
- environmentsstring[]required
- branchstring | nullrequired
  a git branch; only with environments [preview]
- scopestringrequired
  team: a shared variable
  one of project, team
- typestringrequired
  sensitive: never shown again, production and preview only
  one of plain, sensitive
- valuestring | nullrequired
  the text only when revealed (?decrypt=1) and plain
- created_atstring (date-time)
- updated_atstring (date-time)
- created_byobject | null
- updated_byobject | null
- projectsobject[]
  shared variables only
sharedEnvVar[]
a project's list: the team's shared variables linked to it
- idstring (uuid)required
- keystringrequired
  pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
- environmentsstring[]required
- branchstring | nullrequired
  a git branch; only with environments [preview]
- scopestringrequired
  team: a shared variable
  one of project, team
- typestringrequired
  sensitive: never shown again, production and preview only
  one of plain, sensitive
- valuestring | nullrequired
  the text only when revealed (?decrypt=1) and plain
- created_atstring (date-time)
- updated_atstring (date-time)
- created_byobject | null
- updated_byobject | null
- projectsobject[]
  shared variables only

Errors

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

Example

curl "https://api.ibel.ai/v1/functions/my-api/env" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/env

Add or import environment variables#

All or none. Applies at once: running deployments restart with the new values.

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

Parameters

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

Request body`application/json`

one of: {key, value, …}, {variables: [...]}, {dotenv}

keystring
valuestring
up to 5120 characters
variablesEnvVarInput[]
several, up to 128
- keystringrequired
- valuestringrequired
  up to 5120 characters
- environmentsstring[]
  default: all three; production and preview when sensitive; preview with a branch
- branchstring
  a git branch: only its previews
- typestring
  one of plain, sensitive
- sensitiveboolean
dotenvstring
.env text to import
environmentsstring[]
for every row that leaves them out
branchstring
projects only
typestring
one of plain, sensitive
sensitiveboolean
upsertboolean
replace the value of a variable with the same key, branch and environments
projectsstring[]
shared variables only: the apps and functions it reaches

Response

201EnvVarAdded

variablesEnvVar[]required
- idstring (uuid)required
- keystringrequired
  pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
- environmentsstring[]required
- branchstring | nullrequired
  a git branch; only with environments [preview]
- scopestringrequired
  team: a shared variable
  one of project, team
- typestringrequired
  sensitive: never shown again, production and preview only
  one of plain, sensitive
- valuestring | nullrequired
  the text only when revealed (?decrypt=1) and plain
- created_atstring (date-time)
- updated_atstring (date-time)
- created_byobject | null
- updated_byobject | null
- projectsobject[]
  shared variables only
createdintegerrequired
updatedintegerrequired

Errors

Status	Description
400	Bad request: `bad_variable`, `bad_key`, `bad_value`, `bad_environments`, `bad_type`, `bad_branch`, `sensitive_development`, `policy_sensitive`, `bad_dotenv`, `duplicate`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `env_conflict`, `sensitive`, `too_many`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/env" \
  -H "Authorization: Bearer $KEY" \
  -d '{"key":"STRIPE_KEY","value":"s3cr3t","variables":[{"key":"STRIPE_KEY","value":"s3cr3t","environments":["production"],"branch":"dev","type":"plain","sensitive":true}],"dotenv":"…","environments":["production"],"branch":"dev","type":"plain","sensitive":true,"upsert":true,"projects":["…"]}'

GET/v1/functions/{name}/env/{id}

One environment variable#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
the variable's id
decryptstringquery
1: plain values (owner, admin, developer); sensitive ones never
one of 1

Response

200EnvVar

idstring (uuid)required
keystringrequired
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
environmentsstring[]required
branchstring | nullrequired
a git branch; only with environments [preview]
scopestringrequired
team: a shared variable
one of project, team
typestringrequired
sensitive: never shown again, production and preview only
one of plain, sensitive
valuestring | nullrequired
the text only when revealed (?decrypt=1) and plain
created_atstring (date-time)
updated_atstring (date-time)
created_byobject | null
- typestring
  one of person, key
- namestring | null
updated_byobject | null
- typestring
  one of person, key
- namestring | null
projectsobject[]
shared variables only
- namestring
- kindstring
  one of function, app

Errors

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

Example

curl "https://api.ibel.ai/v1/functions/my-api/env/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/functions/{name}/env/{id}

Delete an environment variable#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
the variable's id

Response

200object

idstring (uuid)
keystring
deletedboolean

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api/env/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/functions/{name}/env/{id}

Change an environment variable#

A sensitive variable cannot become plain.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
the variable's id

Request body`application/json`

keystring
valuestring
up to 5120 characters
environmentsstring[]
branchstring | null
typestring
one of plain, sensitive
sensitiveboolean
projectsstring[]
shared variables only: replaces the links

Response

200EnvVar

idstring (uuid)required
keystringrequired
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
environmentsstring[]required
branchstring | nullrequired
a git branch; only with environments [preview]
scopestringrequired
team: a shared variable
one of project, team
typestringrequired
sensitive: never shown again, production and preview only
one of plain, sensitive
valuestring | nullrequired
the text only when revealed (?decrypt=1) and plain
created_atstring (date-time)
updated_atstring (date-time)
created_byobject | null
- typestring
  one of person, key
- namestring | null
updated_byobject | null
- typestring
  one of person, key
- namestring | null
projectsobject[]
shared variables only
- namestring
- kindstring
  one of function, app

Errors

Status	Description
400	Bad request: `bad_variable`, `bad_key`, `bad_value`, `bad_environments`, `bad_type`, `bad_branch`, `sensitive_development`, `policy_sensitive`, `bad_dotenv`, `duplicate`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `env_conflict`, `sensitive`, `too_many`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/functions/my-api/env/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY" \
  -d '{"key":"STRIPE_KEY","value":"s3cr3t","environments":["production"],"branch":"dev","type":"plain","sensitive":true,"projects":["…"]}'

PUT/v1/functions/{name}/secrets/{key}

Set a secret (a sensitive variable for production and preview)#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
keystringpathrequired
secret name
pattern ^[A-Z_][A-Z0-9_]{0,63}$

Request body`application/json`

valuestringrequired
up to 5120 characters

Response

200object

namestring
updatedboolean

Errors

Status	Description
400	Bad request: `bad_name`, `bad_value`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `too_many`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/functions/my-api/secrets/STRIPE_KEY" \
  -H "Authorization: Bearer $KEY" \
  -d '{"value":"s3cr3t"}'

DELETE/v1/functions/{name}/secrets/{key}

Delete a key in every environment#

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

Parameters

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

Response

200object

namestring
deletedboolean

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api/secrets/STRIPE_KEY" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/secrets

List the variables' keys#

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

Parameters

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

Response

200object

secretsSecret[]required
- namestringrequired
- updated_atstring (date-time)

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/functions/my-api/secrets" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/crons

List cron triggers#

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

Parameters

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

Response

200object

cronsCron[]required
- exprstringrequired
  5-field cron
- tzstringrequired
  IANA time zone

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/functions/my-api/crons" \
  -H "Authorization: Bearer $KEY"

PUT/v1/functions/{name}/crons

Replace the cron triggers#

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

Parameters

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

Request body`application/json`

crons(string | object)[]required
up to 5
- exprstringrequired
- tzstring
tzstring
default "Asia/Tehran"

Response

200object

cronsCron[]required
- exprstringrequired
  5-field cron
- tzstringrequired
  IANA time zone

Errors

Status	Description
400	Bad request: `bad_crons`, `too_many`, `bad_cron`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/functions/my-api/crons" \
  -H "Authorization: Bearer $KEY" \
  -d '{"crons":["0 3 * * *"]}'

GET/v1/functions/{name}/logs

Log entries, filtered and paged#

The newest limit entries that match, newest last; next_cursor reaches older ones. The store keeps about the last 2000 per project.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
sincestringquery
ISO time, epoch ms, or back from now: 30m, 1h, 7d
untilstringquery
ISO time or epoch ms
levelstringquery
error, warning, info (comma list)
sourcestringquery
request, static, fetch, cron, console (comma list)
statusstringquery
codes or classes, e.g. 404,5xx
pathstringquery
request paths (comma list); end with * for a prefix
environmentstringquery
production or preview
branchstringquery
a preview's branch
deploymentstringquery
a version number, e.g. 12 or v12
qstringquery
text the entry contains
limitintegerquery
1-1000, default 100
1–1000 · default 100
cursorstringquery
next_cursor of the page before
facetsstringquery
1: counts per filter value
bucketsintegerquery
a histogram of the range in this many bars (up to 120)
0–120

Response

200LogPage

logsLogEntry[]required
newest last
- idstringrequired
- tinteger
  milliseconds since 1970
- kindstring
- levelstring
- msgstring
- methodstring
- pathstring
- statusinteger
- msnumber
- versioninteger
- staticboolean
- cronstring
- outcomestring
- hoststring
  the hostname a request was served on
- tracestring
  the request's trace id (32 hex), when its trace was kept; open it with GET /v1/traces/{trace_id}
- severitystring
  one of error, warning, info
- sourcestring
  one of request, static, fetch, cron, console
- environmentstring
  one of production, preview
- branchstring | null
  a preview's branch, when known
- projectstring
  team logs: the project
- productstring
  one of function, app
next_cursorstring | nullrequired
pass as cursor for older entries
matchedintegerrequired
entries in the range that match
scannedintegerrequired
truncatedboolean
the team's request read only part of its logs
facetsobject
with facets=1: counts per filter value, each over what the other filters leave
- levelobject
- sourceobject
- statusobject
- environmentobject
- pathobject
- projectobject
histogramobject
with buckets=n: the range in n bars, per level
- frominteger
- tointeger
- bucketsobject[]

Errors

Status	Description
400	Bad request: `bad_param`
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/functions/my-api/logs" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/tail

Follow the log (server-sent events)#

Each event is data: <LogEntry JSON>; : keep-alive comments about every 10 s.

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

Parameters

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

Response

200stringtext/event-stream

Errors

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

Example

Request

curl -N "https://api.ibel.ai/v1/functions/my-api/tail" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/usage

Usage per minute#

At most 31 days per request.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
fromstring (date-time)query
ISO time; default an hour before to
tostring (date-time)query
ISO time; default now

Response

200UsageReport

fromstring (date-time)required
tostring (date-time)required
totalUsagerequired
- requestsinteger
- errorsinteger
- wall_msinteger
- static_requestsinteger
- bytes_outinteger
- subrequestsinteger
- egress_bytesinteger
seriesUsage[]required
- requestsinteger
- errorsinteger
- wall_msinteger
- static_requestsinteger
- bytes_outinteger
- subrequestsinteger
- egress_bytesinteger
- minutestring (date-time)

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/functions/my-api/usage" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/observability

Requests, errors and latency#

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

Parameters

namestringpathrequired
the function's or app'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

200Observability

rangestringrequired
stepstringrequired
totalsPercentilesrequired
- requestsinteger
  every request served, static files and code
- function_requestsinteger
  requests that ran the code
- static_requestsinteger
  requests answered with a static file
- errors_4xxinteger
- errors_5xxinteger
- error_ratenumber
- p50number | null
- p95number | null
- p99number | null
seriesPercentiles[]required
- tstring (date-time)
- requestsinteger
- function_requestsinteger
  requests that ran the code
- static_requestsinteger
  requests answered with a static file
- errors_4xxinteger
- errors_5xxinteger
- p50number | null
- p95number | null
- p99number | null
routesPercentiles[]required
- routestring
- requestsinteger
- function_requestsinteger
  requests that ran the code
- static_requestsinteger
  requests answered with a static file
- errors_5xxinteger
- error_ratenumber
- avg_msnumber | null
- p50number | null
- p95number | null
- p99number | null
notestring
copiesFunctionCopies
- limitintegerrequired
  the plan's copies per server (function_copies in GET /v1/limits)
- perstringrequired
  one of server
- totalsCopyFiguresrequired
- seriesobject[]required
  the same steps as the observability series
- serversCopyFigures[]required

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/functions/my-api/observability" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/builds

List builds (newest 50)#

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

Parameters

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

Response

200object

buildsBuild[]required
- idstring (uuid)required
- branchstring | null
- commitstring | null
  pattern ^[0-9a-f]{40}$
- messagestring | null
  the commit's first line
- statusstringrequired
  one of queued, running, succeeded, failed, cancelled, skipped
- triggerstringrequired
  one of cli, git
- versioninteger | null
- errorstring | null
- created_atstring (date-time)required
- started_atstring (date-time) | null
- finished_atstring (date-time) | null
- secondsinteger | null
- stagedboolean
  a production build held for its checks
- promotionstring
  one of none, waiting, promoted, blocked, superseded
- scanobject | null
  the dependency scan's summary
- queueobject | null
  a queued build's place in the team's queue
- configBuildConfig | null
  the build configuration frozen when the build started
- no_cacheboolean
  built without the build cache
- cacheobject | null
- hintobject | null
  a failed build explained; show it above the log
- secretsobject | null
  the secret scan's summary
- sbomobject | null
- provenanceobject | null
- skip_reasonstring | null
- cancelled_bystring | null

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/functions/my-api/builds" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/builds

Queue a build from a source tarball#

The body is a .tar.gz of the project, up to 100 MiB.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
branchstringquery
git branch; none, main, master or production builds production
commitstringquery
40-hex git SHA
pattern ^[0-9a-f]{40}$
no_cachestringquery
1: build without the build cache
one of 1, true
triggerstringquery
git counts only from the Git receiver (its own token); otherwise the build is cli
one of cli, git

Request body`application/gzip`

string (binary)

Response

201Build

idstring (uuid)required
branchstring | null
commitstring | null
pattern ^[0-9a-f]{40}$
messagestring | null
the commit's first line
statusstringrequired
one of queued, running, succeeded, failed, cancelled, skipped
triggerstringrequired
one of cli, git
versioninteger | null
errorstring | null
created_atstring (date-time)required
started_atstring (date-time) | null
finished_atstring (date-time) | null
secondsinteger | null
stagedboolean
a production build held for its checks
promotionstring
one of none, waiting, promoted, blocked, superseded
scanobject | null
the dependency scan's summary
queueobject | null
a queued build's place in the team's queue
- positioninteger
  1 is the team's next
- aheadinteger
- runninginteger
- limitinteger
  the team's concurrent builds
- reasonstring
  one of team_limit, waiting_for_builder
configBuildConfig | null
the build configuration frozen when the build started
- root_dirstringrequired
  a folder in the repository; empty: the root
- ignore_commandstringrequired
  exit 0 skips the build; empty: never skip
- install_commandstringrequired
  empty: detected
- build_commandstringrequired
  empty: detected
- output_dirstringrequired
  empty: detected
- node_versionstring | nullrequired
  null: the default (26)
  one of 22, 24, 26, null
- secret_scanstringrequired
  one of block, warn
- cachebooleanrequired
no_cacheboolean
built without the build cache
cacheobject | null
- statusstring
  one of hit, miss, off, skipped, no_lockfile
- keystring
- frameworkstring
- restored_bytesinteger
- saved_bytesinteger
- evictedinteger
- notestring
hintobject | null
a failed build explained; show it above the log
- kindstring
  one of typescript, module_not_found, missing_env, out_of_memory, timeout, install_failed, secrets, no_output, build_command_failed
- titlestring
- explainstring
- fixstring
- filestring
- lineinteger
- columninteger
secretsobject | null
the secret scan's summary
- scannedboolean
- countinteger
- highinteger
- blockedboolean
- policystring
  one of block, warn
sbomobject | null
- componentsinteger
- lock_filestring
provenanceobject | null
- key_idstring
- output_sha256string
skip_reasonstring | null
cancelled_bystring | null

Errors

Status	Description
400	Bad request: `bad_source`, `bad_commit`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
413	Body too large: `too_large`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/builds" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/gzip" --data-binary @source.tar.gz

GET/v1/functions/{name}/builds/{id}

Get a build#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id

Response

200Build

idstring (uuid)required
branchstring | null
commitstring | null
pattern ^[0-9a-f]{40}$
messagestring | null
the commit's first line
statusstringrequired
one of queued, running, succeeded, failed, cancelled, skipped
triggerstringrequired
one of cli, git
versioninteger | null
errorstring | null
created_atstring (date-time)required
started_atstring (date-time) | null
finished_atstring (date-time) | null
secondsinteger | null
stagedboolean
a production build held for its checks
promotionstring
one of none, waiting, promoted, blocked, superseded
scanobject | null
the dependency scan's summary
queueobject | null
a queued build's place in the team's queue
- positioninteger
  1 is the team's next
- aheadinteger
- runninginteger
- limitinteger
  the team's concurrent builds
- reasonstring
  one of team_limit, waiting_for_builder
configBuildConfig | null
the build configuration frozen when the build started
- root_dirstringrequired
  a folder in the repository; empty: the root
- ignore_commandstringrequired
  exit 0 skips the build; empty: never skip
- install_commandstringrequired
  empty: detected
- build_commandstringrequired
  empty: detected
- output_dirstringrequired
  empty: detected
- node_versionstring | nullrequired
  null: the default (26)
  one of 22, 24, 26, null
- secret_scanstringrequired
  one of block, warn
- cachebooleanrequired
no_cacheboolean
built without the build cache
cacheobject | null
- statusstring
  one of hit, miss, off, skipped, no_lockfile
- keystring
- frameworkstring
- restored_bytesinteger
- saved_bytesinteger
- evictedinteger
- notestring
hintobject | null
a failed build explained; show it above the log
- kindstring
  one of typescript, module_not_found, missing_env, out_of_memory, timeout, install_failed, secrets, no_output, build_command_failed
- titlestring
- explainstring
- fixstring
- filestring
- lineinteger
- columninteger
secretsobject | null
the secret scan's summary
- scannedboolean
- countinteger
- highinteger
- blockedboolean
- policystring
  one of block, warn
sbomobject | null
- componentsinteger
- lock_filestring
provenanceobject | null
- key_idstring
- output_sha256string
skip_reasonstring | null
cancelled_bystring | null

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/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/builds/{id}/logs

A build's log#

1000 lines per call. Each step starts with a line ── <step> (unpack, install, build and deploy).

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id
afterstringquery
the last line id received, <ms>-<n>

Response

200BuildLog

statusstringrequired
linesobject[]required
- idstringrequired
- tinteger
- linestringrequired
last_idstring
the last entry read, shown or not: the next after

Errors

Status	Description
400	Bad request: `bad_param`
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/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903/logs" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/builds/{id}/cancel

Cancel a build#

A queued or running build; a running one stops and deploys nothing.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id

Response

200object

idstring (uuid)required
statusstringrequired
one of cancelled

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
409	Conflict: `not_running` (the build already finished)
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903/cancel" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/builds/{id}/redeploy

Build the same source again#

The same source or commit as the build, with today's build configuration.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id
no_cachestringquery
1: build without the build cache
one of 1, true

Response

201object

idstring (uuid)required
statusstringrequired
one of queued
no_cachebooleanrequired

Errors

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

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903/redeploy" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/builds/{id}/secrets

A build's secret findings#

Where the secret scan found likely secrets (never the values).

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id

Response

200SecretFindings

summaryobject | nullrequired
- scannedboolean
- countinteger
- highinteger
- blockedboolean
- policystring
findingsobject[]required
- rulestring
- descriptionstring
- filestring
- lineinteger
- confidencestring
  one of high, low

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/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903/secrets" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/builds/{id}/sbom

A build's bill of materials#

The CycloneDX 1.5 document made from the build's lock file.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id
downloadstringquery
1: as a file (content-disposition)
one of 1

Response

200objectapplication/vnd.cyclonedx+json

Errors

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

Example

Request

curl "https://api.ibel.ai/v1/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903/sbom" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/builds/{id}/provenance

A build's provenance record#

Only a build that deployed has one.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstring (uuid)pathrequired
build id

Response

200ProvenanceRecord

statementProvenanceStatementrequired
- typestring
  one of cloudhost.build-provenance/v1
- subjectobject
- buildobject
- builderobject
- issued_atstring (date-time)
signaturestringrequired
base64
algorithmstringrequired
one of ed25519
key_idstringrequired

Errors

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

Example

curl "https://api.ibel.ai/v1/functions/my-api/builds/88e2fe1d-6d75-4de5-8c8f-27380ec66903/provenance" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/build-config

Get the build configuration#

How the project is built, the Node.js versions offered, the plan's limits and the build cache.

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

Parameters

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

Response

200BuildConfigView

settingsBuildConfigrequired
- root_dirstringrequired
  a folder in the repository; empty: the root
- ignore_commandstringrequired
  exit 0 skips the build; empty: never skip
- install_commandstringrequired
  empty: detected
- build_commandstringrequired
  empty: detected
- output_dirstringrequired
  empty: detected
- node_versionstring | nullrequired
  null: the default (26)
  one of 22, 24, 26, null
- secret_scanstringrequired
  one of block, warn
- cachebooleanrequired
node_versionsstring[]required
default_node_versionstringrequired
limitsobjectrequired
- concurrent_buildsinteger
- cache_bytesinteger
cacheBuildCacherequired
- entriesobject[]required
- bytesintegerrequired
- limit_bytesintegerrequired
  the plan's size: Hobby 500 MB, Pro 1 GB, Enterprise 2 GB

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/functions/my-api/build-config" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/functions/{name}/build-config

Change the build configuration#

Only the fields sent change; null or an empty string puts a field back to its default. The next build uses them.

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

Parameters

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

Request body`application/json`

any of the fields; null or an empty string clears one

root_dirstring | null
up to 200 characters
ignore_commandstring | null
up to 500 characters
install_commandstring | null
up to 500 characters
build_commandstring | null
up to 500 characters
output_dirstring | null
up to 200 characters
node_versionstring | null
one of 22, 24, 26, null
secret_scanstring
one of block, warn
cacheboolean

Response

200object

settingsBuildConfigrequired
- root_dirstringrequired
  a folder in the repository; empty: the root
- ignore_commandstringrequired
  exit 0 skips the build; empty: never skip
- install_commandstringrequired
  empty: detected
- build_commandstringrequired
  empty: detected
- output_dirstringrequired
  empty: detected
- node_versionstring | nullrequired
  null: the default (26)
  one of 22, 24, 26, null
- secret_scanstringrequired
  one of block, warn
- cachebooleanrequired

Errors

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

Example

curl -X PATCH "https://api.ibel.ai/v1/functions/my-api/build-config" \
  -H "Authorization: Bearer $KEY" \
  -d '{"root_dir":"…","ignore_command":"…","install_command":"…","build_command":"…","output_dir":"…","node_version":"22","secret_scan":"block","cache":true}'

GET/v1/functions/{name}/build-cache

The build cache#

What the project's build cache holds; the oldest entries go first when it is over the plan's size.

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

Parameters

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

Response

200BuildCache

entriesobject[]required
- keystring
- frameworkstring
- bytesinteger
- created_atstring (date-time)
- used_atstring (date-time)
bytesintegerrequired
limit_bytesintegerrequired
the plan's size: Hobby 500 MB, Pro 1 GB, Enterprise 2 GB

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/functions/my-api/build-cache" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/functions/{name}/build-cache

Clear the build cache#

The next build starts fresh.

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

Parameters

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

Response

200object

clearedintegerrequired

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api/build-cache" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/transfer

Move to another team#

Refused while any version binds a database, cache or bucket.

Credential: A dashboard session only (API keys are refused)
Roles: admin or owner in both teams
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

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

Request body`application/json`

teamstring (uuid)required

Response

200object

movedstring
tostring

Errors

Status	Description
400	Bad request: `same_team`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`, `session_only`
404	Not found: `not_found`
409	Conflict: `has_bindings`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/transfer" \
  -H "Authorization: Bearer $SESSION" \
  -d '{"team":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f"}'

GET/v1/functions/{name}/domains

List the project's custom domains#

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

Parameters

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

Response

200object

domainsDomain[]required
- namestringrequired
  lowercase ASCII (an international name in its xn-- form)
- apexstringrequired
  the registrable domain
- typestringrequired
  one of apex, subdomain
- projectobjectrequired
- branchstring | null
  a git branch: the domain serves its preview
- servesstring | null
  the platform address it serves; null for a redirect
- redirectobject | null
- statestringrequired
  one of pending, verifying, valid, misconfigured, error
- reasonstring | null
  what is missing or wrong, for people
- verifiedbooleanrequired
  ownership proven by the TXT record
- recordsDomainRecord[]required
  the records to set at the DNS provider
- checksobject[]
  what the last lookup found
- certificateobjectrequired
- urlstringrequired
- checked_atstring (date-time) | null
- next_check_atstring (date-time)
- created_atstring (date-time)
- alsoDomain[]
  add only: the www pair added with it
limitinteger
domains per project on the team's plan

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/functions/my-api/domains" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/domains

Add a custom domain#

Records: a subdomain is a CNAME to the platform's target, a registrable domain A records to the gateway addresses; a TXT record on the registrable domain proves ownership (one per team covers every name under it). States: pending, misconfigured, verifying (a certificate is being obtained), valid, error.

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

Parameters

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

Request body`application/json`

domainstringrequired
a subdomain (shop.example.ir) or a registrable domain (example.ir)
wwwstring
for a root or www name: also add the other one, redirecting to the root or to www
one of none, redirect-to-apex, redirect-to-www
redirect_tostring
another domain of the project: answer with a redirect there
redirect_statusinteger
one of 301, 302, 307, 308 · default 308
branchstring
a git branch: serve its preview instead of production

Response

201Domain

namestringrequired
lowercase ASCII (an international name in its xn-- form)
apexstringrequired
the registrable domain
typestringrequired
one of apex, subdomain
projectobjectrequired
- namestring
- kindstring
  one of function, app
- productstring
  one of functions, apps
branchstring | null
a git branch: the domain serves its preview
servesstring | null
the platform address it serves; null for a redirect
redirectobject | null
- tostring
- statusinteger
  one of 301, 302, 307, 308
statestringrequired
one of pending, verifying, valid, misconfigured, error
reasonstring | null
what is missing or wrong, for people
verifiedbooleanrequired
ownership proven by the TXT record
recordsDomainRecord[]required
the records to set at the DNS provider
- typestringrequired
  one of A, CNAME, TXT
- namestringrequired
  relative to the registrable domain; @ is the domain itself
- hoststringrequired
  the full name
- valuestringrequired
- purposestringrequired
  one of routing, ownership
- okbooleanrequired
  found as it should be at the last check
checksobject[]
what the last lookup found
- typestring
- hoststring
- okboolean
- foundstring[]
certificateobjectrequired
- statestringrequired
  one of none, issuing, valid, renewing, expired
- not_beforestring (date-time)
- not_afterstring (date-time)
- issued_atstring (date-time)
- renew_errorstring
- next_attempt_atstring (date-time)
urlstringrequired
checked_atstring (date-time) | null
next_check_atstring (date-time)
created_atstring (date-time)
alsoDomain[]
add only: the www pair added with it

Errors

Status	Description
400	Bad request: `bad_domain`, `reserved_domain`, `bad_redirect`, `bad_branch`, `bad_www`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `domain_limit`
404	Not found: `not_found`
409	Conflict: `domain_exists`, `domain_taken`
429	Too many requests: `rate_limited`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/domains" \
  -H "Authorization: Bearer $KEY" \
  -d '{"domain":"…"}'

GET/v1/functions/{name}/domains/ibel.ai

One custom domain#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
domainstringpathrequired
the domain, e.g. shop.example.ir

Response

200Domain

namestringrequired
lowercase ASCII (an international name in its xn-- form)
apexstringrequired
the registrable domain
typestringrequired
one of apex, subdomain
projectobjectrequired
- namestring
- kindstring
  one of function, app
- productstring
  one of functions, apps
branchstring | null
a git branch: the domain serves its preview
servesstring | null
the platform address it serves; null for a redirect
redirectobject | null
- tostring
- statusinteger
  one of 301, 302, 307, 308
statestringrequired
one of pending, verifying, valid, misconfigured, error
reasonstring | null
what is missing or wrong, for people
verifiedbooleanrequired
ownership proven by the TXT record
recordsDomainRecord[]required
the records to set at the DNS provider
- typestringrequired
  one of A, CNAME, TXT
- namestringrequired
  relative to the registrable domain; @ is the domain itself
- hoststringrequired
  the full name
- valuestringrequired
- purposestringrequired
  one of routing, ownership
- okbooleanrequired
  found as it should be at the last check
checksobject[]
what the last lookup found
- typestring
- hoststring
- okboolean
- foundstring[]
certificateobjectrequired
- statestringrequired
  one of none, issuing, valid, renewing, expired
- not_beforestring (date-time)
- not_afterstring (date-time)
- issued_atstring (date-time)
- renew_errorstring
- next_attempt_atstring (date-time)
urlstringrequired
checked_atstring (date-time) | null
next_check_atstring (date-time)
created_atstring (date-time)
alsoDomain[]
add only: the www pair added with it

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/functions/my-api/domains/domain" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/functions/{name}/domains/ibel.ai

Remove a custom domain#

Stops serving it and deletes its certificate; domains redirecting to it stop redirecting.

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
domainstringpathrequired
the domain, e.g. shop.example.ir

Response

200object

namestring
removedboolean

Errors

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

Example

curl -X DELETE "https://api.ibel.ai/v1/functions/my-api/domains/domain" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/functions/{name}/domains/ibel.ai

Change a domain's redirect or branch#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
domainstringpathrequired
the domain, e.g. shop.example.ir

Request body`application/json`

redirect_tostring | null
redirect_statusinteger
one of 301, 302, 307, 308
branchstring | null

Response

200Domain

namestringrequired
lowercase ASCII (an international name in its xn-- form)
apexstringrequired
the registrable domain
typestringrequired
one of apex, subdomain
projectobjectrequired
- namestring
- kindstring
  one of function, app
- productstring
  one of functions, apps
branchstring | null
a git branch: the domain serves its preview
servesstring | null
the platform address it serves; null for a redirect
redirectobject | null
- tostring
- statusinteger
  one of 301, 302, 307, 308
statestringrequired
one of pending, verifying, valid, misconfigured, error
reasonstring | null
what is missing or wrong, for people
verifiedbooleanrequired
ownership proven by the TXT record
recordsDomainRecord[]required
the records to set at the DNS provider
- typestringrequired
  one of A, CNAME, TXT
- namestringrequired
  relative to the registrable domain; @ is the domain itself
- hoststringrequired
  the full name
- valuestringrequired
- purposestringrequired
  one of routing, ownership
- okbooleanrequired
  found as it should be at the last check
checksobject[]
what the last lookup found
- typestring
- hoststring
- okboolean
- foundstring[]
certificateobjectrequired
- statestringrequired
  one of none, issuing, valid, renewing, expired
- not_beforestring (date-time)
- not_afterstring (date-time)
- issued_atstring (date-time)
- renew_errorstring
- next_attempt_atstring (date-time)
urlstringrequired
checked_atstring (date-time) | null
next_check_atstring (date-time)
created_atstring (date-time)
alsoDomain[]
add only: the www pair added with it

Errors

Status	Description
400	Bad request: `bad_redirect`, `bad_branch`, `nothing_to_change`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/functions/my-api/domains/domain" \
  -H "Authorization: Bearer $KEY" \
  -d '{"redirect_to":"…","redirect_status":301,"branch":"dev"}'

POST/v1/functions/{name}/domains/ibel.ai/verify

Check a domain's DNS now#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
domainstringpathrequired
the domain, e.g. shop.example.ir

Response

200Domain

namestringrequired
lowercase ASCII (an international name in its xn-- form)
apexstringrequired
the registrable domain
typestringrequired
one of apex, subdomain
projectobjectrequired
- namestring
- kindstring
  one of function, app
- productstring
  one of functions, apps
branchstring | null
a git branch: the domain serves its preview
servesstring | null
the platform address it serves; null for a redirect
redirectobject | null
- tostring
- statusinteger
  one of 301, 302, 307, 308
statestringrequired
one of pending, verifying, valid, misconfigured, error
reasonstring | null
what is missing or wrong, for people
verifiedbooleanrequired
ownership proven by the TXT record
recordsDomainRecord[]required
the records to set at the DNS provider
- typestringrequired
  one of A, CNAME, TXT
- namestringrequired
  relative to the registrable domain; @ is the domain itself
- hoststringrequired
  the full name
- valuestringrequired
- purposestringrequired
  one of routing, ownership
- okbooleanrequired
  found as it should be at the last check
checksobject[]
what the last lookup found
- typestring
- hoststring
- okboolean
- foundstring[]
certificateobjectrequired
- statestringrequired
  one of none, issuing, valid, renewing, expired
- not_beforestring (date-time)
- not_afterstring (date-time)
- issued_atstring (date-time)
- renew_errorstring
- next_attempt_atstring (date-time)
urlstringrequired
checked_atstring (date-time) | null
next_check_atstring (date-time)
created_atstring (date-time)
alsoDomain[]
add only: the www pair added with it

Errors

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

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/domains/domain/verify" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/build-settings

Get build settings#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Response

200BuildSettings

smokeboolean
smoke_pathstring
test_commandstring | null
typecheckboolean
typecheck_commandstring | null
required_checksstring[]
check_timeout_minutesinteger
scan_fail_onstring
one of none, high, critical
planstring
appliesobject
the same settings as the team's plan allows them today

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/functions/my-api/build-settings" \
  -H "Authorization: Bearer $KEY"

PUT/v1/functions/{name}/build-settings

Change build settings#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Request body`application/json`

only the fields sent change

smokeboolean
smoke_pathstring
up to 200 characters
test_commandstring | null
up to 300 characters
typecheckboolean
typecheck_commandstring | null
up to 300 characters
required_checksstring[]
0–10 items
check_timeout_minutesinteger
1–60
scan_fail_onstring
one of none, high, critical

Response

200BuildSettings

smokeboolean
smoke_pathstring
test_commandstring | null
typecheckboolean
typecheck_commandstring | null
required_checksstring[]
check_timeout_minutesinteger
scan_fail_onstring
one of none, high, critical
planstring
appliesobject
the same settings as the team's plan allows them today

Errors

Status	Description
400	Bad request: `bad_settings`, `bad_name`, `bad_status`, `bad_url`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Forbidden: `forbidden`, `plan_required`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/functions/my-api/build-settings" \
  -H "Authorization: Bearer $KEY" \
  -d '{"smoke":true,"smoke_path":"…","test_command":"…","typecheck":true,"typecheck_command":"…","required_checks":["…"],"check_timeout_minutes":1,"scan_fail_on":"none"}'

GET/v1/functions/{name}/deployments/{build}/checks

A deployment's checks#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)

Response

200DeploymentChecks

buildstring (uuid)
promotionstring
one of none, waiting, promoted, blocked, superseded
stagedboolean
versioninteger | null
deadlinestring (date-time) | null
checksCheck[]
- namestringrequired
- sourcestringrequired
  one of builtin, external
- statusstringrequired
  one of pending, queued, running, passed, failed, timed_out
- requiredboolean
- summarystring | null
- urlstring | null
- attemptinteger
- started_atstring (date-time) | null
- finished_atstring (date-time) | null
- secondsinteger | null
- logstring
  the end of its output; only on the single-check route

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/functions/my-api/deployments/build/checks" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/deployments/{build}/checks/{check}

One check, with its log#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)
checkstringpathrequired
the check's name; a '/' in it is sent as %2F
pattern ^[a-z0-9][a-z0-9._/-]{0,63}$

Response

200Check

namestringrequired
sourcestringrequired
one of builtin, external
statusstringrequired
one of pending, queued, running, passed, failed, timed_out
requiredboolean
summarystring | null
urlstring | null
attemptinteger
started_atstring (date-time) | null
finished_atstring (date-time) | null
secondsinteger | null
logstring
the end of its output; only on the single-check route

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/functions/my-api/deployments/build/checks/check" \
  -H "Authorization: Bearer $KEY"

PUT/v1/functions/{name}/deployments/{build}/checks/{check}

Report an external check (a CI)#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)
checkstringpathrequired
the check's name; a '/' in it is sent as %2F
pattern ^[a-z0-9][a-z0-9._/-]{0,63}$

Request body`application/json`

statusstringrequired
one of running, passed, failed
summarystring
up to 300 characters
urlstring
up to 500 characters
logstring
up to 65536 characters

Response

200Check

namestringrequired
sourcestringrequired
one of builtin, external
statusstringrequired
one of pending, queued, running, passed, failed, timed_out
requiredboolean
summarystring | null
urlstring | null
attemptinteger
started_atstring (date-time) | null
finished_atstring (date-time) | null
secondsinteger | null
logstring
the end of its output; only on the single-check route

Errors

Status	Description
400	Bad request: `bad_settings`, `bad_name`, `bad_status`, `bad_url`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
409	Conflict: `running`, `decided`, `not_waiting`, `superseded`, `too_many_checks`, `reserved_name`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/functions/my-api/deployments/build/checks/check" \
  -H "Authorization: Bearer $KEY" \
  -d '{"status":"running"}'

POST/v1/functions/{name}/deployments/{build}/checks/{check}/rerun

Run a check again#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)
checkstringpathrequired
the check's name; a '/' in it is sent as %2F
pattern ^[a-z0-9][a-z0-9._/-]{0,63}$

Response

200object

rerunstring
one of smoke, pending, build
buildstring (uuid)

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
409	Conflict: `running`, `decided`, `not_waiting`, `superseded`, `too_many_checks`, `reserved_name`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/deployments/build/checks/check/rerun" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/deployments/{build}/promote

Make a deployment waiting on its checks live#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)

Response

200object

buildstring (uuid)
promotionstring
versioninteger

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Forbidden: `forbidden`, `plan_required`
404	Not found: `not_found`
409	Conflict: `running`, `decided`, `not_waiting`, `superseded`, `too_many_checks`, `reserved_name`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/deployments/build/promote" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/deployments/{build}/vulnerabilities

Vulnerable dependencies of a build#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)

Response

200Vulnerabilities

buildstring (uuid)
scanobject
- statusstring
  one of ok, no_lockfile, unreadable, too_large, no_data, not_run
- lockfilestring | null
- packagesinteger
- countsobject
- blockedboolean
vulnerabilitiesVulnerability[]
- packagestring
- versionstring
- severitystring
  one of critical, high, moderate, low, unknown
- advisorystring
- aliasesstring[]
- titlestring
- fixed_versionstring | null
- devboolean
- scorenumber | null

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/functions/my-api/deployments/build/vulnerabilities" \
  -H "Authorization: Bearer $KEY"

POST/v1/functions/{name}/deployments/{build}/vulnerabilities/rescan

Scan a build's dependencies again#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
buildstring (uuid)pathrequired
the build's id (a deployment)

Response

200Vulnerabilities

buildstring (uuid)
scanobject
- statusstring
  one of ok, no_lockfile, unreadable, too_large, no_data, not_run
- lockfilestring | null
- packagesinteger
- countsobject
- blockedboolean
vulnerabilitiesVulnerability[]
- packagestring
- versionstring
- severitystring
  one of critical, high, moderate, low, unknown
- advisorystring
- aliasesstring[]
- titlestring
- fixed_versionstring | null
- devboolean
- scorenumber | null

Errors

Status	Description
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
409	Conflict: `running`, `decided`, `not_waiting`, `superseded`, `too_many_checks`, `reserved_name`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/deployments/build/vulnerabilities/rescan" \
  -H "Authorization: Bearer $KEY"

GET/v1/functions/{name}/vulnerabilities

The project's dependency summary#

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

Parameters

namestringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Response

200object

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/functions/my-api/vulnerabilities" \
  -H "Authorization: Bearer $KEY"

GET/v1/provenance/key

The platform's provenance key#

The Ed25519 public key that signs build provenance records.

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

Response

200object

algorithmstringrequired
one of ed25519
key_idstringrequired
public_keystringrequired
PEM

Errors

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

Example

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

POST/v1/provenance/verify

Check a provenance record#

Checks the signature with the platform's key, and whether the record is the one held for that build.

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

Request body`application/json`

statementProvenanceStatementrequired
- typestring
  one of cloudhost.build-provenance/v1
- subjectobject
- buildobject
- builderobject
- issued_atstring (date-time)
signaturestringrequired
base64
algorithmstringrequired
one of ed25519
key_idstringrequired

Response

200object

validbooleanrequired
reasonstring
issued_by_usbooleanrequired
statementProvenanceStatement
- typestring
  one of cloudhost.build-provenance/v1
- subjectobject
- buildobject
- builderobject
- issued_atstring (date-time)

Errors

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

Example

curl -X POST "https://api.ibel.ai/v1/provenance/verify" \
  -H "Authorization: Bearer $KEY" \
  -d '{"statement":{"type":"cloudhost.build-provenance/v1","subject":{"kind":"…","name":"my-api","output_sha256":"…","bundle_sha256":"…","manifest_sha256":"…","version":1},"build":{"id":"88e2fe1d-6d75-4de5-8c8f-27380ec66903","trigger":"…","branch":"dev","commit":"3f786850e387550fdab836ed7e6dc881de23001b","source_sha256":"…","lock_file":"…","lock_file_sha256":"…","sbom_sha256":"…","started_at":"…","finished_at":"…"},"builder":{"name":"my-api","isolation":"…","cache":"…"},"issued_at":"2026-11-04T09:30:00Z"},"signature":"…","algorithm":"ed25519","key_id":"…"}'

List functions#

Response

Errors

Example

Create a function#

Request bodyapplication/json

Response

Errors

Example

Get a function#

Parameters

Response

Errors

Example

Delete a function#

Parameters

Response

Errors

Example

Rename a function#

Parameters

Request bodyapplication/json

Response

Errors

Example

List versions (newest 100)#

Parameters

Response

Errors

Example

Upload a version#

Parameters

Request bodyapplication/json

Response

Errors

Example

Deploy a version (production or a preview)#

Parameters

Request bodyapplication/json

Response

Errors

Example

The starter functions, with their source#

Response

Errors

Example

The plan's limits on function source and uploaded archives#

Response

Errors

Example

Deployment size limits, the plan's and every plan's#

Response

Errors

Example

Where git push goes, and how to sign in#

Response

Errors

Example

A version's source files (default the live version)#

Parameters

Response

Errors

Example

Deploy a function from source files as written (no bundling)#

Parameters

Request bodyapplication/json

Response

Errors

Example

Roll production back#

Parameters

Request bodyapplication/json

Response

Errors

Example

List branch previews#

Parameters

Response

Errors

Example

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`