> For the complete documentation index, see [llms.txt](https://docs.appetize.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appetize.io/rest-api/builds.md).
# Builds
## Get a specific build by its unique identifier.
> Get a specific build by its unique identifier.
```json
{"openapi":"3.0.3","info":{"title":"Appetize V2 API Reference","version":"2"},"servers":[{"url":"https://api.appetize.io"}],"security":[{"jwt":[]},{"apiToken":[]}],"components":{"securitySchemes":{"apiToken":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Use an API token for authentication via X-API-KEY header"}},"schemas":{"Build":{"type":"object","required":["id","created"],"properties":{"id":{"type":"string","description":"The unique identifier for the build."},"appId":{"type":"string","description":"The unique identifier for the app build. On Android this is the package name, on iOS this is the bundle identifier."},"platform":{"type":"string","enum":["ios","android"]},"name":{"description":"The app name, as specified by the specific build. This is the CFBundleDisplayName on iOS and the application label on Android.","type":"string"},"iconUrl":{"description":"The app icon, as specified by the specific build.","type":"string","format":"uri"},"versionName":{"description":"The version name, as specified by the build. In Android this is the versionName, in iOS this is the CFBundleShortVersionString.","type":"string"},"buildNumber":{"description":"The build number, as specified by the build. In Android this is the versionCode, in iOS this is the CFBundleVersion.","type":"string"},"tags":{"description":"The tags associated with the app version.","type":"array","items":{"type":"string"}},"note":{"description":"The note associated with the app version.","type":"string"},"created":{"description":"The date the build was created.","type":"string","format":"date-time"},"createdBy":{"description":"The user who created the build.","type":"string"},"updated":{"description":"The date the build was last updated.","type":"string","format":"date-time"},"updatedBy":{"description":"The user who last updated the build.","type":"string"},"lastPlayed":{"description":"The time the build was last played.","type":"string","format":"date-time"},"metadata":{"description":"The platform specific metadata associated with the build.","oneOf":[{"type":"object","properties":{"android":{"$ref":"#/components/schemas/AndroidMetadata"}}},{"type":"object","properties":{"ios":{"$ref":"#/components/schemas/IosMetadata"}}}]}}},"AndroidMetadata":{"type":"object","properties":{"packageName":{"type":"string"},"name":{"type":"string"},"versionName":{"type":"string"},"versionCode":{"type":"integer","format":"int64"},"minSDKVersion":{"type":"integer","format":"int32"},"targetSDKVersion":{"type":"integer","format":"int32"},"architectures":{"type":"array","items":{"type":"string"}},"permissions":{"type":"array","items":{"type":"string"}},"localizations":{"type":"array","items":{"type":"string"}}}},"IosMetadata":{"type":"object","properties":{"CFBundleId":{"type":"string"},"CFBundleName":{"type":"string"},"CFBundleDisplayName":{"type":"string"},"MinimumOSVersion":{"type":"string"},"DTPlatformName":{"type":"string"},"CFBundleVersion":{"type":"string"},"CFBundleShortVersionString":{"type":"string"},"CFBundleSupportedPlatforms":{"type":"array","items":{"type":"string"}},"UIRequiredDeviceCapabilities":{"type":"array","items":{"type":"string"}},"DTSDKName":{"type":"string"},"UsageDescriptions":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]}},"UISupportedInterfaceOrientations":{"type":"array","items":{"type":"string"}},"UISupportedInterfaceOrientationsIpad":{"type":"array","items":{"type":"string"}},"CFBundleURLTypes":{"type":"array","items":{"$ref":"#/components/schemas/CfBundleUrlType"}},"Localizations":{"type":"array","items":{"type":"string"}},"Frameworks":{"type":"array","items":{"type":"string"}},"Architectures":{"type":"array","items":{"type":"string"}}}},"CfBundleUrlType":{"type":"object","properties":{"CFBundleURLName":{"type":"string"},"CFBundleURLSchemes":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"message":{"description":"Error message.","type":"string"}}}}},"paths":{"/v2/builds/{buildId}":{"get":{"summary":"Get a specific build by its unique identifier.","tags":["Builds"],"description":"Get a specific build by its unique identifier.","operationId":"getBuild","parameters":[{"name":"buildId","in":"path","required":true,"description":"Unique identifier for the build.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Build not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Delete Build
> Delete a build by its unique identifier.
```json
{"openapi":"3.0.3","info":{"title":"Appetize V2 API Reference","version":"2"},"servers":[{"url":"https://api.appetize.io"}],"security":[{"jwt":[]},{"apiToken":[]}],"components":{"securitySchemes":{"apiToken":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Use an API token for authentication via X-API-KEY header"}},"schemas":{"Error":{"type":"object","properties":{"message":{"description":"Error message.","type":"string"}}}}},"paths":{"/v2/builds/{buildId}":{"delete":{"summary":"Delete Build","tags":["Builds"],"description":"Delete a build by its unique identifier.","operationId":"deleteBuild","parameters":[{"in":"path","name":"buildId","description":"The unique identifier for the build.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Build deleted","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Updates an existing build.
> Update a build by its unique identifier.
```json
{"openapi":"3.0.3","info":{"title":"Appetize V2 API Reference","version":"2"},"servers":[{"url":"https://api.appetize.io"}],"security":[{"jwt":[]},{"apiToken":[]}],"components":{"securitySchemes":{"apiToken":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Use an API token for authentication via X-API-KEY header"}},"schemas":{"UploadBuild":{"allOf":[{"$ref":"#/components/schemas/UploadBuildCommon"},{"oneOf":[{"$ref":"#/components/schemas/UploadBuildUrl"},{"$ref":"#/components/schemas/UploadBuildMultipart"}]}]},"UploadBuildCommon":{"type":"object","properties":{"tags":{"type":"array","default":[],"items":{"type":"string"},"description":"Tags for this specific build. Useful for identifying & filtering a certain build. You can add up to 20 tags, each with up to 20 characters."},"note":{"type":"string","description":"A note for your own purposes, will appear on your management dashboard."}}},"UploadBuildUrl":{"type":"object","properties":{"url":{"type":"string","description":"A publicly accessible link to your .zip, .tar.gz, or .apk file."}}},"UploadBuildMultipart":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The app file to upload."}}},"Build":{"type":"object","required":["id","created"],"properties":{"id":{"type":"string","description":"The unique identifier for the build."},"appId":{"type":"string","description":"The unique identifier for the app build. On Android this is the package name, on iOS this is the bundle identifier."},"platform":{"type":"string","enum":["ios","android"]},"name":{"description":"The app name, as specified by the specific build. This is the CFBundleDisplayName on iOS and the application label on Android.","type":"string"},"iconUrl":{"description":"The app icon, as specified by the specific build.","type":"string","format":"uri"},"versionName":{"description":"The version name, as specified by the build. In Android this is the versionName, in iOS this is the CFBundleShortVersionString.","type":"string"},"buildNumber":{"description":"The build number, as specified by the build. In Android this is the versionCode, in iOS this is the CFBundleVersion.","type":"string"},"tags":{"description":"The tags associated with the app version.","type":"array","items":{"type":"string"}},"note":{"description":"The note associated with the app version.","type":"string"},"created":{"description":"The date the build was created.","type":"string","format":"date-time"},"createdBy":{"description":"The user who created the build.","type":"string"},"updated":{"description":"The date the build was last updated.","type":"string","format":"date-time"},"updatedBy":{"description":"The user who last updated the build.","type":"string"},"lastPlayed":{"description":"The time the build was last played.","type":"string","format":"date-time"},"metadata":{"description":"The platform specific metadata associated with the build.","oneOf":[{"type":"object","properties":{"android":{"$ref":"#/components/schemas/AndroidMetadata"}}},{"type":"object","properties":{"ios":{"$ref":"#/components/schemas/IosMetadata"}}}]}}},"AndroidMetadata":{"type":"object","properties":{"packageName":{"type":"string"},"name":{"type":"string"},"versionName":{"type":"string"},"versionCode":{"type":"integer","format":"int64"},"minSDKVersion":{"type":"integer","format":"int32"},"targetSDKVersion":{"type":"integer","format":"int32"},"architectures":{"type":"array","items":{"type":"string"}},"permissions":{"type":"array","items":{"type":"string"}},"localizations":{"type":"array","items":{"type":"string"}}}},"IosMetadata":{"type":"object","properties":{"CFBundleId":{"type":"string"},"CFBundleName":{"type":"string"},"CFBundleDisplayName":{"type":"string"},"MinimumOSVersion":{"type":"string"},"DTPlatformName":{"type":"string"},"CFBundleVersion":{"type":"string"},"CFBundleShortVersionString":{"type":"string"},"CFBundleSupportedPlatforms":{"type":"array","items":{"type":"string"}},"UIRequiredDeviceCapabilities":{"type":"array","items":{"type":"string"}},"DTSDKName":{"type":"string"},"UsageDescriptions":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]}},"UISupportedInterfaceOrientations":{"type":"array","items":{"type":"string"}},"UISupportedInterfaceOrientationsIpad":{"type":"array","items":{"type":"string"}},"CFBundleURLTypes":{"type":"array","items":{"$ref":"#/components/schemas/CfBundleUrlType"}},"Localizations":{"type":"array","items":{"type":"string"}},"Frameworks":{"type":"array","items":{"type":"string"}},"Architectures":{"type":"array","items":{"type":"string"}}}},"CfBundleUrlType":{"type":"object","properties":{"CFBundleURLName":{"type":"string"},"CFBundleURLSchemes":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"message":{"description":"Error message.","type":"string"}}}}},"paths":{"/v2/builds/{buildId}":{"patch":{"summary":"Updates an existing build.","tags":["Builds"],"description":"Update a build by its unique identifier.","operationId":"updateBuild","parameters":[{"in":"path","name":"buildId","description":"The unique identifier for the build.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadBuild"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get builds
> List all builds in the account, with associated metadata. The default page size is 100 items
```json
{"openapi":"3.0.3","info":{"title":"Appetize V2 API Reference","version":"2"},"servers":[{"url":"https://api.appetize.io"}],"security":[{"jwt":[]},{"apiToken":[]}],"components":{"securitySchemes":{"apiToken":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Use an API token for authentication via X-API-KEY header"}},"schemas":{"Pagination":{"type":"object","properties":{"total":{"type":"integer","format":"int32"},"nextPage":{"type":"number","nullable":true,"format":"int32"}}},"BuildCollection":{"type":"object","properties":{"builds":{"description":"A collection of builds.","type":"array","items":{"$ref":"#/components/schemas/Build"}}}},"Build":{"type":"object","required":["id","created"],"properties":{"id":{"type":"string","description":"The unique identifier for the build."},"appId":{"type":"string","description":"The unique identifier for the app build. On Android this is the package name, on iOS this is the bundle identifier."},"platform":{"type":"string","enum":["ios","android"]},"name":{"description":"The app name, as specified by the specific build. This is the CFBundleDisplayName on iOS and the application label on Android.","type":"string"},"iconUrl":{"description":"The app icon, as specified by the specific build.","type":"string","format":"uri"},"versionName":{"description":"The version name, as specified by the build. In Android this is the versionName, in iOS this is the CFBundleShortVersionString.","type":"string"},"buildNumber":{"description":"The build number, as specified by the build. In Android this is the versionCode, in iOS this is the CFBundleVersion.","type":"string"},"tags":{"description":"The tags associated with the app version.","type":"array","items":{"type":"string"}},"note":{"description":"The note associated with the app version.","type":"string"},"created":{"description":"The date the build was created.","type":"string","format":"date-time"},"createdBy":{"description":"The user who created the build.","type":"string"},"updated":{"description":"The date the build was last updated.","type":"string","format":"date-time"},"updatedBy":{"description":"The user who last updated the build.","type":"string"},"lastPlayed":{"description":"The time the build was last played.","type":"string","format":"date-time"},"metadata":{"description":"The platform specific metadata associated with the build.","oneOf":[{"type":"object","properties":{"android":{"$ref":"#/components/schemas/AndroidMetadata"}}},{"type":"object","properties":{"ios":{"$ref":"#/components/schemas/IosMetadata"}}}]}}},"AndroidMetadata":{"type":"object","properties":{"packageName":{"type":"string"},"name":{"type":"string"},"versionName":{"type":"string"},"versionCode":{"type":"integer","format":"int64"},"minSDKVersion":{"type":"integer","format":"int32"},"targetSDKVersion":{"type":"integer","format":"int32"},"architectures":{"type":"array","items":{"type":"string"}},"permissions":{"type":"array","items":{"type":"string"}},"localizations":{"type":"array","items":{"type":"string"}}}},"IosMetadata":{"type":"object","properties":{"CFBundleId":{"type":"string"},"CFBundleName":{"type":"string"},"CFBundleDisplayName":{"type":"string"},"MinimumOSVersion":{"type":"string"},"DTPlatformName":{"type":"string"},"CFBundleVersion":{"type":"string"},"CFBundleShortVersionString":{"type":"string"},"CFBundleSupportedPlatforms":{"type":"array","items":{"type":"string"}},"UIRequiredDeviceCapabilities":{"type":"array","items":{"type":"string"}},"DTSDKName":{"type":"string"},"UsageDescriptions":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]}},"UISupportedInterfaceOrientations":{"type":"array","items":{"type":"string"}},"UISupportedInterfaceOrientationsIpad":{"type":"array","items":{"type":"string"}},"CFBundleURLTypes":{"type":"array","items":{"$ref":"#/components/schemas/CfBundleUrlType"}},"Localizations":{"type":"array","items":{"type":"string"}},"Frameworks":{"type":"array","items":{"type":"string"}},"Architectures":{"type":"array","items":{"type":"string"}}}},"CfBundleUrlType":{"type":"object","properties":{"CFBundleURLName":{"type":"string"},"CFBundleURLSchemes":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"message":{"description":"Error message.","type":"string"}}}}},"paths":{"/v2/builds":{"get":{"summary":"Get builds","tags":["Builds"],"description":"List all builds in the account, with associated metadata. The default page size is 100 items","operationId":"listAllBuilds","parameters":[{"in":"query","name":"appId","schema":{"type":"string"},"description":"The unique identifier for the app build. On Android this is the package name, on iOS this is the bundle identifier."},{"in":"query","name":"buildId","description":"The unique identifier for the build.","schema":{"type":"string"}},{"in":"query","name":"platform","description":"The platform the app targets.","schema":{"type":"string","enum":["ios","android"]}},{"in":"query","name":"buildNumber","description":"The build number, as specified by the build. In Android this is the versionCode, in iOS this is the CFBundleVersion.","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"versionName","description":"The version name, as specified by the build. In Android this is the versionName, in iOS this is the CFBundleShortVersionString.","schema":{"type":"string"}},{"in":"query","name":"tags","description":"The tags to filter by. Comma separated","schema":{"type":"string"}},{"in":"query","name":"limit","description":"The number of items to return. Default is 100.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":200}},{"in":"query","name":"pageNumber","description":"The page number to return. Default is 1.","schema":{"type":"integer","format":"int32","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"$ref":"#/components/schemas/BuildCollection"}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Upload a new build
> Upload a new build to Appetize. This will create a new app if one does not already exist, or update an existing app with a new build version.\
\
You can upload a file via a url (application/json), or submit your file directly (multipart/form).\
\
Note that the build's metadata (ie. appId) is updated asynchronously after the request completes.
```json
{"openapi":"3.0.3","info":{"title":"Appetize V2 API Reference","version":"2"},"servers":[{"url":"https://api.appetize.io"}],"security":[{"jwt":[]},{"apiToken":[]}],"components":{"securitySchemes":{"apiToken":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Use an API token for authentication via X-API-KEY header"}},"schemas":{"Error":{"type":"object","properties":{"message":{"description":"Error message.","type":"string"}}}}},"paths":{"/v2/builds":{"post":{"tags":["Builds"],"summary":"Upload a new build","description":"Upload a new build to Appetize. This will create a new app if one does not already exist, or update an existing app with a new build version.
You can upload a file via a url (application/json), or submit your file directly (multipart/form).
Note that the build's metadata (ie. appId) is updated asynchronously after the request completes.","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["url","platform"],"properties":{"url":{"type":"string","description":"A publicly accessible link to your .zip, .tar.gz, or .apk file."},"platform":{"type":"string","enum":["ios","android"],"description":"Platform the app targets."},"tags":{"type":"array","default":[],"items":{"type":"string"},"description":"Tags for this specific build. Useful for identifying & filtering a certain build. You can add up to 20 tags, each with up to 20 characters."}}}]}},"multipart/form":{"schema":{"allOf":[{"type":"object","required":["file","platform"],"properties":{"file":{"type":"string","format":"binary","description":"The app file to upload."},"platform":{"type":"string","enum":["ios","android"],"description":"Platform the app targets ('ios' or 'android')."},"tags":{"type":"string","format":"array","description":"String representing an array of strings. Tags for this specific build. Useful for identifying & filtering a certain build. Ie. ['latest', 'beta']
You can add up to 20 tags, each with up to 20 characters."}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["id","created"],"properties":{"id":{"type":"string","description":"Unique identifier for the build."},"created":{"description":"The date the build was created.","type":"string","format":"date-time"},"createdBy":{"description":"The user who created the build.","type":"string"},"updated":{"description":"The date the build was last updated.","type":"string","format":"date-time"},"updatedBy":{"description":"The user who last updated the build.","type":"string"},"note":{"type":"string","description":"A note for your own purposes, will appear on your management dashboard."},"tags":{"description":"The tags associated with the app version.","type":"array","items":{"type":"string"}}}}]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get build icon by its unique identifier
> Get build icon by its unique identifier
```json
{"openapi":"3.0.3","info":{"title":"Appetize V2 API Reference","version":"2"},"servers":[{"url":"https://api.appetize.io"}],"security":[{"jwt":[]},{"apiToken":[]}],"components":{"securitySchemes":{"apiToken":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Use an API token for authentication via X-API-KEY header"}}},"paths":{"/v2/builds/{buildId}/icon":{"get":{"summary":"Get build icon by its unique identifier","description":"Get build icon by its unique identifier","tags":["Builds"],"parameters":[{"name":"buildId","in":"path","required":true,"description":"Unique identifier for the build.","schema":{"type":"string"}}],"responses":{"307":{"description":"Redirect to the icon image file","headers":{"Location":{"content":{"text/plain":{"schema":{"type":"string","enum":["/build/icon/path"]}}}}}}}}}}}
```