Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Products

A product is a piece of software the workspace builds and tests, such as a website, an API or a CLI. It runs in environments through deployments, and its test runs and secrets belong to it.

The Product object

Software the workspace builds and tests.

Attributes

idstringRequired

Unique ID of the product.

slugstringRequired

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

namestringRequired

The product's display name.

typestringRequired

What kind of software the product is.

One ofwebsiteapiclimobile_appdesktop_appagent
descriptionnullable stringRequired

A short description, or null.

repositorynullable stringRequired

The source repository, such as acme/storefront, that agent sessions report.

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 environment is active.

The Product object
{  "id": "Pr4GtY9sLm3B",  "slug": "storefront",  "name": "Storefront",  "type": "website",  "description": "The customer-facing shop.",  "repository": "acme/storefront",  "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 products

GET/v1/workspaces/{slug}/products

Returns the workspace's products with their active deployments. Archived products are left out unless archived asks for them.

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.

productsarray of Product objectsRequired

The products, 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}/products
curl https://api.qa.clankership.net/v1/workspaces/acme/products \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront",      "type": "website",      "description": "The customer-facing shop.",      "repository": "acme/storefront",      "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 a product

POST/v1/workspaces/{slug}/products

Adds a product to the workspace. Viewers cannot create products, and the slug must be unused.

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 storefront.

namestringRequired

The product's display name.

typestringRequired

What kind of software this is.

One ofwebsiteapiclimobile_appdesktop_appagent
descriptionnullable string

A short description.

repositorynullable string

The source repository as owner/name, such as acme/storefront.

Returns

Returns the Product 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}/products
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/products \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "slug": "storefront",    "name": "Storefront",    "type": "website",    "repository": "acme/storefront"  }'
Response201
{  "id": "Pr4GtY9sLm3B",  "slug": "storefront",  "name": "Storefront",  "type": "website",  "description": "The customer-facing shop.",  "repository": "acme/storefront",  "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 a product

GET/v1/workspaces/{slug}/products/{product}

Returns one product, archived or not, with its active deployments.

Path parameters

slugstringRequired

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

productstringRequired

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

Returns

Returns the Product 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}/products/{product}
curl https://api.qa.clankership.net/v1/workspaces/acme/products/{product} \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "id": "Pr4GtY9sLm3B",  "slug": "storefront",  "name": "Storefront",  "type": "website",  "description": "The customer-facing shop.",  "repository": "acme/storefront",  "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 a product

PATCH/v1/workspaces/{slug}/products/{product}

Changes only the fields sent. A new slug must be unused in the workspace.

Path parameters

slugstringRequired

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

productstringRequired

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

Body parameters

slugstring

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

namestring

The product's display name.

typestring

What kind of software this is.

One ofwebsiteapiclimobile_appdesktop_appagent
descriptionnullable string

A short description. null clears it.

repositorynullable string

The source repository as owner/name, such as acme/storefront. null clears it.

Returns

Returns the Product 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}/products/{product}
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/products/{product} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Storefront web",    "repository": "acme/storefront"  }'
Response200
{  "id": "Pr4GtY9sLm3B",  "slug": "storefront",  "name": "Storefront",  "type": "website",  "description": "The customer-facing shop.",  "repository": "acme/storefront",  "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 a product

POST/v1/workspaces/{slug}/products/{product}/archive

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

Path parameters

slugstringRequired

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

productstringRequired

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

Returns

Returns the Product 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}/products/{product}/archive
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/products/{product}/archive \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "id": "Pr4GtY9sLm3B",  "slug": "storefront",  "name": "Storefront",  "type": "website",  "description": "The customer-facing shop.",  "repository": "acme/storefront",  "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 a product

POST/v1/workspaces/{slug}/products/{product}/restore

Brings an archived product back with its deployments and secrets. Restoring an active product changes nothing.

Path parameters

slugstringRequired

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

productstringRequired

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

Returns

Returns the Product 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}/products/{product}/restore
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/products/{product}/restore \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "id": "Pr4GtY9sLm3B",  "slug": "storefront",  "name": "Storefront",  "type": "website",  "description": "The customer-facing shop.",  "repository": "acme/storefront",  "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"    }  ]}
NextEnvironments