Deployment protection and releases

Get deployment protection#

Who may open previews (off, team: members who sign in, password) and whether production is protected too; exceptions (domain names never protected), options_passthrough (OPTIONS requests pass, for CORS preflight), password_set, the bypass token's hint, the shareable links, and pro (the password and links are Pro).

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

Errors

Example

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

Set deployment protection#

Any of previews (off, team, password), production, options_passthrough, exceptions (20 at most), password (8 to 128 characters; needed the first time password is chosen; changing it signs everyone out). Answers like GET.

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 bodyapplication/json

• previewsstring

  one of off, team, password

• productionboolean
• options_passthroughboolean
• exceptionsstring[]

  0–20 items

• passwordstring

  8–128 characters

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/functions/my-api/protection" \
  -H "Authorization: Bearer $KEY" \
  -d '{"previews":"off","production":true,"options_passthrough":true,"exceptions":["…"],"password":"…"}'

Create the bypass token#

A token for automation that skips protection, sent as the x-protection-bypass header or query parameter (the query parameter also sets a cookie). {token, hint, header}; the token is shown only in this answer and replaces the earlier one.

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

Errors

Example

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

Delete the bypass token#

{deleted: true}.

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

Errors

Example

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

Sign every visitor out#

Sign-in, password and link cookies stop working; visitors sign in again. {signed_out: true}.

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

Errors

Example

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

List shareable links#

{links: [{id, label, hint, state: active|expired|revoked, expires_at, created_at, created_by, revoked_at}]}.

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

Errors

Example

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

Create a shareable link#

A link that opens a protected deployment without signing in until it expires. expires_in_hours 1 to 2160 (default 24); url one of the project's addresses (default production). Answers with the link and its url, which carries the token and is shown only now. Pro.

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 bodyapplication/json

• labelstring

  up to 100 characters

• expires_in_hoursnumber

  1–2160

• urlstring

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/share-links" \
  -H "Authorization: Bearer $KEY" \
  -d '{"label":"…","expires_in_hours":1,"url":"https://example.com"}'

Revoke a shareable link#

The link and the visits that came through it stop at once. {revoked: true}.

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

Response

Errors

Example

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

Get promotion and version settings#

{auto_promote, skew_protection, skew_hours, production_version, deployment_ids, candidates: [{version, url, releasing, build, commit, message, since}], release, pinned: [{version, url}]}.

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

Errors

Example

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

Set promotion and version settings#

auto_promote: false = deploy without promoting: a production build becomes a candidate at rel-<version>--<name> and goes live only when promoted or released. skew_protection keeps an open page on the version it came from for skew_hours (1 to 168, default 12).

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 bodyapplication/json

• auto_promoteboolean
• skew_protectionboolean
• skew_hoursinteger

  1–168

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/functions/my-api/routing" \
  -H "Authorization: Bearer $KEY" \
  -d '{"auto_promote":true,"skew_protection":true,"skew_hours":1}'

Promote a version#

Make version (or the version of build) live in production at once. Ends a gradual release. {name, active_version, url}.

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 bodyapplication/json

• versioninteger
• buildstring (uuid)

Response

Errors

Example

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

List gradual releases#

{releases: [Release], active} newest first. A Release: {number, status: active|completed|stopped|superseded, percent, version, from_version, steps, step, next_step_at, error_rate, min_requests, end_reason, url, started_by, started_at, changed_at, ended_at}.

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

Errors

Example

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

Start a gradual release#

Send percent (default: the first step, or 10) of production traffic to version (or build). Each visitor stays on one side (a cookie). steps: percentages ending at 100, e.g. [10, 25, 50, 100], or {percent, after_minutes} objects; with every_minutes the steps run on a schedule, else by hand. The release stops by itself when more than error_rate (default 0.05) of the version's requests fail, once it has min_requests (default 50).

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 bodyapplication/json

