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"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

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"  }}
{  "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 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"  }}
{  "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"  }}

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"  }}
{  "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"  }}

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"  }}
{  "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"  }}

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.

API Keys

Create and manage API keys with scoped permissions for programmatic access.

On this page

List variablesCreate a variableFetch a variableUpdate a variableDelete a variable