Unity DevOps Build Automation Artifact API

bash
python

This API is intended to be used in conjunction with the Unity DevOpos Build Automation service. A tool for building your Unity projects in the Cloud.

See https://developer.cloud.unity3d.com for more information.

Making requests

This website is built to allow requests to be made against the API. If you are currently logged into Build Automation you should be able to make requests without entering an API key.

You can find your API key in the Unity Cloud Services portal by clicking on 'Build Automation Preferences' in the sidebar. Copy the API Key and paste it into the upper left corner of this website. It will be used in all subsequent requests.

The general path is to first POST to the Unity Build Automation API to start a build. When specifying a '_local' build target the build will immediately return as successful.

Next use POST to the Unity Build Artifact API create an artifact. When creating the artifact you specify the files you will upload as part of the artifact. Specifying an artifact as the primary artifact will cause it to be shown in the Unity Cloud Services website for download.

To upload the individual files use a tus client. Tus is an open protocol for uploading files that can be resumed. There is a javascript client as well as clients for other languages.

Clients

The Unity Build Automation API is based upon Swagger. Client libraries to integrate with your projects can easily be generated with the Swagger Code Generator.

The JSON schema required to generate a client for this API version is located here:

https://build-artifact-api.cloud.unity3d.com/api/v1/api.json

Authorization

The Unity Build Automation API requires an access token from your Unity Build Automation account, which can be found at https://developer.cloud.unity3d.com/login/me

To authenticate requests, include a Basic Authentication header with your API key as the value. e.g.

Authorization: Basic [YOUR API KEY]

Versioning

The API version is indicated in the request URL. Upgrading to a newer API version can be done by changing the path.

The API will receive a new version in the following cases:

removal of a path or request type
addition of a required field
removal of a required field

The following changes are considered backwards compatible and will not trigger a new API version:

addition of an endpoint or request type
addition of an optional field
removal of an optional field
changes to the format of ids

Rate Limiting

Requests against the API are limited to a rate of 100 per minute and 120 uploads in a 24 hour period. To preserve the quality of service throughout Unity DevOps Build Automation, additional rate limits may apply to some actions. For example, polling aggressively instead of using webhooks or making API calls with a high concurrency may result in rate limiting.

It is not intended for these rate limits to interfere with any legitimate use of the API. Please contact support at cloudbuild@unity3d.com if your use is affected by this rate limit.

You can check the returned HTTP headers for any API request to see your current rate limit status.

* __X-RateLimit-Limit:__ maximum number of requests per minute
* __X-RateLimit-Remaining:__ remaining number of requests in the current window
* __X-RateLimit-Reset:__ time at which the current window will reset (UTC epoch seconds)

Once you go over the rate limit you will receive an error response:


    # initialize the API client
    configuration = Configuration();
    configuration.username = "[YOUR API KEY]";
    client = ApiClient("https://build-artifact-api.cloud.unity3d.com/api/v1")

Paths

Retrieve artifact links

GET /projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts

Description

Return links to artifacts

Required Permissions

project:user

Request Parameters


projectupid	Unity project id	path	string
buildtargetid	buildtarget, _local may be used for local builds	path	string
number	build number	path	string

application/json

Response


curl
  -X GET
  -H 'Content-Type: application/json'
  -H 'Authorization: Basic [YOUR API KEY]'
  https://build-artifact-api.cloud.unity3d.com/api/v1/projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts


artifactsApi = ArtifactsApi(client);
artifacts = artifactsApi.list('{projectupid}', '{buildtargetid}', '{number}');

Responses

application/json

200 OK

object

key: string
name: string
primary: boolean
show_download: boolean
webgl_template: string
files: object[]: object


