Cosmoner Docs
API Reference

Variables

Non-sensitive configuration, stored and returned in plaintext and scoped to a deployment environment. For values that must not be readable, use secrets instead.

List variables

GET
/v1/projects/{projectId}/variables

Every variable on the project, oldest first, with values included — variables hold non-sensitive configuration and are stored in plaintext. Use secrets for anything that must not be readable.

Pass environment to narrow the list to one environment. Variables in default apply to every environment unless an entry with the same name exists for that environment.

Auth: a project API key carrying variables: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

environment?string

Value in

  • "default"
  • "development"
  • "staging"
  • "production"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/variables"
{  "success": true,  "data": [    {      "id": "string",      "name": "string",      "description": "string",      "value": "string",      "environment": "default",      "createdBy": "string",      "updatedBy": "string",      "createdByUser": {        "id": "string",        "name": "string",        "email": "[email protected]"      },      "updatedByUser": {        "id": "string",        "name": "string",        "email": "[email protected]"      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Create a variable

POST
/v1/projects/{projectId}/variables

Names are unique per environment, so the same name may exist once in default and once in production. A name already present in the target environment returns 409 CONFLICT.

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

Role: the caller must be an owner or admin of the project.

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

curl -X POST "https://example.com/v1/projects/string/variables" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "value": "string"  }'
{  "success": true,  "data": {    "id": "string",    "name": "string",    "description": "string",    "value": "string",    "environment": "default",    "createdBy": "string",    "updatedBy": "string",    "createdByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "updatedByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Fetch a variable

GET
/v1/projects/{projectId}/variables/{variableId}

Auth: a project API key carrying variables: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
variableId*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/variables/string"
{  "success": true,  "data": {    "id": "string",    "name": "string",    "description": "string",    "value": "string",    "environment": "default",    "createdBy": "string",    "updatedBy": "string",    "createdByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "updatedByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Update a variable

PATCH
/v1/projects/{projectId}/variables/{variableId}

Changes the value, the description, or both. Send at least one of them; a body with neither is rejected.

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

Role: the caller must be an owner or admin of the project.

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
variableId*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/variables/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "success": true,  "data": {    "id": "string",    "name": "string",    "description": "string",    "value": "string",    "environment": "default",    "createdBy": "string",    "updatedBy": "string",    "createdByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "updatedByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Delete a variable

DELETE
/v1/projects/{projectId}/variables/{variableId}

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

Role: the caller must be an owner or admin of the project.

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
variableId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/projects/string/variables/string"
Empty
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Secrets

Encrypted configuration. A secret's value is returned exactly once — by the call that sets it — and never again; reads describe the secret without handing the plaintext back. For values that do not need protecting, use variables instead.

Infrastructure

The catalogue of what can be created: the sizes on sale and their monthly list prices, in US dollars before tax. The catalogue is the same for every customer and reads nothing from a project, so any valid API key can read it, whatever its scopes. Answers are cached for a few minutes, so a change to what is on sale can take that long to show. A size's `slug` is what a create call takes to choose it. For what creating a resource would actually be charged — tax and any project credit included — use the preview call next to its create call. App sizes are listed here. Redis plans and regions are listed under [Redis](/docs/api/redis). The sizes, regions and templates a server can be created with, and the sizes, versions and regions of an always-on database, are shown in the control panel's create forms and are not described here yet.

On this page

List variablesCreate a variableFetch a variableUpdate a variableDelete a variable