NAV Navbar
shell

Introduction

Welcome to BattleCrate's open API! This API is supported by our team. If you have any enquiries, bug reports or feature requests please get in touch: developers@battlecrate.io.

Client libraries for this API are on the way! Links to the packages will be available here once ready.

Official C# API Client

JAVA - Coming Soon

Python - Coming Soon

PHP - Coming Soon

Authentication

To use this API, you need your own API credentials. These are generated through the BattleCrate console and are scoped to your account.

Your API key is in the form of a bearer token which must be sent in the Authorization header. For instance: Bearer {TOKEN}.

You are responsible for storing your API credentials and keeping them secure. Your API secret is only shown once immediately after generating your credentials.

Third Party Applications

Got a project in mind that could use the BattleCrate API? Get in touch with our support team to get your official third-party application API credentials.

Crates

A Crate represents your game server. It contains the server itself, its configuration and a near-endless, ever-growing list of features. Crates can be deployed in a matter of seconds and are billed hourly, instead of a month at a time. Simply choose a profile, plan and region and you’ll be gaming in no time!

List Crates

curl "https://api.battlecrate.co.uk/1.0/crate" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "results": [
        {
            "uuid": "4a148751-2a01-472d-ac13-2528d650c1c3",
            "name": "My Awesome Crate",
            "state": "running",
            "region": {
                "name": "uk-1",
                "displayName": "UK London",
                "flagUrl": {
                    "0": "https://assets.battlecrate.io/images/regions/uk.svg"
                },
                "canDeploy": true
            },
            "package": {
                "name": "minecraft",
                "displayName": "Minecraft",
                "iconUrl": {
                    "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
                },
                "backgroundUrl": {
                    "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
                    "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
                    "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
                    "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
                }
            },
            "profile": {
                "name": "mc-1.15.2",
                "displayName": "Vanilla 1.15.2",
                "packageName": "minecraft",
                "canDeploy": true
            },
            "plan": {
                "name": "mc-1",
                "displayName": "Grass",
                "pricing": [
                    {
                        "currency": "GBP",
                        "costHourly": 0.03,
                        "costMonthly": 5.0
                    }
                ],
                "packageName": "minecraft",
                "profileName": null,
                "regionName": null,
                "cpuCount": 2.0,
                "memoryInMB": 1024,
                "storageInMB": 5120,
                "backupsInMB": 10240,
                "canDeploy": true
            },
            "permission": "owner",
            "createdAt": "2020-03-18T16:17:09.3975027+00:00"
        }
    ],
    "totalResults": 3,
    "limit": 25,
    "page": 1,
    "totalPages": 1
}

List all the Crates in your account, regardless of whether you own them or if another user has shared them with you. The returned Crates are sorted by date created in ascending order (oldest Crates at the top) and, by default, are returned in groups of 25. You can use the limit and page query parameters to adjust your returned results.

For reference see:

HTTP Request

GET /crate

Query Parameters

Parameter Required Description Default Misc
limit No The maximum number of Crates that can be returned. 25 Minimum 1, Maximum 50
page No The cursor for the next batch of results. 1 Minimum 1

Response Codes

200 OK

400 Bad Request - The request you sent was not valid.

Deploy a new Crate

curl -XPOST 'https://api.battlecrate.io/crate/new' -H 'Authentication: Bearer:  {KEY}' -H "Content-type: application/json" -d '{"name": "Example Crate", "region": "uk-1", "profile": "vanilla", "plan": "mc-1", "properties": {"EULA": true}}'

This command returns the following JSON body.

{
    "uuid": "bf05936b-3b82-4d02-83f2-767e935e38f0",
    "name": "Example Crate",
    "state": "running",
    "region": {
        "name": "uk-1",
        "displayName": "UK London",
        "flagUrl": {
            "0": "https://assets.battlecrate.io/images/regions/uk.svg"
        },
        "canDeploy": true
    },
    "package": {
        "name": "minecraft",
        "displayName": "Minecraft",
        "iconUrl": {
            "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
        },
        "backgroundUrl": {
            "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
            "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
            "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
            "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
        }
    },
    "profile": {
        "name": "vanilla",
        "displayName": "Vanilla",
        "packageName": "minecraft",
        "canDeploy": true
    },
    "plan": {
        "name": "mc-1",
        "displayName": "Grass",
        "pricing": [
            {
                "currency": "GBP",
                "costHourly": 0.03,
                "costMonthly": 5.0
            }
        ],
        "packageName": "minecraft",
        "profileName": null,
        "regionName": null,
        "cpuCount": 2.0,
        "memoryInMB": 1024,
        "storageInMB": 5120,
        "backupsInMB": 10240,
        "canDeploy": true
    },
    "permission": "owner",
    "createdAt": "2020-03-18T16:17:09.3975027+00:00"
}