[
  {
    "key": "primary",
    "name": ".ZIP file",
    "primary": true,
    "show_download": true,
    "webgl_template": "APPLICATION:Default",
    "files": [
      {
        "filename": "webgl.zip",
        "size": 32260251,
        "resumable": false,
        "href": "[FULL S3 LINK]"
      }
    ]
  },
  {
    "key": "all_artifacts",
    "name": "All Artifacts",
    "primary": false,
    "show_download": false,
    "webgl_template": "APPLICATION:Default",
    "files": [
      {
        "filename": "Default WebGL/TemplateData/style.css",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/progressEmpty.Light.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/progressLogo.Dark.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/progressLogo.Light.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/fullscreen.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/progressFull.Light.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/webgl-logo.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/index.html",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/UnityProgress.js",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/progressEmpty.Dark.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/progressFull.Dark.png",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/Build/Default WebGL.json",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/TemplateData/favicon.ico",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/Build/Default WebGL.asm.framework.unityweb",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/Build/UnityLoader.js",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/Build/Default WebGL.asm.memory.unityweb",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/Build/Default WebGL.asm.code.unityweb",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      },
      {
        "filename": "Default WebGL/Build/Default WebGL.data.unityweb",
        "resumable": false,
        "href": "[FULL S3 LINK]"
      }
    ]
  }
]

default

error: string
details: object

Create artifact

POST /projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts

Description

Create a new artifact

Required Permissions

project:user

Request Parameters


projectupid	Unity project id	path	string
buildtargetid	buildtarget, _local may be used for local builds	path	string
number	build number	path	string

application/json

Definition of the artifact including files you plan to upload

{"required":["name","files"],"properties":{"name":{"type":"string"},"key":{"type":"string"},"primary":{"type":"boolean"},"public":{"type":"boolean"},"files":{"type":"array","items":{"type":"object","required":["filename","size"],"properties":{"filename":{"type":"string"},"size":{"type":"integer"},"md5sum":{"type":"string"}}}}}}

Response


curl
  -X POST
  -H 'Content-Type: application/json'
  -H 'Authorization: Basic [YOUR API KEY]'
  --data-binary '{"name":"Android Beta 1","primary":true,"public":false,"files":[{"filename":android-beta-1.apk","size":19901827}]}'
  https://build-artifact-api.cloud.unity3d.com/api/v1/projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts


artifact = Artifact();
artifact.name = 'Android Beta 1'
artifact.primary = True
artifact.public = False
artifact.files = [
  {
    'filename': 'android-beta-1.apk',
    'size': 19901827
  }
];
artifactsApi = ArtifactsApi(client);
artifactsApi.create_artifact('{projectupid}', '{buildtargetid}', '{number}', artifact);

Responses

application/json

201 Created

409 Conflict

default

error: string
details: object

Get file status

HEAD /projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts/{artifactname}/upload/{filename}

Description

Get current status of artifact file. When an artifact is found the server responds with the Upload-Offset and Upload-Length headers which are used when uploading via the PATCH method.

Required Permissions

project:user

Request Parameters


Tus-Resumable	Tus-Resumable version	header	string 1.0.0
projectupid	Unity project id	path	string
buildtargetid	buildtarget, _local may be used for local builds	path	string
number	build number	path	string
artifactname	artifact name	path	string
filename	filename	path	string

Response


curl
  --head
  -H 'Tus-Resumable: {tus-resumable}'
  -H 'Content-Type: application/json'
  -H 'Authorization: Basic [YOUR API KEY]'
  https://build-artifact-api.cloud.unity3d.com/api/v1/projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts/{artifactname}/upload/{filename}


uploadApi = UploadApi(client);
status = uploadApi.status('{tus-resumable}', '{projectupid}', '{buildtargeid}', '{number}', '{artifactname}', '{filename}')

Responses

Uses default content-types: application/json text/plain text/html text/csv

200 OK

404 Not Found

default

error: string
details: object

Create file

POST /projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts/{artifactname}/upload/{filename}

Description

Create upload

Required Permissions

project:user

Request Parameters


Tus-Resumable	Tus-Resumable version	header	string 1.0.0
Upload-Length	Length of upload	header	integer
projectupid	Unity project id	path	string
buildtargetid	buildtarget, _local may be used for local builds	path	string
number	build number	path	string
artifactname	artifact name	path	string
filename	filename	path	string

application/offset+octet-stream

Response


curl
  -X PATCH
  -H 'Upload-Offset: {upload-offset}'
  -H 'Tus-Resumable: {tus-resumable}'
  -H 'Content-Type: application/offset+octet-stream'
  -H 'Authorization: Basic [YOUR API KEY]'
  --data-binary @/path/to/local/file
  https://build-artifact-api.cloud.unity3d.com/api/v1/projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts/{artifactname}/upload/{filename}


uploadApi = UploadApi(client);
response = uploadApi.create('{tus-resumable}', '{upload-length}', '{projectupid}', , '{buildtargetid}', '{number}', '{artifactname}', '{filename}'):

Responses

Uses default content-types: application/json text/plain text/html text/csv

201 Created

default

error: string
details: object

Upload file

PATCH /projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts/{artifactname}/upload/{filename}

Description

Upload artifact file

Required Permissions

project:user

Request Parameters


Tus-Resumable	Tus-Resumable version	header	string 1.0.0
Upload-Offset	Offset at which upload starts	header	integer
projectupid	Unity project id	path	string
buildtargetid	buildtarget, _local may be used for local builds	path	string
number	build number	path	string
artifactname	artifact name	path	string
filename	filename	path	string

application/offset+octet-stream

Response


curl
  -X PATCH
  -H 'Upload-Length: {upload-length}'
  -H 'Content-Length: 0'
  -H 'Tus-Resumable: {tus-resumable}'
  -H 'Content-Type: application/offset+octet-stream'
  -H 'Authorization: Basic [YOUR API KEY]'
  https://build-artifact-api.cloud.unity3d.com/api/v1/projects/{projectupid}/buildtargets/{buildtargetid}/builds/{number}/artifacts/{artifactname}/upload/{filename}


with open('/path/to/local/file', 'rb') as f:
  data = f.read()
uploadApi = UploadApi(client);
response = uploadApi.create('{tus-resumable}', '{upload-offset}', '{projectupid}', , '{buildtargetid}', '{number}', '{artifactname}', '{filename}', data):

Responses

Uses default content-types: application/json text/plain text/html text/csv

204 No Content

400 Bad Request

error: string
details: object

409 Conflict

error: string
details: object

default

error: string
details: object

Configuration

Version 1.0.0

Contents

Paths

Artifacts

Upload

Unity DevOps Build Automation Artifact API

Making requests

Clients

Authorization

Versioning

Rate Limiting

Paths

Retrieve artifact links

Description

Required Permissions

Request Parameters

Response

Responses

Create artifact

Description

Required Permissions

Request Parameters

Response

Responses

Get file status

Description

Required Permissions

Request Parameters

Response

Responses

Create file

Description

Required Permissions

Request Parameters

Response

Responses

Upload file

Description

Required Permissions

Request Parameters

Response

Responses

Version