Kibo Hosted Headless API

When Kibo hosts your headless storefront, the Hosted Headless API lets you check and manage that application. You can:

List the build jobs for a branch and check their status.
Read the log for each step of a build.
Download the runtime logs your application writes while it is live.
Manage the environment variables and secrets for a branch.
Start a new build of a branch.

The Kibo Headless CLI calls these same APIs from the command line.

Before You Start

Your site must have a Kibo Hosted Headless application. Every call is scoped to the site in the request. If that site has no hosted application, the API returns a 404 error.
Authenticate each request. Send an OAuth 2.0 access token in the Authorization header. See How to Authenticate.
Identify the tenant and site. Use your tenant host, such as https://t1000000.sb.usc1.gcp.kibocommerce.com, and send the x-vol-site header. See Additional Headers.
Work by branch. Builds, environment variables, and secrets belong to a source code branch, such as main. Pass the branch name in the path.

Each operation requires a behavior on the calling application or user:

Operations	Required behavior
List build jobs, get a build log, get runtime logs	Developer Asset Read
List environment variables	Headless Env Read
Set or delete environment variables	Headless Env Write
List secrets	Headless Secret Read
Set or delete secrets	Headless Secret Write
Trigger a build	Headless Build Trigger

API Summary

All paths are relative to https://{tenant-host}/api.

Operation	Method and path
Get Application Build Jobs	`GET /platform/appdev/headless-app/builds/{branchName}`
Get Application Build Log	`GET /platform/appdev/headless-app/builds/{branchName}/logs/{jobId}`
Trigger Build	`POST /platform/appdev/headless-app/builds/{branchName}/trigger`
Get Runtime Logs	`GET /platform/appdev/headless-app/logs/runtime`
Get Environment Variables	`GET /platform/appdev/headless-app/env/{branchName}`
Put Environment Variable	`PUT /platform/appdev/headless-app/env/{branchName}`
Delete Environment Variable	`DELETE /platform/appdev/headless-app/env/{branchName}/{variableName}`
Get Secrets	`GET /platform/appdev/headless-app/secrets/{branchName}`
Put Secret	`PUT /platform/appdev/headless-app/secrets/{branchName}`
Delete Secret	`DELETE /platform/appdev/headless-app/secrets/{branchName}/{secretName}`

Build Jobs

Each build of a branch is a build job. List the jobs for a branch to see their status and to find the jobId you need for the build log.

GET /api/platform/appdev/headless-app/builds/main?maxResults=10
Authorization: Bearer {access_token}
x-vol-site: 10000

Query parameter	Description
`maxResults`	Number of jobs to return. Defaults to 20. The maximum is 100.
`nextToken`	The `nextToken` value from the previous response, to get the next page.

Example response:

{
  "nextToken": "eyJuZXh0IjoiMTIifQ==",
  "jobs": [
    {
      "jobId": "12",
      "status": "SUCCEED",
      "commitId": "a3f9e12c",
      "commitTime": "2026-01-15T14:32:00Z",
      "startTime": "2026-01-15T14:33:01Z",
      "endTime": "2026-01-15T14:40:45Z"
    },
    {
      "jobId": "11",
      "status": "FAILED",
      "commitId": "b7d2a44e",
      "commitTime": "2026-01-14T09:10:00Z",
      "startTime": "2026-01-14T09:11:02Z",
      "endTime": "2026-01-14T09:14:30Z"
    }
  ]
}

Field	Description
`nextToken`	Pass this value as `nextToken` to get the next page. It is absent on the last page.
`jobs[].jobId`	The build job identifier. Use it to get the build log.
`jobs[].status`	The build status. See Build Statuses.
`jobs[].commitId`	The commit the job built.
`jobs[].commitTime`	When that commit was made.
`jobs[].startTime`	When the build started.
`jobs[].endTime`	When the build finished.

Build Statuses

Build jobs and build steps report one of these statuses:

Status	Meaning
`PENDING`	The job is queued and has not started.
`PROVISIONING`	The build environment is being prepared.
`RUNNING`	The job is running.
`SUCCEED`	The job finished successfully.
`FAILED`	The job finished with an error.
`CANCELLING`	A cancel was requested and the job is stopping.
`CANCEL`	The job was cancelled.

The cancelled status is CANCEL, not CANCELLED. Match on the exact value when you check for it.

Build Logs

A build runs in steps. The build log lists each step with its status and a link to that step’s output.

GET /api/platform/appdev/headless-app/builds/main/logs/11
Authorization: Bearer {access_token}
x-vol-site: 10000

Example response:

{
  "jobId": "11",
  "steps": [
    {
      "stepName": "BUILD",
      "status": "FAILED",
      "logUrl": "https://logs.example.com/11/build",
      "startTime": "2026-01-14T09:11:02Z",
      "endTime": "2026-01-14T09:14:30Z"
    }
  ]
}

Field	Description
`jobId`	The build job this log belongs to.
`steps[].stepName`	The name of the build step.
`steps[].status`	The step status. Uses the same values as Build Statuses.
`steps[].logUrl`	A temporary URL to download the output of the step.
`steps[].startTime`	When the step started.
`steps[].endTime`	When the step finished.

To find out why a build failed:

List the build jobs for the branch and find the job with status FAILED.
Get the build log for that jobId.
Find the step with status FAILED and download its logUrl.
Compare the job’s commitId with your source history to see what changed.

Runtime Logs

Runtime logs hold the output your application writes while it is live. They are stored as files grouped by date and hour. Each call returns a page of files with a download link for each one.

GET /api/platform/appdev/headless-app/logs/runtime?prefix=2026-01-15&maxResults=50
Authorization: Bearer {access_token}
x-vol-site: 10000