Deploy a new Crate to your account. To call this route successfully you must have enough credit and have not reached the limitation of your account. Please get in touch with our team if you need to deploy more than your account permits.

When deploying a Crate you must also pass in any required properties, to find which properties are required for your deployment see Crate Profile Properties, these properties are required key value pairs used to deploy your Crate.

HTTP Request

POST /crate/new

Body Contents

Parameter Required Type Description
name Yes String The name for your new Crate (must abide by our Crate naming guidelines and regulations).
region Yes String The name of the region where the Crate should be deployed (for example: “uk-1”).
profile Yes String The name of the profile that should be used to configure this Crate (for example: “mc-1.15.2”).
plan Yes String The name of the plan that should be used for this Crate (for example: “mc-1”).
properties Yes Dictionary Any properties required to deploy the Profile. Find these for your chosen profile: see see Crate Profile Properties.

Response Codes

200 OK - A new Crate has been created.

400 Bad Request - The request you sent was not valid.

412 Precondition Failed - Unable to create new Crate on this account. This could be regarding billing or other account limitations.

Get a Crate

curl "https://api.battlecrate.co.uk/1.0/crate/{uuid}" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "uuid": "4a148751-2a01-472d-ac13-2528d650c1c3",
    "name": "My Awesome Crate",
    "state": "running",
    "region": {
        "name": "uk-1",
        "displayName": "UK London",
        "flagUrl": {
            "0": "https://assets.battlecrate.io/images/regions/uk.svg"
        },
        "canDeploy": true
    },
    "package": {
        "name": "minecraft",
        "displayName": "Minecraft",
        "iconUrl": {
            "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
        },
        "backgroundUrl": {
            "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
            "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
            "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
            "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
        }
    },
    "profile": {
        "name": "vanilla",
        "displayName": "Vanilla",
        "packageName": "minecraft",
        "canDeploy": true
    },
    "plan": {
        "name": "mc-1",
        "displayName": "Grass",
        "pricing": [
            {
                "currency": "GBP",
                "costHourly": 0.03,
                "costMonthly": 5.0
            }
        ],
        "packageName": "minecraft",
        "profileName": null,
        "regionName": null,
        "cpuCount": 2.0,
        "memoryInMB": 1024,
        "storageInMB": 5120,
        "backupsInMB": 10240,
        "canDeploy": true
    },
    "permission": "owner",
    "createdAt": "2020-03-18T16:17:09.3975027+00:00"
}

Retrieve a Crate from your account whether you own it, or another user has shared it with you.

For reference see:

HTTP Request

GET /crate/{uuid}

URL Parameters

Parameter Description
uuid The UUID of the Crate to retrieve.

Response Codes

200 OK - Crate has been found.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been or is in the process of being deleted.

Edit a Crate

curl -XPOST 'https://api.battlecrate.io/1.0/crate/{uuid}' -H "Authorization: Bearer: {KEY}" -H "Content-type: application/json" -d '{"name": "Even more awesome Crate"}' 

This command returns the following JSON body.

