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. Use the log exporting and metric exporting add-ons, which ship data to an S3 bucket your systems can read.

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

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 #