Upload & Release
Endpoints for uploading apps to Pgyer via API, including the three-step fast upload flow, HarmonyOS cert and Hsp uploads, and the legacy upload endpoint.
Every API endpoint for uploading apps to Pgyer. Prefer the fast upload flow — it's faster and more reliable.
API publishing follows the same account storage and historical-build cleanup rules. When storage is exceeded, automatic policies attempt to clear existing overage first. If insufficient space can be freed, or manual cleanup is selected, the API returns a failure result. Check code, message, and the final publishing status; a completed file transfer is not a successful publication. Archive installers needed for long-term use.
For help choosing between the API, CLI, CI/CD plugins, MCP, and Agent Skill, see Automated App Uploads and CI/CD Integration.
Fast Upload (New)
Reference implementation: https://github.com/PGYER/upload-app-api-example
Get a pre-upload URL: call getCOSToken to get the upload URL and signing params.
Upload the app file: POST the app as multipart/form-data to the URL returned in the previous step.
Poll for release status: call buildInfo until it returns success or failure.
Get an Upload Token
Returns the pre-upload URL and the signing params.
https://www.pgyer.com/apiv2/app/getCOSTokenRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| _api_key | String | Yes | API Key — see auth |
| buildType | String | Yes | App type: ios or ipa for iOS, android or apk for Android, harmonyos or hap for HarmonyOS |
| oversea | Integer | No | Use overseas upload acceleration: 1 overseas, 2 mainland China; leave blank for auto-detect by IP |
| buildInstallType | Integer | No | Install method, default 1. 1: public; 2: password; 3: invite |
| buildPassword | String | No | Install password — empty means public install |
| buildDescription | String | No | App description; pass empty or omit if none |
| buildUpdateDescription | String | No | Release notes; pass empty or omit if none |
| buildInstallDate | Integer | No | Download date window: 1 sets a window, 2 does not restrict download start or end dates; omit to keep the previous setting. This does not change historical-build retention rules |
| buildInstallStartDate | String | No | Install window start, e.g. 2018-01-01 |
| buildInstallEndDate | String | No | Install window end, e.g. 2018-12-31 |
| buildChannelShortcut | String | No | Channel short URL to update. Channel must already exist; one at a time, e.g. abcd |
Response
| Field | Type | Description |
|---|---|---|
| key | String | Unique storage key for the uploaded file |
| endpoint | String | URL to upload the file to |
| params | Object | Params required by the upload: signature, x-cos-security-token, key |
{
"code": 0,
"message": "",
"data": {
"endpoint": "https://upload-v7.upload.cos.ap-shanghai.myqcloud.com",
"key": "apps/xxx/yyyy/zzzz.apk",
"params": {
"signature": "q-sign-algorithm=sha1&q-ak=...&q-signature=...",
"x-cos-security-token": "...",
"key": "apps/xxx/yyyy/zzzz.apk"
}
}
}Upload the File to the Returned URL
Upload the app file to the endpoint returned by getCOSToken.
A successful upload triggers Pgyer's backend release queue — this step returning success doesn't mean the release is done. Publishing typically completes within a minute; poll buildInfo in the next step to check status.
<endpoint from the previous response>Set Content-Type: multipart/form-data.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | String | Yes | From the previous response |
| signature | String | Yes | From the previous response |
| x-cos-security-token | String | Yes | From the previous response |
| x-cos-meta-file-name | String | No | Original filename, e.g. app-release.apk |
| file | File | Yes | Local path to the app file |
Response
- Success: HTTP
204 No Content. - Failure: the corresponding error message.
Check Release Status
Check whether the app has finished publishing and fetch the release info.
https://www.pgyer.com/apiv2/app/buildInfoRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| _api_key | String | Yes | API Key — see auth |
| buildKey | String | Yes | The key returned in step one |
Response
Three possible outcomes:
| Field | Type | Description |
|---|---|---|
| buildKey | String | Build Key, unique index ID for the app |
| buildType | Integer | App type (1: iOS; 2: Android) |
| buildIsFirst | Integer | Is this the first build (1: yes; 2: no) |
| buildIsLastest | Integer | Is this the latest version (1: yes; 2: no) |
| buildFileSize | Integer | Installer size |
| buildName | String | App name |
| buildVersion | String | Version number, default 1.0 (the version shown to users, e.g. 1.1, 8.2.1) |
| buildVersionNo | String | Build version in the uploaded installer, default 1 (Android's Version Code; iOS is string, Android is integer, e.g. 1001, 28) |
| buildBuildVersion | Integer | Pgyer-generated build number used to distinguish historical versions |
| buildIdentifier | String | App package identifier — BundleId on iOS, package name on Android |
| buildIcon | String | App icon key. Access URL is https://cdn-app-icon2.pgyer.com/<buildIconPath>/<buildIcon>?x-oss-process=image/resize,m_lfit,h_120,w_120/format,jpg; buildIconPath is the first 5 chars of buildIcon joined by /. For buildIcon = 123abcdefaaa, buildIconPath = 1/2/3/a/b |
| buildDescription | String | App description |
| buildUpdateDescription | String | Release notes |
| buildScreenShots | String | Screenshot key; access URL is https://www.pgyer.com/image/view/app_screenshots/<screenshot_key> |
| buildShortcutUrl | String | App short URL |
| buildQRCodeURL | String | App QR code URL |
| buildCreated | String | Upload time |
| buildUpdated | String | Update time |
{
"code": 0,
"message": "",
"data": {
"buildKey": "a1b2c3d4e5f6",
"buildType": 2,
"buildIsFirst": 2,
"buildIsLastest": 1,
"buildFileSize": 12345678,
"buildName": "Sample App",
"buildVersion": "1.1",
"buildVersionNo": "28",
"buildBuildVersion": 5,
"buildIdentifier": "com.example.app",
"buildIcon": "123abcdefaaa",
"buildDescription": "Sample description",
"buildUpdateDescription": "Various bug fixes",
"buildScreenShots": "",
"buildShortcutUrl": "abcd",
"buildQRCodeURL": "https://www.pgyer.com/app/qrcode/abcd",
"buildCreated": "2025-01-01 10:00:00",
"buildUpdated": "2025-01-01 10:05:00"
}
}| Field | Type | Description |
|---|---|---|
| code | Integer | Error code, 1247 — app is still publishing |
| message | String | Human-readable message |
{
"code": 1247,
"message": "App is publishing"
}| Field | Type | Description |
|---|---|---|
| code | Integer | Error code, 1216 — publishing failed |
| message | String | Human-readable message |
{
"code": 1216,
"message": "App publish failed"
}When you get code = 1247 (still publishing), retry every 3–5 seconds until you see success or failure.
Upload HarmonyOS App p12 Certificate
When releasing a HarmonyOS .hap, upload the p12 signing certificate.
https://upload.pgyer.com/apiv2/app/uploadHarmonyCertSet Content-Type: multipart/form-data.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| _api_key | String | Yes | API Key — see auth |
| file | File | Yes | The .p12 file to upload |
| password | String | Yes | Password for the p12 |
| buildKey | String | Yes | See buildKey |
The build referenced by buildKey must contain signing information. Upload a build signed with an internal testing or enterprise profile first.
Response
| Field | Type | Description |
|---|---|---|
| code | Integer | 0 when the certificate is saved; anything greater — see the error codes below |
| message | String | The reason on failure. When code is 0 and message is not empty, the certificate was saved but does not match the build's signing certificate |
| data | String | success when saved |
If the P12 does not match the signing certificate of the build, it is still saved and the response is code: 0, but message explains the mismatch and testers may not be able to install. Upload the P12 that was used to sign the build.
Error Codes
| Code | Meaning |
|---|---|
| 3001 | buildKey is empty or the build was not found |
| 3002 | No permission for this app |
| 3003 | Not a HarmonyOS app |
| 3004 | No certificate file was uploaded |
| 3005 | The file extension is not .p12 |
| 3006 | The P12 certificate is not yet valid or has expired; message includes the time |
| 3008 | Incorrect P12 password, or the file is not a valid P12 certificate |
| 3009 | No private key in the P12, or the private key entry could not be read; export the P12 again |
| 3010 | The certificate could not be saved; try again later |
| 3011 | The certificate file is larger than 10 MB |
| 3012 | The certificate file is empty |
| 3013 | Invalid certificate file format |
| 3014 | The build has no signing information (unsigned or unreadable); upload a build signed with an internal testing or enterprise profile first |
Upload HarmonyOS Hsp File
When a HarmonyOS .hap has .hsp dependencies, upload each .hsp.
https://upload.pgyer.com/apiv2/app/uploadHarmonyHspSet Content-Type: multipart/form-data.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| _api_key | String | Yes | API Key — see auth |
| file | File | Yes | The Hsp file to upload |
| buildKey | String | Yes | See buildKey |
Response
| Field | Type | Description |
|---|---|---|
| code | Integer | 0 on success; anything greater — see error codes |
Upload App (Legacy)
This endpoint is slow — use Fast Upload instead.
https://upload.pgyer.com/apiv2/app/uploadRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| _api_key | String | Yes | API Key — see auth |
| file | File | Yes | The ipa or apk to upload |
| buildInstallType | Integer | No | Install method, default 1. 1: public; 2: password; 3: invite |
| buildPassword | String | No | Install password — empty means public install |
| buildUpdateDescription | String | No | Release notes; pass empty or omit if none |
| buildInstallDate | Integer | No | Whether to set a validity window: 1 with window, 2 forever; omit to leave the previous setting |
| buildInstallStartDate | String | No | Install window start, e.g. 2018-01-01 |
| buildInstallEndDate | String | No | Install window end, e.g. 2018-12-31 |
| buildChannelShortcut | String | No | Channel short URL to update; one at a time, e.g. abcd |
Response
| Field | Type | Description |
|---|---|---|
| buildKey | String | Build Key, unique index ID for the app |
| buildType | Integer | App type (1: iOS; 2: Android) |
| buildIsFirst | Integer | Is this the first build (1: yes; 2: no) |
| buildIsLastest | Integer | Is this the latest version (1: yes; 2: no) |
| buildFileSize | Integer | Installer size |
| buildName | String | App name |
| buildVersion | String | Version number, default 1.0 |
| buildVersionNo | String | Build version in the uploaded installer, default 1 |
| buildBuildVersion | Integer | Pgyer-generated build number used to distinguish historical versions |
| buildIdentifier | String | App package identifier — BundleId on iOS, package name on Android |
| buildIcon | String | App icon key. Access URL is https://cdn-app-icon2.pgyer.com/<buildIconPath>/<buildIcon>?x-oss-process=image/resize,m_lfit,h_120,w_120/format,jpg; buildIconPath is the first 5 chars of buildIcon joined by / |
| buildDescription | String | App description |
| buildUpdateDescription | String | Release notes |
| buildScreenShots | String | Screenshot key; access URL is https://www.pgyer.com/image/view/app_screenshots/<screenshot_key> |
| buildShortcutUrl | String | App short URL |
| buildQRCodeURL | String | App QR code URL |
| buildCreated | String | Upload time |
| buildUpdated | String | Update time |