{
    "uuid": "4a148751-2a01-472d-ac13-2528d650c1c3",
    "name": "Even more awesome Crate",
    "state": "running",
    "region": {
        "name": "uk-1",
        "displayName": "UK London",
        "flagUrl": {
            "0": "https://assets.battlecrate.io/images/regions/uk.svg"
        },
        "canDeploy": true
    },
    "package": {
        "name": "minecraft",
        "displayName": "Minecraft",
        "iconUrl": {
            "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
        },
        "backgroundUrl": {
            "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
            "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
            "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
            "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
        }
    },
    "profile": {
        "name": "vanilla",
        "displayName": "Vanilla",
        "packageName": "minecraft",
        "canDeploy": true
    },
    "plan": {
        "name": "mc-1",
        "displayName": "Grass",
        "pricing": [
            {
                "currency": "GBP",
                "costHourly": 0.03,
                "costMonthly": 5.0
            }
        ],
        "packageName": "minecraft",
        "profileName": null,
        "regionName": null,
        "cpuCount": 2.0,
        "memoryInMB": 1024,
        "storageInMB": 5120,
        "backupsInMB": 10240,
        "canDeploy": true
    },
    "permission": "owner",
    "createdAt": "2020-03-18T16:17:09.3975027+00:00"
}

Edit a Crate in your account whether you own it, or another user has shared it with you. To call this route successfully you must have write permissions for the Crate.

For reference see:

HTTP Request

POST /crate/{uuid}

URL Parameters

Parameter Description
uuid The UUID of the Crate to edit.

Body Contents

Parameter Required Type Description
name Yes String The new name for this Crate (must abide by our Crate naming guidelines and regulations).

Response Codes

200 OK - Crate has been editted.

400 Bad Request - The request you sent was not valid.

403 Forbidden - You do not have permission to change the name of this Crate.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted or is in the process of being deleted.

Delete a Crate

curl -X DELETE "https://api.battlecrate.co.uk/1.0/crate/{uuid}" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "uuid": "1b209590-3e04-4ed3-84c5-ed447cc67641",
    "type": "Delete",
    "isCompleted": true,
    "isCompletedSuccesfully": true,
    "createdAt": "2020-06-03T12:28:06.0937006+00:00",
    "completedAt": "2020-06-03T12:28:06.7964868+00:00"
}

Delete a Crate from your account whether you own it, or another user has shared it with you. To call this route successfully you must have administrative permissions for the Crate.

HTTP Request

DELETE /crate/{uuid}

URL Parameters

Parameter Description
uuid The UUID of the Crate to delete.

Response Codes

200 Ok - The deletion process has been started, the operation to track this request has been returned.

403 Forbidden - You do not have permission to delete that Crate.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted or is in the process of being deleted.

412 Precondition Failed - The Crate can not be deleted as another operation is in progress.

Start a Crate

curl -XPOST "https://api.battlecrate.co.uk/1.0/crate/{uuid}/start?timeout=30" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "uuid": "2d1e8ac3-0bbf-4d35-a829-63324b3fbb51",
    "type": "Start",
    "isCompleted": true,
    "isCompletedSuccesfully": true,
    "createdAt": "2020-06-03T12:28:06.0937006+00:00",
    "completedAt": "2020-06-03T12:28:06.7964868+00:00"
}

Start a Crate from your account whether you own it, or another user has shared it with you. To call this route successfully the Crate must already be in the stopped state. This process is asynchronous so the Crate may not be available immediately.

HTTP Request

POST /crate/{uuid}/start

URL Parameters

Parameter Description
uuid The UUID of the Crate to start.

Query Parameters

Parameter Description Default Misc
timeout The timeout (in seconds) to wait for the call to complete. 30 Minimum 1, Maximum 30

Response Codes

200 Ok - The start command has been received by the Crate - the operation to track this request has been returned.

403 Forbidden - You do not have the required permissions to change the state of this Crate.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted.

412 Precondition Failed - The start command can not be accepted currently, this may be because another operation is running or the Crate is not in a suitable state to issue a start command.

Stop a Crate

curl -X POST "https://api.battlecrate.co.uk/1.0/crate/{uuid}/stop?timeout=30" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "uuid": "16dc1946-347c-49b0-815d-cba806fb4e78",
    "type": "Stop",
    "isCompleted": true,
    "isCompletedSuccesfully": true,
    "createdAt": "2020-06-03T12:28:06.0937006+00:00",
    "completedAt": "2020-06-03T12:28:06.7964868+00:00"
}

Stops a Crate from your account whether you own it, or another user has shared it with you. To call this route successfully the Crate must already be in the running state. This process is asynchronous so the Crate may not be available immediately.

