#setBuildLabel

Create or replace one custom label. A label's key names what it's about, such as e2e, and its text is the current result, such as Passed. Other labels on the build are preserved, including when separate jobs update different keys concurrently.

People with build or release permission can also add, change and remove labels from the Builds and build pages in the ToDesktop dashboard. Those changes are recorded with via: "web".

POST /v1/setBuildLabel
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "appId": "your-app-id",
  "buildId": "your-build-id",
  "key": "e2e",
  "label": {
    "text": "Passed",
    "color": "green",
    "url": "https://github.com/example/app/actions/runs/123",
    "description": "All end-to-end checks passed."
  }
}

#Fields and limits

Each build can have up to ten labels; existing labels can still be updated at that limit.

#Choosing keys

Think of the key as a question and the text as its current answer: qa might be Pending, then Passed or Failed. A build has at most one label per key, so setting a key again replaces its value.

• Use the same keys on every build, so results are easy to compare and filter. The dashboard shows each label with its key, like e2e · Passed, and suggests the values a key has had on other builds.
• Don't put build or run IDs in keys. Link to the run with url instead.
• Give each independent check its own key, such as e2e and unit-tests.
• If two systems report the same kind of result, include the system in the key, such as github-e2e and circleci-e2e, so they don't overwrite each other.

#Replacement and concurrency

Each request replaces the label for that key. Omitting url or description removes its previous value. Other labels remain unchanged.

When jobs update the same key, the last update wins. Use separate keys for independent results, and avoid retrying an older value after a newer update.

If simultaneous edits cause a 409 aborted response, retry the request.

Uses the shared API authentication rules. The app owner and collaborators with current app access and either build or release permission can write labels. Read-only collaborators can read labels but cannot change them.

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

#Example

Mark end-to-end tests as running when the job starts:

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":"e2e","label":{"text":"Running","color":"blue"}}'

Then replace it with the result when the job finishes:

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":"e2e","label":{"text":"Passed","color":"green","url":"https://github.com/example/app/actions/runs/123"}}'