Environments

An environment is a place products run, such as staging or production. Every product in the workspace can deploy to it, and its class decides whether production rules apply.

The Environment object

A place products run, shared by every product in the workspace.

Attributes

idstringRequired

Unique ID of the environment.

slugstringRequired

Lowercase letters, digits and hyphens, unique in the workspace, such as staging.

namestringRequired

The environment's display name.

classstringRequired

Production holds real customer data; everything else is non-production.

One ofproductionnon-production

descriptionnullable stringRequired

A short description, or null.

emojinullable stringRequired

One emoji shown beside the environment's name, or null.

archivedAtnullable stringRequired

When it was archived, as an ISO 8601 timestamp; null while active.

createdAtstringRequired

When it was created, as an ISO 8601 timestamp.

updatedAtstringRequired

When it last changed, as an ISO 8601 timestamp.

deploymentsarray of Deployment objectsRequired

Deployments whose product is active.

The Environment object

{  "id": "En8RqZ2vKp5D",  "slug": "staging",  "name": "Staging",  "class": "non-production",  "description": "Where each merge to main lands before production.",  "emoji": "🧪",  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "deployments": [    {      "id": "Dp3FkR8wNv2T",      "product": {        "id": "Pr4GtY9sLm3B",        "slug": "storefront",        "name": "Storefront",        "type": "website",        "archived": false      },      "environment": {        "id": "En8RqZ2vKp5D",        "slug": "staging",        "name": "Staging",        "class": "non-production",        "emoji": "🧪",        "archived": false      },      "baseUrl": "https://staging.acme.dev",      "fixtureUrl": "https://staging.acme.dev/fixtures",      "version": "9f2c41e",      "versionUpdatedAt": "2026-10-14T09:05:12.000Z",      "active": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

List environments

GET/v1/workspaces/{slug}/environments

Returns the workspace's environments with the deployments of active products.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Query parameters

archivedstring

Which archived objects to return: exclude (the default), include or only archived ones.

One ofexcludeincludeonly

Returns

Returns an object with these fields. Status 200.

environmentsarray of Environment objectsRequired

The environments, sorted by name.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/workspaces/{slug}/environments

1curl https://api.qa.clankership.net/v1/workspaces/acme/environments \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "environments": [    {      "id": "En8RqZ2vKp5D",      "slug": "staging",      "name": "Staging",      "class": "non-production",      "description": "Where each merge to main lands before production.",      "emoji": "🧪",      "archivedAt": null,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z",      "deployments": [        {          "id": "Dp3FkR8wNv2T",          "product": {            "id": "Pr4GtY9sLm3B",            "slug": "storefront",            "name": "Storefront",            "type": "website",            "archived": false          },          "environment": {            "id": "En8RqZ2vKp5D",            "slug": "staging",            "name": "Staging",            "class": "non-production",            "emoji": "🧪",            "archived": false          },          "baseUrl": "https://staging.acme.dev",          "fixtureUrl": "https://staging.acme.dev/fixtures",          "version": "9f2c41e",          "versionUpdatedAt": "2026-10-14T09:05:12.000Z",          "active": true,          "createdAt": "2026-10-01T16:20:00.000Z",          "updatedAt": "2026-10-14T09:05:12.000Z"        }      ]    }  ]}

Create an environment

POST/v1/workspaces/{slug}/environments

Adds an environment every product in the workspace can deploy to. Viewers cannot create environments.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Body parameters

slugstringRequired

Lowercase letters, digits and hyphens, unique in the workspace, such as staging.

namestringRequired

The environment's display name.

classstringRequired

Production holds real customer data. It cannot change once set.

One ofproductionnon-production

descriptionnullable string

A short description.

emojinullable string

One emoji shown beside the name.

Returns

Returns the Environment object. Status 201.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/environments

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/environments \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "slug": "staging",6    "name": "Staging",7    "class": "non-production",8    "emoji": "🧪"9  }'

Response201

{  "id": "En8RqZ2vKp5D",  "slug": "staging",  "name": "Staging",  "class": "non-production",  "description": "Where each merge to main lands before production.",  "emoji": "🧪",  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "deployments": [    {      "id": "Dp3FkR8wNv2T",      "product": {        "id": "Pr4GtY9sLm3B",        "slug": "storefront",        "name": "Storefront",        "type": "website",        "archived": false      },      "environment": {        "id": "En8RqZ2vKp5D",        "slug": "staging",        "name": "Staging",        "class": "non-production",        "emoji": "🧪",        "archived": false      },      "baseUrl": "https://staging.acme.dev",      "fixtureUrl": "https://staging.acme.dev/fixtures",      "version": "9f2c41e",      "versionUpdatedAt": "2026-10-14T09:05:12.000Z",      "active": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Get an environment

GET/v1/workspaces/{slug}/environments/{environment}

Returns one environment, archived or not, with the deployments of active products.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

environmentstringRequired

The environment's slug or ID, such as staging.

Returns

Returns the Environment object. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/workspaces/{slug}/environments/{environment}

1curl https://api.qa.clankership.net/v1/workspaces/acme/environments/{environment} \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "En8RqZ2vKp5D",  "slug": "staging",  "name": "Staging",  "class": "non-production",  "description": "Where each merge to main lands before production.",  "emoji": "🧪",  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "deployments": [    {      "id": "Dp3FkR8wNv2T",      "product": {        "id": "Pr4GtY9sLm3B",        "slug": "storefront",        "name": "Storefront",        "type": "website",        "archived": false      },      "environment": {        "id": "En8RqZ2vKp5D",        "slug": "staging",        "name": "Staging",        "class": "non-production",        "emoji": "🧪",        "archived": false      },      "baseUrl": "https://staging.acme.dev",      "fixtureUrl": "https://staging.acme.dev/fixtures",      "version": "9f2c41e",      "versionUpdatedAt": "2026-10-14T09:05:12.000Z",      "active": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Update an environment

PATCH/v1/workspaces/{slug}/environments/{environment}

Changes only the fields sent. The class cannot change; sending it fails with InvalidInput.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

environmentstringRequired

The environment's slug or ID, such as staging.

Body parameters

slugstring

Lowercase letters, digits and hyphens, unique in the workspace, such as staging.

namestring

The environment's display name.

descriptionnullable string

A short description. null clears it.

emojinullable string

One emoji shown beside the name. null clears it.

classstring

Always rejected: an environment's class cannot change.

One ofproductionnon-production

Returns

Returns the Environment object. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

PATCH/v1/workspaces/{slug}/environments/{environment}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/environments/{environment} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Staging (EU)",6    "emoji": "🇪🇺"7  }'

Response200

{  "id": "En8RqZ2vKp5D",  "slug": "staging",  "name": "Staging",  "class": "non-production",  "description": "Where each merge to main lands before production.",  "emoji": "🧪",  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "deployments": [    {      "id": "Dp3FkR8wNv2T",      "product": {        "id": "Pr4GtY9sLm3B",        "slug": "storefront",        "name": "Storefront",        "type": "website",        "archived": false      },      "environment": {        "id": "En8RqZ2vKp5D",        "slug": "staging",        "name": "Staging",        "class": "non-production",        "emoji": "🧪",        "archived": false      },      "baseUrl": "https://staging.acme.dev",      "fixtureUrl": "https://staging.acme.dev/fixtures",      "version": "9f2c41e",      "versionUpdatedAt": "2026-10-14T09:05:12.000Z",      "active": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Archive an environment

POST/v1/workspaces/{slug}/environments/{environment}/archive

Hides the environment and refuses vault pulls for its deployments until it is restored. Archiving an archived environment changes nothing.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

environmentstringRequired

The environment's slug or ID, such as staging.

Returns

Returns the Environment object. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/environments/{environment}/archive

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/environments/{environment}/archive \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "En8RqZ2vKp5D",  "slug": "staging",  "name": "Staging",  "class": "non-production",  "description": "Where each merge to main lands before production.",  "emoji": "🧪",  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "deployments": [    {      "id": "Dp3FkR8wNv2T",      "product": {        "id": "Pr4GtY9sLm3B",        "slug": "storefront",        "name": "Storefront",        "type": "website",        "archived": false      },      "environment": {        "id": "En8RqZ2vKp5D",        "slug": "staging",        "name": "Staging",        "class": "non-production",        "emoji": "🧪",        "archived": false      },      "baseUrl": "https://staging.acme.dev",      "fixtureUrl": "https://staging.acme.dev/fixtures",      "version": "9f2c41e",      "versionUpdatedAt": "2026-10-14T09:05:12.000Z",      "active": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Restore an environment

POST/v1/workspaces/{slug}/environments/{environment}/restore

Brings an archived environment back with its deployments. Restoring an active environment changes nothing.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

environmentstringRequired

The environment's slug or ID, such as staging.

Returns

Returns the Environment object. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/environments/{environment}/restore

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/environments/{environment}/restore \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "En8RqZ2vKp5D",  "slug": "staging",  "name": "Staging",  "class": "non-production",  "description": "Where each merge to main lands before production.",  "emoji": "🧪",  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "deployments": [    {      "id": "Dp3FkR8wNv2T",      "product": {        "id": "Pr4GtY9sLm3B",        "slug": "storefront",        "name": "Storefront",        "type": "website",        "archived": false      },      "environment": {        "id": "En8RqZ2vKp5D",        "slug": "staging",        "name": "Staging",        "class": "non-production",        "emoji": "🧪",        "archived": false      },      "baseUrl": "https://staging.acme.dev",      "fixtureUrl": "https://staging.acme.dev/fixtures",      "version": "9f2c41e",      "versionUpdatedAt": "2026-10-14T09:05:12.000Z",      "active": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

NextDeployments