Build distribution

A distribution gives one tester group access to one release. It works independently of channel promotion: you can share a draft build privately without putting it on beta or stable. Testers find shared builds in the /t portal, and optional email notifications tell them a build is available.

All routes below begin with /api/v1/orgs/:orgId/apps/:appId/distributions. They require a GitHub dashboard session; API tokens, including admin tokens, do not authenticate these routes. The app must belong to the organization in the path.

Method and suffix	Minimum role	Success	Purpose
GET /	Viewer	200	List distributions, optionally for one release
POST /releases/:releaseId	Developer	200	Share a release with groups
DELETE /:distributionId	Developer	204	Withdraw one group share
GET /auto-rules	Viewer	200	List automatic rules
POST /auto-rules	Developer	201	Create a rule
DELETE /auto-rules/:ruleId	Developer	204	Delete a rule

Share a release

The release must belong to the app and must not be revoked. Each group ID must belong to the organization. Send 1–50 group IDs, optional whatToTest text of at most 4,000 characters, and notify (defaults to true):

POST /api/v1/orgs/org_123/apps/app_456/distributions/releases/rel_789
Content-Type: application/json

{
  "groupIds": ["tgr_android", "tgr_staff"],
  "whatToTest": "Check offline sync after updating from 1.3.",
  "notify": true
}

The response is { "distributions": [...], "notified": 12 }. Each distribution has id, releaseId, groupId, groupName, whatToTest, source (manual or auto), and createdAt. notified counts testers newly queued for email, not confirmed deliveries or installs.

One release can be shared with many groups. If it is shared with the same group again, the server updates that distribution's whatToTest text. Passing null or omitting the text clears it for that share. When notify is true, the server sends at most one build notification per tester per release, even if that tester belongs to several selected groups or you repeat the distribution call. Existing deliveries are not resent by this endpoint. The message uses whatToTest when present, otherwise the release notes; the email text is limited to the first 1,000 characters.

An unknown release returns 404 release_not_found; a revoked release returns 409 release_revoked; an unknown group returns 404 tester_group_not_found. Route schema errors, such as an empty groupIds array, return 400 as described in API conventions.

List and withdraw shares

GET / returns { "items": [...] } for every distribution of this app, sorted by group name. Add ?releaseId=rel_789 to see shares for one release. The route does not paginate. Use the id from a list item to withdraw it:

DELETE /api/v1/orgs/org_123/apps/app_456/distributions/dst_111

The response is 204 No Content. A tester loses access to that release through this group, but still sees it if another of their groups has an active distribution. Withdrawing a share does not recall email already sent. An unknown distribution ID returns 404 distribution_not_found.

Automatic distribution rules

An automatic rule pairs one app channel with one organization tester group. When a release is promoted to that channel, ReleaseDesk shares it with the group and requests email notification. The rule uses channel and group IDs, not their names:

POST /api/v1/orgs/org_123/apps/app_456/distributions/auto-rules
Content-Type: application/json

{"channelId":"chn_beta","groupId":"tgr_android"}

The 201 response includes id, groupId, groupName, channelId, channelName, and createdAt. GET /auto-rules returns { "items": [...] }, sorted by channel and group names. Creating an existing channel/group pair leaves the existing rule in place and returns it. An unknown channel returns 404 channel_not_found; an unknown group returns 404 tester_group_not_found.

Rules run after a successful promotion. They do not retroactively share releases already promoted before the rule was created. If the notification or distribution step fails, the promotion still succeeds, so check the distributions list when delivery is important. Delete a rule with DELETE /auto-rules/:ruleId (204). Deletion stops future automatic shares but does not withdraw distributions created earlier; withdraw those separately if needed.

Start with Testers and groups to create recipients, then follow Releases and channels to upload or promote a build.