> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kibo Hosted Headless API

> Check builds, read build and runtime logs, manage environment variables and secrets, and trigger builds for a Kibo Hosted Headless application.

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](https://docs.kibocommerce.com/api-overviews/sdks-and-toolkits.md#clis-and-toolkits) 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](https://docs.kibocommerce.com/api-overviews/getting-started.md#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](https://docs.kibocommerce.com/api-overviews/getting-started.md#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](https://docs.kibocommerce.com/api-reference/headlessapp/get-application-build-jobs.md) | `GET /platform/appdev/headless-app/builds/{branchName}` |
| [Get Application Build Log](https://docs.kibocommerce.com/api-reference/headlessapp/get-application-build-log.md) | `GET /platform/appdev/headless-app/builds/{branchName}/logs/{jobId}` |
| [Trigger Build](https://docs.kibocommerce.com/api-reference/headlessapp/trigger-build.md) | `POST /platform/appdev/headless-app/builds/{branchName}/trigger` |
| [Get Runtime Logs](https://docs.kibocommerce.com/api-reference/headlessapp/get-runtime-logs.md) | `GET /platform/appdev/headless-app/logs/runtime` |
| [Get Environment Variables](https://docs.kibocommerce.com/api-reference/headlessapp/get-environment-variables.md) | `GET /platform/appdev/headless-app/env/{branchName}` |
| [Put Environment Variable](https://docs.kibocommerce.com/api-reference/headlessapp/put-environment-variable.md) | `PUT /platform/appdev/headless-app/env/{branchName}` |
| [Delete Environment Variable](https://docs.kibocommerce.com/api-reference/headlessapp/delete-environment-variable.md) | `DELETE /platform/appdev/headless-app/env/{branchName}/{variableName}` |
| [Get Secrets](https://docs.kibocommerce.com/api-reference/headlessapp/get-secrets.md) | `GET /platform/appdev/headless-app/secrets/{branchName}` |
| [Put Secret](https://docs.kibocommerce.com/api-reference/headlessapp/put-secret.md) | `PUT /platform/appdev/headless-app/secrets/{branchName}` |
| [Delete Secret](https://docs.kibocommerce.com/api-reference/headlessapp/delete-secret.md) | `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.

```http theme={null}
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:

```json theme={null}
{
  "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](#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. |

> [!NOTE]
>
> 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.

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

Example response:

```json theme={null}
{
  "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](#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:

1. List the build jobs for the branch and find the job with status `FAILED`.
2. Get the build log for that `jobId`.
3. Find the step with status `FAILED` and download its `logUrl`.
4. 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.

```http theme={null}
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:

```json theme={null}
{
  "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. |

> [!NOTE]
>
> 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:

```http theme={null}
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](#secrets) for those.

List the variables for a branch:

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

```json theme={null}
{
  "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.

```http theme={null}
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`.

```http theme={null}
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.

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

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

Create or update a secret:

```http theme={null}
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`.

```http theme={null}
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.

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

Example response:

```json theme={null}
{
  "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](#build-statuses), 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.