#ToDesktop API Reference

The ToDesktop API provides HTTP endpoints for checking release state, listing released builds, managing build labels, releasing builds, and controlling app download access.

#Base URL

All endpoints in this section are rooted at:

https://api.todesktop.com/v1

#Authentication

All protected endpoints use the same header:

Authorization: Bearer <access-token>

Supported credentials are:

• Account access tokens: ToDesktop CLI/account tokens.
• Personal access tokens (PATs): active tokens scoped to the target app.
• Firebase ID tokens: tokens issued for a ToDesktop user session.

The API identifies you from the token; no email is required in the request.

#App permissions

You must own the app or have accepted access to it. Personal tokens can only access their assigned apps and cannot grant more permissions than their owner has.

Account IP restrictions apply to protected endpoints. The request must satisfy the caller's allowlist and, for collaborators, the app owner's allowlist. These account restrictions are separate from an app's download-access policy.

#Endpoints

#Error Handling

Protected endpoints use these authentication and authorization statuses:

Error response formats depend on the endpoint. Authentication and authorization failures on getBuild and releaseBuild use a string-valued error:

{ "error": "Invalid bearer token." }

The download-access API and build-label APIs use structured errors:

{ "error": { "reason": "unauthenticated", "message": "Invalid bearer token." } }

Other errors may use a message and numeric code:

{
  "message": "Parameter appId is required in search params",
  "code": 1
}

See each endpoint's reference for additional errors and retry instructions.