HTTP APIs

You can use the raw HTTP APIs to manage Cloud Code scripts.

Using the API

The Admin API documentation contains a detailed description of admin operations, such as creating, reading, updating, and deleting scripts.
The Client API documentation contains a detailed description of client-facing operations, such as running a script.

Both API documents include information on authentication, endpoints, and request and response formats, along with examples. You can download them in OpenAPI format and use them to set up your own automation.

To use the Admin API, authenticate using a service account.

Authorization header

To authenticate the requests, use Basic Authentication. Create a service account and base64 encode the <KEY_ID>:<SECRET_KEY> and use it as the value of the Authorization header.

--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>' \

Deploy scripts

You can create a script by sending the following request:

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>' \
--data '{
    "name": "test-script",
    "type": "API",
    "code": "module.exports = () => {return \"Result from standalone API script\";}",
    "language": "JS"
}'

To make the script available to the game client, you have to publish it:

curl --request POST 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>/publish' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>'

Every time you publish, the script version increments. A successful response could look as follows:

{
    "version": 1,
    "datePublished": "2023-06-23T10:39:20Z"
}

You are not able to publish a script that has no changes since the last publish.

Update scripts

You can update the script code, parameters or both by sending the following request:

curl --request PATCH 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>' \
--data '{
    "params": [
        {
            "name": "parameter",
            "type": "STRING",
            "required": false
        }
    ],
     "code": "module.exports = () => {return \"Updated result from standalone API script\";}"
}'

To make the updated version of the script available to the game client, you have to publish it again, resulting in creating version 2.

{
    "version": 2,
    "datePublished": "2023-06-23T10:40:00Z"
}

Rollback scripts

If you published a script, and you are not happy with the new version, you can roll back to the previous version by sending a request with a specified version number:

curl --request POST 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>/publish' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>'
--data '{
    "version": 1
}'

Now the first script version is republished as version 3:

{
    "version": 3,
    "datePublished": "2023-06-23T10:50:00Z"
}

Retrieve scripts

To check the contents of your script, you can send the following request:

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>'

The response could look as follows:

{
  "name": "test",
  "type": "API",
  "language": "JS",
  "activeScript": {
    "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
    "params": [
      {
        "name": "someThing",
        "type": "STRING",
        "required": true
      }
    ],
    "version": 2,
    "datePublished": "2021-07-23T16:08:35Z"
  },
  "versions": [
    {
      "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
      "params": [
        {
          "name": "someThing",
          "type": "STRING",
          "required": true
        }
      ],
      "isDraft": true,
      "version": null,
      "dateUpdated": "2021-07-23T15:59:32Z"
    },
    {
      "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
      "params": [
        {
          "name": "someThing",
          "type": "STRING",
          "required": true
        }
      ],
      "isDraft": false,
      "version": 2,
      "dateUpdated": "2021-07-23T16:08:35Z",
      "dateCreated": "2021-07-23T16:08:35Z"
    },
    {
      "code": "module.exports=async (cloudCode) =>{cloudCode.logger.info('this message confirms that the logging client is functional!'); return cloudCode.params.someThing;}",
      "params": [
        {
          "name": "someThing",
          "type": "STRING",
          "required": true
        }
      ],
      "isDraft": false,
      "version": 1,
      "dateUpdated": "2021-07-23T15:59:58Z",
      "dateCreated": "2021-07-23T15:59:58Z"
    }
  ],
  "params": [
    {
      "name": "someThing",
      "type": "STRING",
      "required": true
    }
  ]
}

The response contains the following information:

name: the name of the script.
type: the type of the script. Cloud Code scripts only support API scripts.
language: the language of the script. Cloud Code scripts only support JavaScript.

The activeScript refers to the currently published script version which is available to the game client. This contains its code and parameters, the version number and the date when it was published.

The versions array contains all the versions of the script, including the currently published version, the working copy, and any previously published versions. This working copy is a script version that contains the latest changes, but is not yet available to the game client. For this version, the attribute isDraft is set to true, and its version is null. The working copy is published next time you send a publish request.

To see all the scripts you have created, you can send the following request:

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>'

The list response could look as follows:

{
    "results": [
        {
            "name": "script",
            "language": "JS",
            "type": "API",
            "published": true,
            "lastPublishedDate": "2022-03-08T12:37:48Z",
            "lastPublishedVersion": 40
        },
        {
            "name": "test",
            "language": "JS",
            "type": "API",
            "published": true,
            "lastPublishedDate": "2023-06-20T15:14:58Z",
            "lastPublishedVersion": 4
        }
    ],
    "links": {
        "next": null
    }
}

The response contains a quick overview of all the scripts you have created. To use paging, you can use query parameters to narrow down the scope of your results and obtain a link to the next page of results.

curl 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts?limit=2' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>'

The next link could look as follows:

{
  "links": {
        "next": "/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts?after=<SCRIPT_NAME>"
    }
}

Delete script

To delete a script, you can send the following request:

curl --request DELETE 'https://services.api.unity.com/cloud-code/v1/projects/<PROJECT_ID>/environments/<ENVIRONMENT_ID>/scripts/<SCRIPT_NAME>' \
--header 'Authorization: Basic <SERVICE_ACCOUNT_CREDENTIALS_ENCODED>'

An empty response indicates a successful deletion.

HTTP APIs#

Using the API#

Authorization header#

Deploy scripts#

Update scripts#

Rollback scripts#

Retrieve scripts#

Delete script#