• versioninteger
• buildstring (uuid)
• stepsany[]

  0–12 items

• every_minutesnumber

  0–10080

• percentinteger

  1–99

• error_ratenumber

  at most 1

• min_requestsinteger

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/functions/my-api/releases" \
  -H "Authorization: Bearer $KEY" \
  -d '{"version":1,"build":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","steps":[],"every_minutes":0,"percent":1,"error_rate":1,"min_requests":1}'

Get a release#

A Release (current for the active one) with metrics: {series: [{version, minute, requests, errors, static_requests}], totals: [{version, requests, errors, error_rate, static_requests}]} since it started.

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

• numberstringpathrequired

  a release number, or current

Response

Errors

Example

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

Set the release's share#

{percent} 1 to 100; 100 makes the version production and completes the release. Answers with the Release.

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 bodyapplication/json

• percentintegerrequired

  1–100

Response

Errors

Example

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

Next step#

The plan's next step (after the last: production). Answers with the Release.

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

Errors

Example

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

Stop the release#

All traffic back to production at once; the version stays at its own address, waiting. Answers with the Release.

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

Errors

Example

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

Get deployment protection#

Who may open previews (off, team: members who sign in, password) and whether production is protected too; exceptions (domain names never protected), options_passthrough (OPTIONS requests pass, for CORS preflight), password_set, the bypass token's hint, the shareable links, and pro (the password and links are Pro).

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

Errors

Example

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

Set deployment protection#

Any of previews (off, team, password), production, options_passthrough, exceptions (20 at most), password (8 to 128 characters; needed the first time password is chosen; changing it signs everyone out). Answers like GET.

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 bodyapplication/json

• previewsstring

  one of off, team, password

• productionboolean
• options_passthroughboolean
• exceptionsstring[]

  0–20 items

• passwordstring

  8–128 characters

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/apps/my-api/protection" \
  -H "Authorization: Bearer $KEY" \
  -d '{"previews":"off","production":true,"options_passthrough":true,"exceptions":["…"],"password":"…"}'

Create the bypass token#

A token for automation that skips protection, sent as the x-protection-bypass header or query parameter (the query parameter also sets a cookie). {token, hint, header}; the token is shown only in this answer and replaces the earlier one.

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

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/protection/bypass" \
  -H "Authorization: Bearer $KEY"

Delete the bypass token#

{deleted: true}.

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

Errors

Example

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

Sign every visitor out#

Sign-in, password and link cookies stop working; visitors sign in again. {signed_out: true}.

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

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/protection/sign-out" \
  -H "Authorization: Bearer $KEY"

List shareable links#

{links: [{id, label, hint, state: active|expired|revoked, expires_at, created_at, created_by, revoked_at}]}.

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

Errors

Example

curl "https://api.ibel.ai/v1/apps/my-api/share-links" \
  -H "Authorization: Bearer $KEY"

Create a shareable link#

A link that opens a protected deployment without signing in until it expires. expires_in_hours 1 to 2160 (default 24); url one of the project's addresses (default production). Answers with the link and its url, which carries the token and is shown only now. Pro.

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 bodyapplication/json

• labelstring

  up to 100 characters

• expires_in_hoursnumber

  1–2160

• urlstring

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/share-links" \
  -H "Authorization: Bearer $KEY" \
  -d '{"label":"…","expires_in_hours":1,"url":"https://example.com"}'

Revoke a shareable link#

The link and the visits that came through it stop at once. {revoked: true}.

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

Response

Errors

Example

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

Get promotion and version settings#

{auto_promote, skew_protection, skew_hours, production_version, deployment_ids, candidates: [{version, url, releasing, build, commit, message, since}], release, pinned: [{version, url}]}.

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

Errors

Example

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

Set promotion and version settings#

auto_promote: false = deploy without promoting: a production build becomes a candidate at rel-<version>--<name> and goes live only when promoted or released. skew_protection keeps an open page on the version it came from for skew_hours (1 to 168, default 12).

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 bodyapplication/json