HTTP Request

POST /crate/{uuid}/stop

URL Parameters

Parameter Description
uuid The UUID of the Crate to stop.

Query Parameters

Parameter Description Default Misc
timeout The timeout (in seconds) to wait for the command to complete. 30 Minimum 1, Maximum 30

Response Codes

200 Ok - The stop command has been received by the Crate - the operation to track this request has been returned.

403 Forbidden - You do not have the required permissions to change the state of this Crate.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted.

412 Precondition Failed - The stop command can not be accepted currently, this may be because another operation is running or the Crate is not in a suitable state to issue a stop command.

Restart a Crate

curl -X POST "https://api.battlecrate.co.uk/1.0/crate/{uuid}/restart?timeout=30" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "uuid": "cdfba9c3-dd98-4fb9-99c4-ae0271af6e9b",
    "type": "Restart",
    "isCompleted": true,
    "isCompletedSuccesfully": true,
    "createdAt": "2020-06-03T12:28:06.0937006+00:00",
    "completedAt": "2020-06-03T12:28:06.7964868+00:00"
}

Restarts a Crate from your account whether you own it, or another user has shared it with you. To call this route successfully the Crate must already be in the running state. This process is asynchronous so the Crate may not be available immediately.

HTTP Request

POST /crate/{uuid}/restart

URL Parameters

Parameter Description
uuid The UUID of the Crate to restart.

Query Parameters

Parameter Description Default Misc
timeout The timeout (in seconds) to wait for the command to complete. 30 Minimum 1, Maximum 30

Response Codes

200 Ok - The restart command has been received by the Crate - the operation to track this request has been returned.

403 Forbidden - You do not have the required permissions to change the state of this Crate.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted.

412 Precondition Failed - The restart command can not be accepted currently, this may be because another operation is running or the Crate is not in a suitable state to issue a restart command.

Get Players

curl -X GET "https://api.battlecrate.co.uk/1.0/crate/{uuid}/players" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "online": 3,
    "totalSlots": 10
}

Get the number of players that are currently connected to a Crate and the total number of available slots. To call this route successfully the Crate must already be in the running state. This information may be game specific.

HTTP Request

GET /crate/{uuid}/players

URL Parameters

Parameter Description
uuid The UUID of the Crate to get the player count for.

Response Codes

200 OK - The player count has been returned.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted.

412 Precondition Failed - The operation could not complete, this could be because the Crate is offline.

Send Command to Crate Console

Input a command into the console for a given Crate. To call this route successfully the Crate must already be in the running state.

We are building a new feature that will allow you to stream a Crate's console using WebSockets. We'll let you know when this is ready.

HTTP Request

POST /crate/{uuid}/console

URL Parameters

Parameter Description
uuid The UUID of the Crate to input a command to.

Response Codes

204 No Content - The restart command has been received by the Crate.

403 Forbidden - You do not have the required permissions to change the state of this Crate.

404 Not Found - Crate could not be found.

410 Gone - The Crate has been deleted.

412 Precondition Failed - The command can not be sent, this could be because the Crate is offline.

Crate Packages

A Crate Package represents a game. It contains different Profiles that can be used to configure a Crate as well as their corresponding Plans and Regions where it can be deployed. For example: minecraft is a Crate Package that contains Vanilla and Vanilla Bukkit Profiles, each of these Profiles then contain properties, this is where you change the version and pass in any extra information.

List Crate Packages

curl "https://api.battlecrate.co.uk/1.0/crate_package" -H "Authorization: Bearer {KEY}"

This command returns the following JSON.

