Cosmoner Docs
API Reference

Servers

Dedicated machines in a project. The keys that can log into a server are fixed when it is created — they are written to the machine at first boot — so decide them before provisioning, not after.

List servers

GET
/v1/projects/{projectId}/servers

Every server in the project, newest first. Terminated servers are omitted.

Each server's status and public address are reconciled with the platform as part of this read, so a machine that has finished starting reports RUNNING here first.

Auth: a project API key carrying servers:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/servers"
{  "success": true,  "data": [    {      "id": "string",      "organizationId": "string",      "name": "string",      "type": "LAMP",      "region": "string",      "instanceType": "string",      "status": "PROVISIONING",      "ipAddress": "string",      "hostname": "string",      "sshUser": "string",      "phpVersion": "string",      "pgVersion": "string",      "pgDatabase": "string",      "pgUsername": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Provision a server

POST
/v1/projects/{projectId}/servers

Provisions a server and adds it to the project's subscription.

sshKeyIds is the only chance to decide who can log in: the keys are written to the machine when it first boots, and none can be added afterwards. A server created without any cannot be reached at all, short of rebuilding it.

Billing is charged to the project's saved card. A project with no usable card returns 402. Provisioning is transactional — a failure part-way rolls back what it created.

Auth: a project API key carrying all of servers:read and servers:write.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects/string/servers" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "slug": "string",    "provider": "digitalocean",    "region": "string"  }'
{  "success": true,  "data": {    "deployed": true  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Fetch a server

GET
/v1/projects/{projectId}/servers/{id}

The server, with the keys authorised on it — enough to build the connect instructions, naming the right user and key.

Auth: a project API key carrying servers:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/servers/string"
{  "success": true,  "data": {    "id": "string",    "organizationId": "string",    "name": "string",    "type": "LAMP",    "region": "string",    "instanceType": "string",    "status": "PROVISIONING",    "ipAddress": "string",    "hostname": "string",    "sshUser": "string",    "phpVersion": "string",    "pgVersion": "string",    "pgDatabase": "string",    "pgUsername": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "sshKeys": [      {        "id": "string",        "name": "string",        "fingerprint": "string"      }    ]  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Rename a server

PATCH
/v1/projects/{projectId}/servers/{id}

Renames the machine upstream first, so a failure leaves both sides on the old name rather than disagreeing.

Auth: a project API key carrying all of servers:read and servers:write.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
id*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/projects/string/servers/string" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "success": true,  "data": {    "id": "string",    "organizationId": "string",    "name": "string",    "type": "LAMP",    "region": "string",    "instanceType": "string",    "status": "PROVISIONING",    "ipAddress": "string",    "hostname": "string",    "sshUser": "string",    "phpVersion": "string",    "pgVersion": "string",    "pgDatabase": "string",    "pgUsername": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Destroy a server

DELETE
/v1/projects/{projectId}/servers/{id}

Destroys the machine and stops billing for it. The data on it is not recoverable.

If the call fails part-way the server stays visible and the call can be retried — it is never left billing invisibly.

Auth: a project API key carrying all of servers:read and servers:write.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/projects/string/servers/string"
{  "success": true,  "data": {}}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Power a server on, off, or reboot it

POST
/v1/projects/{projectId}/servers/{id}/actions

Power actions are applied asynchronously, so the server comes back as PROVISIONING — the state it sits in while the action settles. Read the server again to see where it lands.

Returns 409 if the action does not fit the current state: powering on a running server, or stopping one that is not running.

Auth: a project API key carrying all of servers:read and servers:write.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
id*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects/string/servers/string/actions" \  -H "Content-Type: application/json" \  -d '{    "action": "power_on"  }'
{  "success": true,  "data": {    "id": "string",    "organizationId": "string",    "name": "string",    "type": "LAMP",    "region": "string",    "instanceType": "string",    "status": "PROVISIONING",    "ipAddress": "string",    "hostname": "string",    "sshUser": "string",    "phpVersion": "string",    "pgVersion": "string",    "pgDatabase": "string",    "pgUsername": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Preview what a server will cost

GET
/v1/projects/{projectId}/servers/preview

What provisioning a given size would be charged today and each month after, before committing to it.

Auth: a project API key carrying servers:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Query Parameters

provider*"digitalocean"

Value in

  • "digitalocean"
slug*string

The size to price, as listed by the catalogue.

Match^[A-Za-z0-9][A-Za-z0-9._-]*$
Length1 <= length <= 64

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/servers/preview?provider=digitalocean&slug=string"
{  "success": true,  "data": {    "subtotal": -9007199254740991,    "tax": -9007199254740991,    "creditApplied": -9007199254740991,    "dueToday": -9007199254740991,    "monthly": -9007199254740991,    "currency": "string",    "nextBillingDate": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Apps

Manage app deployments, networking, domains, and monitoring.

SSH keys

Public keys that authorise access to the servers in a project. A key is written to a server by cloud-init at first boot, so it must be registered *before* the server that should trust it is created.

On this page

List serversProvision a serverFetch a serverRename a serverDestroy a serverPower a server on, off, or reboot itPreview what a server will cost