Query parameter	Description
`prefix`	Optional date filter in the format `yyyy`, `yyyy-mm`, `yyyy-mm-dd`, or `yyyy-mm-dd-hh`. Any other format returns a `400` error.
`maxResults`	Number of log files to return. Defaults to 300. The maximum is 1000.
`nextToken`	The `nextToken` value from the previous response, to get the next page.

Examples of prefix:

`prefix`	Returns
`2026`	All logs from 2026
`2026-01`	All logs from January 2026
`2026-01-15`	All logs from January 15, 2026
`2026-01-15-14`	All logs from the 14:00 hour on January 15, 2026

Example response:

{
  "nextToken": "1ABCdefGHIjkl%2BmnoPQR%3D",
  "prefix": "2026-01-15",
  "maxResults": 50,
  "isTruncated": true,
  "logs": [
    {
      "key": "<application-id>/2026/01/15/14/<file-name>",
      "logUrl": "https://logs.example.com/runtime-log-1",
      "size": 204800,
      "lastModified": "2026-01-15T15:00:00Z"
    }
  ]
}

Field	Description
`nextToken`	Pass this value as `nextToken` to get the next page.
`prefix`	The date filter used for this request.
`maxResults`	The page size used for this request.
`isTruncated`	`true` when more log files match. Use `nextToken` to get them.
`logs[].key`	The log file identifier. The path in the key includes the year, month, day, and hour.
`logs[].logUrl`	A URL to download the log file. It expires 4 hours after the response is created.
`logs[].size`	The file size in bytes.
`logs[].lastModified`	When the file was last written.

Download log files soon after you list them. If a logUrl has expired, call Get Runtime Logs again to get a new one.

To read all pages, repeat the request with the nextToken from each response until isTruncated is false. The runtime logs nextToken is already URL-encoded, so add it to the query string as returned:

GET /api/platform/appdev/headless-app/logs/runtime?prefix=2026-01-15&nextToken=1ABCdefGHIjkl%2BmnoPQR%3D
Authorization: Bearer {access_token}
x-vol-site: 10000

Environment Variables

Environment variables are plaintext settings for a branch, such as an API host or a feature switch. The API returns their values, so do not store passwords or keys in them. Use secrets for those. List the variables for a branch:

GET /api/platform/appdev/headless-app/env/main
Authorization: Bearer {access_token}
x-vol-site: 10000

{
  "totalCount": 2,
  "items": [
    { "name": "KIBO_API_HOST", "value": "t1000000.sb.usc1.gcp.kibocommerce.com" },
    { "name": "NEXT_PUBLIC_SITE_NAME", "value": "My Store" }
  ]
}

Create or update a variable. If a variable with that name exists on the branch, its value is replaced.

PUT /api/platform/appdev/headless-app/env/main
Authorization: Bearer {access_token}
x-vol-site: 10000
Content-Type: application/json

{
  "name": "NEXT_PUBLIC_SITE_NAME",
  "value": "My Store"
}

The response returns the name, value, and lastModified time of the variable. Delete a variable by name. A successful delete returns 204 No Content. If the variable does not exist on the branch, the API returns 404.

DELETE /api/platform/appdev/headless-app/env/main/NEXT_PUBLIC_SITE_NAME
Authorization: Bearer {access_token}
x-vol-site: 10000

Secrets

Secrets are encrypted values for a branch, such as API keys and shared secrets. You can set and delete a secret, but the API never returns its value. Listing secrets returns only their names and when they last changed.

GET /api/platform/appdev/headless-app/secrets/main
Authorization: Bearer {access_token}
x-vol-site: 10000

{
  "totalCount": 1,
  "items": [
    { "name": "KIBO_SHARED_SECRET", "lastModified": "2026-01-15T14:32:00Z" }
  ]
}

Create or update a secret:

PUT /api/platform/appdev/headless-app/secrets/main
Authorization: Bearer {access_token}
x-vol-site: 10000
Content-Type: application/json

{
  "name": "KIBO_SHARED_SECRET",
  "value": "your-secret-value"
}

The response returns the name and lastModified time, without the value. Delete a secret by name. A successful delete returns 204 No Content. If the secret does not exist on the branch, the API returns 404.

DELETE /api/platform/appdev/headless-app/secrets/main/KIBO_SHARED_SECRET
Authorization: Bearer {access_token}
x-vol-site: 10000

Name and Value Rules

These rules apply to both environment variables and secrets:

The name must start with a letter or underscore and contain only letters, digits, and underscores.
The name can be up to 128 characters.
The value is required and can be up to 4096 characters.

A request that breaks these rules returns a 400 error.

Trigger a Build

Start a new build of a branch, for example after you change its environment variables or secrets. The request has no body.

POST /api/platform/appdev/headless-app/builds/main/trigger
Authorization: Bearer {access_token}
x-vol-site: 10000

Example response:

{
  "jobId": "13",
  "branchName": "main",
  "status": "PENDING",
  "startTime": "2026-01-15T16:02:11Z"
}

Use the jobId to follow the build. List the build jobs for the branch to check its status, and get its build log when it finishes. If the branch does not exist, the API returns 404. If the application already has the maximum number of builds running, the request fails with an error that says so. Wait for a running build to finish, then try again.

Developers

API reference

AI Tools

Before You Start

API Summary

Build Jobs

Build Statuses

Build Logs

Runtime Logs

Environment Variables

Secrets

Name and Value Rules

Trigger a Build

​Before You Start

​API Summary

​Build Jobs

​Build Statuses

​Build Logs

​Runtime Logs

​Environment Variables

​Secrets

​Name and Value Rules

​Trigger a Build

Before You Start

API Summary

Build Jobs

Build Statuses

Build Logs

Runtime Logs

Environment Variables

Secrets

Name and Value Rules

Trigger a Build