{
    "results": [
        {
            "name": "minecraft",
            "displayName": "Minecraft",
            "iconUrl": {
                "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
            },
            "backgroundUrl": {
                "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
                "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
                "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
                "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
            },
            "profiles": [
                {
                    "name": "mc-1.15.2",
                    "displayName": "Vanilla 1.15.2",
                    "packageName": "minecraft",
                    "canDeploy": true
                }
            ],
            "totalProfileCount": 1,
            "plans": [
                {
                    "name": "mc-1",
                    "displayName": "Grass",
                    "pricing": {
                        "currency": "GBP",
                        "costHourly": 0.015,
                        "costMonthly": 5.0
                    },
                    "packageName": "minecraft",
                    "profileName": null,
                    "regionName": null,
                    "cpuCount": 1.0,
                    "memoryInMB": 1024,
                    "storageInMB": 5120,
                    "backupsInMB": 10240,
                    "canDeploy": true
                }
            ],
            "totalPlanCount": 1,
            "regions": [
                {
                    "name": "uk-1",
                    "displayName": "UK London",
                    "flagUrl": {
                        "0": "https://assets.battlecrate.io/images/regions/uk.svg"
                    },
                    "canDeploy": true
                }
            ],
            "totalRegionCount": 1,
            "canDeploy": true
        }
    ],
    "totalResults": 1,
    "limit": 25,
    "page": 1,
    "totalPages": 1
}

Get a list of packages, this will be returned in the standard Results Response with pagination.

HTTP Request

GET /crate_package

Query Parameters

Parameter Required Description Default Misc
limit No The maximum number of Crate Packages that can be returned. 25 Minimum: 1, Maximum: 50
page No The cursor for the next batch of results. 1 Minimum 1

Response Codes

200 OK

Get a Crate Package

curl "https://api.battlecrate.co.uk/1.0/crate_package/{name}" -H "Authorization: Bearer {KEY}"

This command returns the following JSON.

{
    "name": "minecraft",
    "displayName": "Minecraft",
    "iconUrl": {
        "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
    },
    "backgroundUrl": {
        "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
        "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
        "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
        "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
    },
    "profiles": [
        {
            "name": "mc-1.15.2",
            "displayName": "Vanilla 1.15.2",
            "packageName": "minecraft",
            "canDeploy": true
        }
    ],
    "totalProfileCount": 1,
    "plans": [
        {
            "name": "mc-1",
            "displayName": "Grass",
            "pricing": {
                "currency": "GBP",
                "costHourly": 0.015,
                "costMonthly": 5.0
            },
            "packageName": "minecraft",
            "profileName": null,
            "regionName": null,
            "cpuCount": 1.0,
            "memoryInMB": 1024,
            "storageInMB": 5120,
            "backupsInMB": 10240,
            "canDeploy": true
        }
    ],
    "totalPlanCount": 1,
    "regions": [
        {
            "name": "uk-1",
            "displayName": "UK London",
            "flagUrl": {
                "0": "https://assets.battlecrate.io/images/regions/uk.svg"
            },
            "canDeploy": true
        }
    ],
    "totalRegionCount": 1,
    "canDeploy": true
}

Retrieve a specific Crate Package.

HTTP Request

GET /crate_package/{name}

URL Parameters

Parameter Description
name The name of the Crate Package.

Response Codes

200 OK - Crate Package found.

404 Not Found - This Crate Package can not be found.

410 Gone - This Crate Package has been discontinued.

List Profiles in a Package

curl "https://api.battlecrate.co.uk/1.0/crate_package/minecraft" -H "Authorization: Bearer {KEY}"

This command returns the following JSON.

{
    "results": [
        {
            "name": "vanilla",
            "displayName": "Vanilla",
            "packageName": "minecraft",
            "canDeploy": true
        }
    ],
    "totalResults": 1,
    "limit": 25,
    "page": 1,
    "totalPages": 1
}

List all available Profiles inside a Crate Package. Read more about what this object represents in Crate Profiles.

HTTP Request

GET /crate_package/{name}

URL Parameters

Parameter Description
name The name of the Crate Package.

Query Parameters

Parameter Required Description Default Misc
limit No The maximum number of Crate Packages that can be returned. 25 Minimum: 1, Maximum: 50
page No The cursor for the next batch of results. 1 Minimum 1

Response Codes

200 OK

404 Not Found - That Crate Package could not be found.

Get properties for a Profile

curl "https://api.battlecrate.co.uk/1.0/crate_package/minecraft/profile/vanilla/properties" -H "Authorization: Bearer {KEY}"

This command returns the following JSON.

[
    {
        "name": "version",
        "default": "1.15.2",
        "valueType": "string",
        "required": true,
        "acceptedValues": [
            "1.15.2",
            "1.15.1"
        ]
    },
    {
        "name": "eula",
        "default": false,
        "valueType": "boolean",
        "required": true,
        "acceptedValues": [
            true
        ]
    }
]

