API

Basics

A deploy is three calls: start it, send its log in batches while it runs, and finish it. Each answer carries the deploy's id, which the next calls name.

Start a deploy

POST/deploys

A deploy or a rollback starts. Only app and environment are needed: the rest is what the machine says about itself. A new app adds the app.

curl https://services.my-beast.com/deploys/api/v1/deploys \
  -H "Authorization: Bearer $MYBEAST_DEPLOYS_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "app=shop" \
  --data-urlencode "environment=staging" \
  --data-urlencode "command=make deploy:staging" \
  --data-urlencode "commit=$(git rev-parse HEAD)" \
  --data-urlencode "actor_email=$(git config user.email)"

{
  "id": "019a3f2e-7b1c-7d4e-9a51-3c2b8e6f0a12",
  "number": 12,
  "title": "Deploy #12",
  "app": "shop",
  "environment": "staging",
  "kind": "deploy",
  "status": "running",
  "url": "https://services.my-beast.com/acme/storefront/deploys/apps/shop/deploys/12",
  "warning": null
}

url is the deploy's page. warning is a sentence for the person when another deploy is still running in the environment, such as Deploy #11 by Anna is still running here (started 3 minutes ago). It never stops this one.

Send the log

POST/deploys/{id}/lines?offset={offset}

The body is the log's bytes from offset on, as text/plain: 0 for the first batch, then the received of the last answer. Send whole lines while the deploy runs; the last line may lack its newline at the end.

• A batch is at most 512 KB.
• A batch sent again after a lost answer is not kept twice: bytes Deploys has already are skipped.
• An empty body says the machine is still there. Without one for 10 minutes, the deploy is marked lost; a batch after that takes it up again.
• Colours and cursor codes are taken out, a line over 2,000 characters is cut, and lines past 50,000 are counted, not kept.

curl "https://services.my-beast.com/deploys/api/v1/deploys/$DEPLOY_ID/lines?offset=0" \
  -H "Authorization: Bearer $MYBEAST_DEPLOYS_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: text/plain" \
  --data-binary @deploy.log

{
  "received": 18342,
  "lines": 214,
  "status": "running"
}

received is the bytes Deploys has of the log, lines its lines so far. A batch that does not start where the log stands, or one after the deploy ended, is answered 409 with the byte to send from:

{
  "message": "The log stands at byte 16384: send from there.",
  "expected": 16384
}

Finish a deploy

POST/deploys/{id}/finish

How the command ended, as the machine saw it. The first finish stands: another changes nothing, except on a deploy that was marked lost meanwhile.

curl https://services.my-beast.com/deploys/api/v1/deploys/$DEPLOY_ID/finish \
  -H "Authorization: Bearer $MYBEAST_DEPLOYS_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "status=succeeded" \
  --data-urlencode "exit_code=0" \
  --data-urlencode "duration_seconds=92"

{
  "id": "019a3f2e-7b1c-7d4e-9a51-3c2b8e6f0a12",
  "number": 12,
  "title": "Deploy #12",
  "app": "shop",
  "environment": "staging",
  "kind": "deploy",
  "status": "succeeded",
  "url": "https://services.my-beast.com/acme/storefront/deploys/apps/shop/deploys/12",
  "release": "20261101-101500-a1b2c3d",
  "took": "1m 32s"
}

release is the name the deploy ended with, found as The line that names the release says. A deploy that succeeded becomes what is live in its environment and, unless it is a rollback, names its release in Errors when the app has an Errors key. One that failed is told to the project's people.

Read an app

GET/apps/{app}?environment={environment}

An app's saved commands, and what is live in an environment: what mybeast-deploy status prints. environment is optional; with it, the commands have {env} filled in.

curl "https://services.my-beast.com/deploys/api/v1/apps/shop?environment=staging" \
  -H "Authorization: Bearer $MYBEAST_DEPLOYS_KEY" \
  -H "Accept: application/json"

{
  "app": "shop",
  "name": "Shop",
  "environment": "staging",
  "deploy_command": "make deploy:staging",
  "rollback_command": "make rollback:staging",
  "live_release": "20261101-101500-a1b2c3d",
  "live_commit": "a1b2c3d4",
  "live_title": "Deploy #12",
  "live_by": "Anna Virtanen",
  "live_at": "1.11. 10:16 (2 hours ago)",
  "last_status": "succeeded"
}

The live_ fields are null when nothing is live there yet, and last_status is how the last deploy there ended. live_at is written for a person, in the service's time zone.

Statuses

A machine finishes a deploy with succeeded, failed or cancelled; lost is Deploys' own word.

Errors

An error answers with a message in words a person can act on. mybeast-deploy prints it, and runs the deploy all the same.

For example, an environment the project does not have:

{
  "message": "Storefront has no environment “prd”: its environments are staging and production. A project admin adds one at https://id.my-beast.com/…, or --env names one of these."
}