setBuildLabel

Create or replace one custom label, identified by a stable key such as github-e2e. Other labels on the build are preserved, including when separate jobs update different keys concurrently.

POST /v1/setBuildLabel
Authorization: Bearer <access-token>
Content-Type: application/json
{
  "appId": "your-app-id",
  "buildId": "your-build-id",
  "key": "github-e2e",
  "label": {
    "text": "E2E passed",
    "color": "green",
    "url": "https://github.com/example/app/actions/runs/123",
    "description": "All end-to-end checks passed."
  }
}

Fields and limits

FieldRequiredRules
appId, buildIdYes1–128 letters, numbers, underscores or hyphens.
keyYes1–64 lowercase letters, numbers or hyphens; must start with a letter. todesktop- prefixes, constructor and prototype are reserved.
label.textYes1–40 Unicode code points after trimming surrounding whitespace.
label.colorYesgray, blue, green, orange, red or purple.
label.urlNoHTTPS URL, at most 2,048 characters, without embedded credentials.
label.descriptionNoAt most 240 Unicode code points.

The JSON request body must not exceed 16 KiB. Unknown fields are rejected, including server attribution fields. Each build can have up to ten labels; existing labels can still be updated at that limit.

Replacement and concurrency

Each set replaces all editable fields for that key. Omitting url or description removes its previous value. Creation metadata is retained, and update metadata records the authenticated caller. An identical set is a no-op, including its timestamps and attribution.

For simultaneous updates to the same key, the last committed update wins. There are no client-supplied revisions or conditional-write parameters. Retrying an older request after a newer update can overwrite that update; use one writer per key or distinct keys when jobs need independent results.

Updates to different keys preserve each other. The server retries conflicts internally; if contention persists, it returns 409 with reason aborted, and the client can retry.

The app owner and delegates with either build or release permission can write labels. Both legacy account tokens and active personal tokens scoped to the app are supported. Viewer-only users can read labels but cannot change them. No email or caller-supplied user ID is needed.

Returns HTTP 200 with { appId, buildId, customLabels }. See getBuildLabels for the full response and error contract.

Example

curl -X POST "https://api.todesktop.com/v1/setBuildLabel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"appId":"your-app-id","buildId":"your-build-id","key":"github-e2e","label":{"text":"E2E passed","color":"green"}}'
Previous getBuildLabels
Next removeBuildLabel