List all available Properties for a specific Crate Profile. See Crate Profile Property.

Properties are attirbutes you are required to send when creating a new Crate - these properties are using in the deployment operation for the server.

HTTP Request

GET /crate_package/{packageName}/profile/{profileName}/properties

URL Parameters

Parameter Description
packageName The name of the Crate Package.
profileName The name of the Crate Profile.

Response Codes

200 OK

404 Not Found - That profile could not be found.

Regions

A Region represents a geographical location where BattleCrate services are deployed (for example: United Kingdom or EU). You should usually choose the Region that is closest to you/your players for the lowest latency.

List Regions

curl "https://api.battlecrate.co.uk/1.0/region" -H "Authorization: Bearer {KEY}"

This command returns the following JSON.

{
    "results": [
        {
            "name": "uk-1",
            "displayName": "UK London",
            "flagUrl": {
                "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
            },
            "canDeploy": true
        }
    ],
    "totalResults": 1,
    "limit": 25,
    "page": 1,
    "totalPages": 1
}

List all available Regions.

HTTP Request

GET /region

Query Parameters

Parameter Required Description Default Misc
limit No The maximum number of Regions that can be returned. 25 Minimum: 1, Maximum: 50
page No The cursor for the next batch of results. 1 Minimum 1

Response Codes

200 OK

Get Region

curl "https://api.battlecrate.co.uk/1.0/region/{name}" -H "Authorization: Bearer {KEY}"

This command returns the following JSON.

{
    {
        "name": "uk-1",
        "displayName": "UK London",
        "flagUrl": {
            "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
        },
        "canDeploy": true
    }
}

Get a specific Region.

HTTP Request

GET /region/{name}

URL Parameters

Parameter Description
name The name of the Region.

Response Codes

200 OK - Region found.

404 Not Found - This Region can not be found.

410 Gone - This Region has been discontinued.

Account