• auto_promoteboolean
• skew_protectionboolean
• skew_hoursinteger

  1–168

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/apps/my-api/routing" \
  -H "Authorization: Bearer $KEY" \
  -d '{"auto_promote":true,"skew_protection":true,"skew_hours":1}'

Promote a version#

Make version (or the version of build) live in production at once. Ends a gradual release. {name, active_version, url}.

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 bodyapplication/json

• versioninteger
• buildstring (uuid)

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/promote" \
  -H "Authorization: Bearer $KEY" \
  -d '{"version":1,"build":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f"}'

List gradual releases#

{releases: [Release], active} newest first. A Release: {number, status: active|completed|stopped|superseded, percent, version, from_version, steps, step, next_step_at, error_rate, min_requests, end_reason, url, started_by, started_at, changed_at, ended_at}.

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

Errors

Example

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

Start a gradual release#

Send percent (default: the first step, or 10) of production traffic to version (or build). Each visitor stays on one side (a cookie). steps: percentages ending at 100, e.g. [10, 25, 50, 100], or {percent, after_minutes} objects; with every_minutes the steps run on a schedule, else by hand. The release stops by itself when more than error_rate (default 0.05) of the version's requests fail, once it has min_requests (default 50).

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 bodyapplication/json

• versioninteger
• buildstring (uuid)
• stepsany[]

  0–12 items

• every_minutesnumber

  0–10080

• percentinteger

  1–99

• error_ratenumber

  at most 1

• min_requestsinteger

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/releases" \
  -H "Authorization: Bearer $KEY" \
  -d '{"version":1,"build":"8c1e0c55-1f2a-4d3b-9e8f-0a1b2c3d4e5f","steps":[],"every_minutes":0,"percent":1,"error_rate":1,"min_requests":1}'

Get a release#

A Release (current for the active one) with metrics: {series: [{version, minute, requests, errors, static_requests}], totals: [{version, requests, errors, error_rate, static_requests}]} since it started.

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

• numberstringpathrequired

  a release number, or current

Response

Errors

Example

curl "https://api.ibel.ai/v1/apps/my-api/releases/1405-000001" \
  -H "Authorization: Bearer $KEY"

Set the release's share#

{percent} 1 to 100; 100 makes the version production and completes the release. Answers with the Release.

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 bodyapplication/json

• percentintegerrequired

  1–100

Response

Errors

Example

curl -X PATCH "https://api.ibel.ai/v1/apps/my-api/releases/current" \
  -H "Authorization: Bearer $KEY" \
  -d '{"percent":1}'

Next step#

The plan's next step (after the last: production). Answers with the Release.

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

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/releases/current/advance" \
  -H "Authorization: Bearer $KEY"

Stop the release#

All traffic back to production at once; the version stays at its own address, waiting. Answers with the Release.

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

Errors

Example

curl -X POST "https://api.ibel.ai/v1/apps/my-api/releases/current/stop" \
  -H "Authorization: Bearer $KEY"

Sign in to a protected deployment#

Used by the dashboard's sign-in page for team protection: {host, return} → {redirect}, the deployment's address with a one-time hand-over that becomes the visitor's cookie. The caller must be a member of the team that owns it.

Request bodyapplication/json

• hoststringrequired
• returnstringrequired

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/protection/grant" \
  -H "Authorization: Bearer $KEY" \
  -d '{"host":"…","return":"https://example.com"}'

Open a password-protected deployment#

Used by the sign-in page for password protection: {host, return, password} → {redirect}. No key needed; 20 tries a minute per project.

Request bodyapplication/json

• hoststringrequired
• returnstringrequired
• passwordstringrequired

Response

Errors

Example

curl -X POST "https://api.ibel.ai/v1/protection/password" \
  -d '{"host":"…","return":"https://example.com","password":"…"}'