#getBuildLabels

Read a build's current custom labels. Labels are stored on the build and are also included in getBuild responses and todesktop builds --format=json output when present.

GET /v1/getBuildLabels?appId={appId}&buildId={buildId}
Authorization: Bearer <access-token>

Supply your ToDesktop app ID and the build ID. Both query parameters are required.

Uses the shared API authentication rules. The caller must own the app or be a collaborator with current, accepted app access. Read-only access is sufficient.

#Response

All three label endpoints return the same response shape, with the current label map. Builds without labels return an empty object.

{
  "appId": "your-app-id",
  "buildId": "your-build-id",
  "customLabels": {
    "e2e": {
      "text": "Passed",
      "color": "green",
      "url": "https://github.com/example/app/actions/runs/123",
      "createdAt": "2026-09-09T10:00:00.000Z",
      "updatedAt": "2026-09-09T10:05:00.000Z",
      "createdBy": { "userId": "user-id", "displayName": "Example User", "via": "api" },
      "updatedBy": { "userId": "user-id", "displayName": "Example User", "via": "api", "tokenDescription": "Nightly E2E" }
    }
  }
}

createdAt, updatedAt, createdBy and updatedBy are assigned by the server. Timestamps use ISO 8601 UTC. Attribution contains the user's ID and display name, and via: api for changes made with an access token, personal access token or the CLI, or web for changes made in the ToDesktop dashboard. Personal tokens also include their description.

Labels are informational and do not affect whether a build can be released. They remain on the same build when packaging is rerun. Cloned builds start without labels.

Build-finished and release webhooks (both full and partial releases) include customLabels from the event's build snapshot, or {} when no labels exist. Later label edits do not modify earlier payloads or trigger additional webhooks. Release webhook signatures cover the labels as part of the complete JSON payload. Test webhooks include an empty label map.

#Errors

Label endpoints use structured errors:

{ "error": { "reason": "not-found", "message": "Build not found." } }

For authentication and permission errors, see the shared error handling reference.

#Example

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://api.todesktop.com/v1/getBuildLabels?appId=your-app-id&buildId=your-build-id"