# Use the Heroic Cloud API

**URL:** https://heroiclabs.com/docs/heroic-cloud/api/use-the-api/
**Summary:** Authenticate as a service user, understand which operations are available to you, and work through the requests automation reaches for most often.
**Keywords:** service users, api, heroic cloud, authentication, curl
**Categories:** heroic-cloud, api, service-users

---


# Use the Heroic Cloud API

The Heroic Cloud API is the programmatic equivalent of the Heroic Cloud dashboard. [Service users](../../access-control/#service-users) reach the subset of it built for automation: inspecting builders, deployments, and titles, updating their configuration, and triggering builds.

This guide covers authenticating, what's available once you have, and the requests automation reaches for most often. For the complete endpoint specification, see [Service users API](../service-users/).

## Base URL

Every endpoint sits under `https://cloud.heroiclabs.com`, prefixed with `/v3`.

## Authenticate

Service users authenticate with HTTP Basic. The username joins the service user's name and your organization name as `<service-user>@<organization>`. The password is the service user's secret:

```bash
Authorization: Basic <base64(<service-user>@<organization>:<secret>)>
```

Pass both to `curl -u` and let it encode the header for you:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/maintenance" \
  -u "<service-user>@<organization>:<secret>"
```

To build the header yourself, base64 encode the credential string:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/maintenance" \
  -H "Authorization: Basic $(echo -n '<service-user>@<organization>:<secret>' | base64)"
```

Both forms are equivalent. Prefer `-u` in scripts, since it avoids a subshell and won't wrap long credentials across lines.

Service users have no password or SSO login, so the secret is their only credential. Reveal and rotate it from the dashboard, and store it in your CI provider's secret store rather than in your repository.

To create a service user and scope its permissions, see [Access control](../../access-control/).

## What service users can do

Service users read, update, and trigger. Creating and deleting resources stays with human users, so no `POST` that provisions a resource and no `DELETE` is available to a service user.

{{< table name="heroic-cloud.concepts.api.use-the-api.service-user-actions" >}}

Authentication and permissions are separate checks. Valid credentials only get the request as far as the permission model, which applies to service users exactly as it does to regular users. Scope each service user to the minimum it needs: a CI/CD service user typically needs only **Trigger** on the relevant builder.

{{< note "important" >}}
Deployment logs and metrics aren't available through this API. Use the [log exporting](../../operations/log-exporting/) and [metric exporting](../../operations/metric-exporting/) add-ons, which ship data to an S3 bucket your systems can read.
{{< /note >}}

## Handle errors

Errors return a JSON body with a numeric `code` and a `message`.

{{< table name="heroic-cloud.concepts.api.use-the-api.error-codes" >}}

## Read enum values

Responses serialize enums as **numbers**, not as the names the specification lists. A completed build returns `"status": 2`, not `"status": "OPERATION_STATUS_DONE"`. Compare against the number.

`OperationStatus` governs build and deployment progress:

{{< table name="heroic-cloud.concepts.api.use-the-api.operation-status" >}}

Other enums follow the same pattern: the specification lists names in value order, starting at `0`.

## Trigger a build

Trigger a Nakama builder and build the tip of a branch:

```sh
curl -X POST \
  "https://cloud.heroiclabs.com/v3/organization/<organization>/builder/nakama/<builder>/trigger" \
  -u "<service-user>@<organization>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'
```

The request body is required, though every field in it is optional. Send `{}` to build the builder's configured defaults. Set `commit` to build a specific revision, `branch` to build the tip of a branch, and `nakama_image` to override the Nakama base image.

A `200` response returns the builder, including a `last_build` object.

**Reference**: [`TriggerNakamaBuilder`](../service-users/#/HeroicCloudService/TriggerNakamaBuilder)

## Wait for a build to finish

Triggering starts a build without waiting for it. Poll the builder and read `last_build.status`:

```sh
curl -s \
  "https://cloud.heroiclabs.com/v3/organization/<organization>/builder/nakama/<builder>" \
  -u "<service-user>@<organization>:<secret>" \
  | jq -r '.last_build.status'
```

Poll until the status leaves `1`. On `2`, read `last_build.image` for the image the build produced, which is what you deploy. On `3`, the build failed.

For a complete pipeline that triggers a build, waits for it, and deploys the result, see the [CI/CD guide](../../titles/cicd/).

**Reference**: [`GetNakamaBuilder`](../service-users/#/HeroicCloudService/GetNakamaBuilder)

## Inspect builders and deployments

List the Nakama builders your service user can see:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/builder/nakama" \
  -u "<service-user>@<organization>:<secret>"
```

List Nakama deployments, and Satori deployments, with the matching endpoints:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/deployment/nakama" \
  -u "<service-user>@<organization>:<secret>"

curl "https://cloud.heroiclabs.com/v3/organization/<organization>/deployment/satori" \
  -u "<service-user>@<organization>:<secret>"
```

Append the resource name to the collection path to fetch a single resource, for example `/deployment/nakama/<deployment>`.

**Reference**: [`ListNakamaBuilders`](../service-users/#/HeroicCloudService/ListNakamaBuilders), [`ListNakamaDeployments`](../service-users/#/HeroicCloudService/ListNakamaDeployments), [`ListSatoriDeployments`](../service-users/#/HeroicCloudService/ListSatoriDeployments), [`GetNakamaDeployment`](../service-users/#/HeroicCloudService/GetNakamaDeployment)

## Browse a builder's repository

Before triggering a build, list what's available to build. Branches:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/builder/nakama/<builder>/branch" \
  -u "<service-user>@<organization>:<secret>"
```

Tags, and commits on a given branch:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/builder/nakama/<builder>/tag" \
  -u "<service-user>@<organization>:<secret>"

curl -G "https://cloud.heroiclabs.com/v3/organization/<organization>/builder/nakama/<builder>/commits" \
  -u "<service-user>@<organization>:<secret>" \
  -d branch=main
```

**Reference**: [`ListNakamaBuilderRepositoryBranches`](../service-users/#/HeroicCloudService/ListNakamaBuilderRepositoryBranches), [`ListNakamaBuilderRepositoryTags`](../service-users/#/HeroicCloudService/ListNakamaBuilderRepositoryTags), [`ListNakamaBuilderCommits`](../service-users/#/HeroicCloudService/ListNakamaBuilderCommits)

## List built images

Fetch the images a builder has produced, which is useful for picking a specific one to deploy:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/image" \
  -u "<service-user>@<organization>:<secret>"
```

**Reference**: [`ListImages`](../service-users/#/HeroicCloudService/ListImages)

## Check maintenance and billing

Query scheduled maintenance for your organization:

```sh
curl "https://cloud.heroiclabs.com/v3/organization/<organization>/maintenance" \
  -u "<service-user>@<organization>:<secret>"
```

Fetch billing for a period, or a single invoice by ID:

```sh
curl -G "https://cloud.heroiclabs.com/v3/organization/<organization>/billing" \
  -u "<service-user>@<organization>:<secret>" \
  -d period_month_year=<month-year>

curl "https://cloud.heroiclabs.com/v3/organization/<organization>/billing/invoice/<invoice-id>" \
  -u "<service-user>@<organization>:<secret>"
```

**Reference**: [`ListMaintenance`](../service-users/#/HeroicCloudService/ListMaintenance), [`GetBilling`](../service-users/#/HeroicCloudService/GetBilling), [`GetBillingInvoice`](../service-users/#/HeroicCloudService/GetBillingInvoice)

## See also

* [Service users API](../service-users/) for the full endpoint specification.
* [Access control](../../access-control/) for creating service users and scoping their permissions.
* [CI/CD guide](../../titles/cicd/) for a complete GitHub Actions pipeline.