Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Deployments

A deployment says that one product runs in one environment, at which URL and which version. Test runs target a deployment, and vault pulls read the secrets of one.

The Deployment object

One product running in one environment.

Attributes

idstringRequired

Unique ID of the deployment.

productobjectRequired

The product that is deployed.

environmentobjectRequired

The environment it is deployed to.

baseUrlnullable stringRequired

The http(s) URL where the product answers in this environment. Required for website and API products.

fixtureUrlnullable stringRequired

The deployment's Fixture API, which test runs call to create and delete test data, or null when it has none.

versionnullable stringRequired

The build that is running, such as a git SHA, or null when unknown.

versionUpdatedAtnullable stringRequired

When version last changed, as an ISO 8601 timestamp.

activebooleanRequired

False while the product or the environment is archived.

createdAtstringRequired

When it was created, as an ISO 8601 timestamp.

updatedAtstringRequired

When it last changed, as an ISO 8601 timestamp.

The Deployment object
{  "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 deployments

GET/v1/workspaces/{slug}/deployments

Returns the workspace's deployments, optionally for one product or one environment.

Path parameters

slugstringRequired

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

Query parameters

productstring

Only deployments of this product, by slug or ID.

environmentstring

Only deployments to this environment, by slug or ID.

archivedstring

Whether to include deployments whose product or environment is archived. Defaults to exclude.

One ofexcludeincludeonly

Returns

Returns an object with these fields. Status 200.

deploymentsarray of Deployment objectsRequired

The deployments, sorted by product name and then environment 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}/deployments
curl https://api.qa.clankership.net/v1/workspaces/acme/deployments \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "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 a deployment

POST/v1/workspaces/{slug}/deployments

Records that a product runs in an environment. A product has at most one deployment per environment.

Path parameters

slugstringRequired

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

Body parameters

productstringRequired

The product to deploy, by slug or ID.

environmentstringRequired

The environment to deploy it to, by slug or ID.

baseUrlnullable string

The http(s) URL where the product answers. Required for website and API products.

fixtureUrlnullable string

The http(s) URL of the deployment's Fixture API, which test runs call to create and delete test data.

versionnullable string

The build that is running, such as a git SHA.

Returns

Returns the Deployment 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}/deployments
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/deployments \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "product": "storefront",    "environment": "staging",    "baseUrl": "https://staging.acme.dev",    "fixtureUrl": "https://staging.acme.dev/fixtures",    "version": "9f2c41e"  }'
Response201
{  "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 a deployment

GET/v1/workspaces/{slug}/deployments/{product}/{environment}

Returns the deployment of one product to one environment.

Path parameters

slugstringRequired

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

productstringRequired

The product's slug or ID, such as storefront.

environmentstringRequired

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

Returns

Returns the Deployment 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}/deployments/{product}/{environment}
curl https://api.qa.clankership.net/v1/workspaces/acme/deployments/{product}/{environment} \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "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 a deployment

PATCH/v1/workspaces/{slug}/deployments/{product}/{environment}

Changes only the fields sent. Send version after each deploy to record what is running.

Path parameters

slugstringRequired

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

productstringRequired

The product's slug or ID, such as storefront.

environmentstringRequired

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

Body parameters

baseUrlnullable string

The http(s) URL where the product answers. null clears it for products that do not need one.

fixtureUrlnullable string

The http(s) URL of the deployment's Fixture API. null clears it.

versionnullable string

The build that is running, such as a git SHA. null clears it.

Returns

Returns the Deployment 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}/deployments/{product}/{environment}
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/deployments/{product}/{environment} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "version": "4b7e0d2"  }'
Response200
{  "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"}

Delete a deployment

DELETE/v1/workspaces/{slug}/deployments/{product}/{environment}

Removes the deployment. Its secret values are kept and return if the product is deployed to the environment again.

Path parameters

slugstringRequired

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

productstringRequired

The product's slug or ID, such as storefront.

environmentstringRequired

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

Returns

Returns no content. Status 204.

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.
DELETE/v1/workspaces/{slug}/deployments/{product}/{environment}
curl -X DELETE https://api.qa.clankership.net/v1/workspaces/acme/deployments/{product}/{environment} \  -H "Authorization: Bearer $CLANKER_API_KEY"
NextTeams