You can return information about your account using the following routes - you can not change information about your account through the API, anny account changes must be done through the (Web Console)[https://console.battlecrate.io].

Get basic account information

curl "https://api.battlecrate.co.uk/1.0/account" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

{
    "emailAddress": "test@battlecrate.io",
    "givenName": "Test",
    "familyName": "User",
    "country": "GB"
}

This route returns basic information about your account.

HTTP Request

GET /account

Response Codes

200 OK

Get balances for your account

curl "https://api.battlecrate.co.uk/1.0/account/balance" -H "Authorization: Bearer: {KEY}"

This command returns the following JSON body.

[
    {
        "currency": "GBP",
        "amount": 10.05
    }
]

This route returns a list of Balance Objects, this will contain the three character code of the currency and a decimal of how much of that currency your account holds.

HTTP Request

GET /account/balance

Response Codes

200 OK

Object Definitions

Result Response

{
    "results": [],
    "totalResults": 0,
    "limit": 10,
    "page": 0,
    "totalPages": 0
}

A result object is a generalised return format used by this API. It is used to return pages of results in a reusable format. When a result object is returned, you can usually supply the query parameters page and limit.

Attribute Type Description
results Array An array of objects. The object type will be defined per the request.
totalResults Integer The total number of results, not just those on this page.
limit Integer The limit for each page.
page Integer The current page.
totalPages Integer The total number of available pages.

Crate

{
    "uuid": "bf05936b-3b82-4d02-83f2-767e935e38f0",
    "name": "Example Crate",
    "state": "running",
    "region" : {
        "name": "uk-1",
        "displayName": "UK London",
        "flagUrl": {
            "0": "https://assets.battlecrate.io/images/regions/uk.svg"
        },
        "canDeploy": true
    },
    "package": {
        "name": "minecraft",
        "displayName": "Minecraft",
        "iconUrl": {
            "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
        },
        "backgroundUrl": {
            "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
            "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
            "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
            "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
        }
    },
    "profile": {
        "name": "vanilla",
        "displayName": "Vanilla",
        "packageName": "minecraft",
        "canDeploy": true
    },
    "plan": {
        "name": "mc-1",
        "displayName": "Grass",
        "pricing": [
            {
                "currency": "GBP",
                "costHourly": 0.03,
                "costMonthly": 5.0
            }
        ],
        "packageName": "minecraft",
        "profileName": null,
        "regionName": null,
        "cpuCount": 2.0,
        "memoryInMB": 1024,
        "storageInMB": 5120,
        "backupsInMB": 10240,
        "canDeploy": true
    },
    "permission": "owner",
    "createdAt": "2020-03-28T12:00:00.000000+00:00"
}
Attribute Type Description
uuid String The unique ID of the Crate.
name String The name of the Crate. A Crate name can only contain the following characters: "a-z", "A-Z", "0-9", "_", "-", "[]", "+"
state String The current state of the Crate. (See Crate States)
region RegionObject The Region the Crate is running in. (See Region)
package CratePackageObject The Crate Package the Crate is running. (See Crate Package)
profile CrateProfileObject The Profile the Crate is running. (See Crate Profile)
plan CratePlanObject The Plan your Crate is currently running. (See Crate Plan)
permission String The permission level you have on this Crate. (See Permissions)
createdAt DateTime The date and time when the Crate was created in ISO 8601 format.

Crate States

A Crate can be in any of the following states:

Crate Package

{
    "name": "minecraft",
    "displayName": "Minecraft",
    "iconUrl": {
        "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
    },
    "backgroundUrl": {
        "256": "https://assets.battlecrate.io/images/packages/minecraft/background-256.jpg",
        "512": "https://assets.battlecrate.io/images/packages/minecraft/background-512.jpg",
        "768": "https://assets.battlecrate.io/images/packages/minecraft/background-768.jpg",
        "1024": "https://assets.battlecrate.io/images/packages/minecraft/background-1024.jpg"
    },
    "profiles": [
        {
            "name": "vanilla",
            "displayName": "Vanilla",
            "packageName": "minecraft",
            "canDeploy": true
        }
    ],
    "totalProfileCount": 1,
    "plans": [
        {
            "name": "mc-1",
            "displayName": "Grass",
            "pricing": {
                "currency": "GBP",
                "costHourly": 0.03,
                "costMonthly": 5.0
            },
            "packageName": "minecraft",
            "profileName": null,
            "regionName": null,
            "cpuCount": 1.0,
            "memoryInMB": 1024,
            "storageInMB": 5120,
            "backupsInMB": 10240,
            "canDeploy": true
        }
    ],
    "totalPlanCount": 1,
    "regions": [
        {
            "name": "uk-1",
            "displayName": "UK",
            "flagUrl": {
                "0": "https://assets.battlecrate.io/images/regions/uk.svg",
            },
            "canDeploy": true
        }
    ],
    "totalRegionCount": 1,
    "canDeploy": true
}
Attribute Type Description
name String The unique name of this Crate Package.
displayName String The display name of this Crate Package.
profiles Array (CrateProfileObject) An array of Profile objects for this package. (See Crate Profile)
totalProfileCount Integer The total number of Profiles available for this Crate Package.
plans Array (CratePlanObject) An array of Plan objects this Crate Package can run on. (See Crate Plan)
totalPlanCount Integer The total number of Plans available for this Crate Package.
regions Array (RegionObject) An array of Region objects this Crate Package can run in. (See Region)
totalRegionCount Integer The total number of Regions that support this Crate Package.
canDeploy Bool Whether this Region can have services deployed to it.

Crate Profile

{
    "name": "vanilla",
    "displayName": "Vanilla"
}
Attribute Type Description
name String The unique name of this Profile.
displayName String The display name of the Profile.

Crate Profile Property

{
    "name": "version",
    "default": "1.15.2",
    "valueType": "string",
    "required": true,
    "acceptedValues": [
        "1.15.2",
        "1.15.1",
        "1.15"
    ]
}
Attribute Type Description
name String The name of the property, this is the key in the dictionary provided when deploying a Crate. (See Deploy a new Crate)
default Various If a default is set for this property, then a value of the correct value type for this property will be returned.
valueType String The type of field required: string, integer, guid, float, boolean.
required Boolean Is this a field you must provide?
acceptedValues Array (Various) If not null, this is an array of values you could provide, you must select a value from this list, if null, any value of the correct type may be accepted.

Crate Plan

{
    "name": "mc-1",
    "displayName": "Grass",
    "pricing": {
        "currency": "GBP",
        "costHourly": 0.03,
        "costMonthly": 5.0
    },
    "packageName": "minecraft",
    "profileName": null,
    "regionName": null,
    "cpuCount": 1,
    "memoryInMB": 1024,
    "storageInMB": 5120,
    "backupsInMB": 10240,
    "canUse": true
}
Attribute Type Description
name String The unique name of the Plan.
displayName String The display name of the Plan.
pricing Array (PricingObject) An array of different currencies available for this plan. Depending on where you are viewing this object, pricing may not be included. (See Pricing)
packageName String The name of the Crate Package that this Plan belongs to.
profileName String / Null The name of the Profile that this Plan can be deployed to, if specific. Otherwise, null.
regionname String / Null The name of the Region that this Plan can be deployed to, if specific. Otherwise, null.
cpuCount Double The number of vCPUs provided by this Plan.
memoryInMB Integer The amount of memory (in MB) provided by this Plan.
storageInMB Integer The amount of storage (in MB) provided by this Plan.
backupsInMB Integer The amount of backup-allocated-storage (in MB) provided by this Plan.
canUse Boolean Whether this plan can currently be deployed.

Pricing

{
    "currency": "GBP",
    "costHourly": 0.03,
    "costMonthly": 5.0
}
Attribute Type Description
currency String The currency code that this plan is billed in, in ISO 4217 format.
costHourly Decimal The amount that will billed each hour for this Crate.
costMonthly Decimal The cost this plan will cap out at, per month. (This is calculated by costMonthly / (7 * 24)). This is because the Crate bills each hour for the first seven days, after that you hit the monthly cost of the Crate and it is free for the remainder of the period.

Region

{
    "name": "uk-1",
    "displayName": "UK London",
    "flagUrl": {
        "0": "https://assets.battlecrate.io/images/packages/minecraft/icon.svg"
    },
    "canDeploy": true
}
Attribute Type Description
name String The unique name of the Region.
displayName String The display name of the Region.
flagUrl Dictionary The flag icons, 0 will be an SVG.
canDeploy Boolean Determines if you can deploy to this region.

Operation

{
    "uuid": "b53e249f-c3ce-4a37-9dec-eb55c64fa434",
    "type": "Start",
    "isCompleted": true,
    "isCompletedSuccesfully": true,
    "createdAt": "2020-06-03T12:28:06.0937006+00:00",
    "completedAt": "2020-06-03T12:28:06.7964868+00:00"
}
Attribute Type Description
uuid Guid The unique id of the operation.
type String The type of operation.
isCompleted Boolean Is the operation completed.
isCompletedSuccesfully Boolean If the operation is completed, did it complete succesfully.
createdAt DateTime The datetime the operation was created.
completedAt DateTime / Null The datetime the operation was completed.

Balance

{
    "currency": "GBP",
    "amount": 5.01
}
Attribute Type Description
currency String The three character code of the balance.
amount Decimal The amount of that currency on the account.

User

{
    "emailAddress": "test@battlecrate.io",
    "givenName": "Test",
    "familyName": "User",
    "country": "GB"
}
Attribute Type Description
emailAddress String The email address for your account.
givenName String Your given name,
familyName String Your family name.
country String The two character ISO standard country code for your country.

Permissions

Permissions are used to control what users can do with your Crates when shared.

Outlined below is the hierarchy of permission levels.

owner - Assigned to the user who pays for the resource. The resource belongs to their account.

admin - This permission grants the user the ability to perform any action on a resource.

write - This permission grants the user the ability to write information to a resource. They do not have permission to destructive operations (for example: deleting a Crate).

read - This permission grants the user the ability to view resources but not modify it in any way.

Errors

The BattleCrate API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key/secret combindation is wrong.
403 Forbidden -- You do not have permission to perform that action.
404 Not Found -- The route or object you tried to access could not be found.
405 Method Not Allowed -- You tried to access a route with the incorrect method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
429 Too Many Requests -- You're requesting too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.