View as Markdown

Use the Heroic Cloud API

The Heroic Cloud API is the programmatic equivalent of the Heroic Cloud dashboard. 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.

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:

1

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

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

1
2

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

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

1
2

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.

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.

ActionAvailableExamples
ReadYesList builders, get a deployment, list images, get an invoice
UpdateYesUpdate a builder, deployment, or title
TriggerYesTrigger a Nakama builder build
CreateNoCreate a builder, deployment, or title
DeleteNoDelete a builder, deployment, or title

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.

Deployment logs and metrics aren’t available through this API. For logs, use the log exporting add-on, which ships logs to an S3-compatible bucket Heroic Labs provisions for you. For metrics, use the metric exporting add-on. It provides a secure Prometheus endpoint you scrape, already aggregated across every Nakama node in the deployment.

Handle errors #

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

StatusMeaning
401Credentials are missing, malformed, or invalid. A disabled service user returns 401 as well, so a rejected credential that used to work may have been disabled rather than rotated.
403Credentials are valid, but the operation isn’t available to service users, or your permissions don’t cover it.

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:

ValueNameMeaning
0OPERATION_STATUS_UNSPECIFIEDNot set
1OPERATION_STATUS_IN_PROGRESSAccepted and running
2OPERATION_STATUS_DONECompleted successfully
3OPERATION_STATUS_FAILEDFailed permanently

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:

1
2
3
4
5

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

Wait for a build to finish #

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

1
2
3
4

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.

Reference: GetNakamaBuilder

Deploy an image #

Building and deploying are separate calls, so automation that builds doesn’t have to deploy. Change the image a Nakama deployment runs with a PUT:

1
2
3
4
5

curl -X PUT \
  "https://cloud.heroiclabs.com/v3/organization/<organization>/deployment/nakama/<deployment>" \
  -u "<service-user>@<organization>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{"image": "<image>"}'

The update is partial. Fields you leave out keep their current values. A body containing only image changes the running image and leaves CPU, memory, runtime variables, and every other setting untouched. Send only the fields you intend to change.

A 200 response means the update was accepted. Poll the deployment and read state.status to follow the deploy, using the same OperationStatus values as builds:

1
2
3
4

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

On 3, read state.errors for the reason. Deploying through the API uses the same rolling update as the dashboard. See Deploy downtime.

Reference: UpdateNakamaDeployment

Inspect builders and deployments #

List the Nakama builders your service user can see:

1
2

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:

1
2
3
4
5

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, ListNakamaDeployments, ListSatoriDeployments, GetNakamaDeployment

Browse a builder’s repository #

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

1
2

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

Tags, and commits on a given branch:

1
2
3
4
5
6

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, ListNakamaBuilderRepositoryTags, ListNakamaBuilderCommits

List built images #

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

1
2

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

Reference: ListImages

Check maintenance and billing #

Query scheduled maintenance for your organization:

1
2

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:

1
2
3
4
5
6

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, GetBilling, GetBillingInvoice

See also #