Clanker instructions

Clanker instructions that no status holds: the defaults a clanker's new ticket gets, and how to write test cases, specs, a Fixture API and test CI. A workspace and each team can set their own; a team's replace the workspace's, which replace Clanker Ship's defaults. Each status keeps its own instructions for its document and work; see Ticket statuses.

The ClankerInstructions object

The instructions of one kind that a team's clankers follow, and where they come from.

Attributes

kindstringRequired

What the instructions shape: ticket for the defaults a clanker's new ticket gets, test-cases for test cases, test-code for specs, fixtures for a product's Fixture API and test-ci for the CI that runs tests. Each status keeps its own instructions for its document and work.

One oftickettest-casestest-codefixturestest-ci

sourcestringRequired

Where these come from: the team's own (team), the workspace's (workspace) or Clanker Ship's defaults (default).

One ofteamworkspacedefault

teamnullable objectRequired

The team asked about, or null for the workspace's instructions.

templatesarray of objectsRequired

One template for every ticket, and at most one more per tag; empty for ticket instructions.

guidancestringRequired

How the clanker should write, in Markdown; empty for ticket instructions.

defaultsnullable objectRequired

What new tickets from clankers get; null for the test kinds.

updatedAtnullable stringRequired

When these were last set, as an ISO 8601 timestamp; null for Clanker Ship's defaults.

updatedBynullable objectRequired

Who last set these; null for Clanker Ship's defaults or when an account API key set them.

The ClankerInstructions object

{  "kind": "ticket",  "source": "team",  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web"  },  "templates": [],  "guidance": "",  "defaults": {    "status": "Plan",    "tags": [],    "owner": "creator",    "clankers": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": null  }}

Get clanker instructions

GET/v1/workspaces/{slug}/clanker-instructions

Returns the instructions a team's clankers follow: the team's own, else the workspace's, else Clanker Ship's defaults. Without team, returns the workspace's or Clanker Ship's. source says which.

Path parameters

slugstringRequired

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

Query parameters

kindstringRequired

What the instructions shape: ticket for the defaults a clanker's new ticket gets, test-cases for test cases, test-code for specs, fixtures for a product's Fixture API and test-ci for the CI that runs tests.

One oftickettest-casestest-codefixturestest-ci

teamstring

A team's key, such as WEB. Leave it out for the workspace's instructions.

Returns

Returns the ClankerInstructions 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}/clanker-instructions

1curl "https://api.clankership.com/v1/workspaces/acme/clanker-instructions?kind=ticket" \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "kind": "ticket",  "source": "team",  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web"  },  "templates": [],  "guidance": "",  "defaults": {    "status": "Plan",    "tags": [],    "owner": "creator",    "clankers": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": null  }}

Set clanker instructions

PUT/v1/workspaces/{slug}/clanker-instructions

Sets the workspace's or a team's own instructions. Fields left out keep their current values, so a team's first change copies what it inherits. Owners and admins set the workspace's, and a team's members also set the team's; viewers cannot. Only ticket instructions take defaults.

Path parameters

slugstringRequired

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

Body parameters

kindstringRequired

What the instructions shape: ticket for the defaults a clanker's new ticket gets, test-cases for test cases, test-code for specs, fixtures for a product's Fixture API and test-ci for the CI that runs tests.

One oftickettest-casestest-codefixturestest-ci

teamnullable string

A team's key, such as WEB. Leave it out for the workspace's instructions.

templatesarray of objects

Replaces the templates: exactly one without a tag, and at most one more per tag, up to 20 in all. Not for ticket instructions.

guidancestring

How the clanker should write, in Markdown, up to 20,000 characters. Not for ticket instructions.

defaultsobject

What a ticket a clanker creates gets for each of these fields the clanker leaves out.

Returns

Returns the ClankerInstructions 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.

PUT/v1/workspaces/{slug}/clanker-instructions

1curl -X PUT https://api.clankership.com/v1/workspaces/acme/clanker-instructions \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "kind": "ticket",6    "team": "WEB",7    "defaults": {8      "status": "Plan",9      "tags": [],10      "owner": "creator",11      "clankers": "creator"12    }13  }'

Response200

{  "kind": "ticket",  "source": "team",  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web"  },  "templates": [],  "guidance": "",  "defaults": {    "status": "Plan",    "tags": [],    "owner": "creator",    "clankers": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": null  }}

Reset clanker instructions

DELETE/v1/workspaces/{slug}/clanker-instructions

Removes the workspace's or a team's own instructions, so it follows what it inherits again, and returns the instructions that now apply. The people who can set the instructions can reset them.

Path parameters

slugstringRequired

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

Query parameters

kindstringRequired

What the instructions shape: ticket for the defaults a clanker's new ticket gets, test-cases for test cases, test-code for specs, fixtures for a product's Fixture API and test-ci for the CI that runs tests.

One oftickettest-casestest-codefixturestest-ci

teamstring

A team's key, such as WEB. Leave it out for the workspace's instructions.

Returns

Returns the ClankerInstructions 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.

DELETE/v1/workspaces/{slug}/clanker-instructions

1curl -X DELETE "https://api.clankership.com/v1/workspaces/acme/clanker-instructions?kind=ticket" \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "kind": "ticket",  "source": "team",  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web"  },  "templates": [],  "guidance": "",  "defaults": {    "status": "Plan",    "tags": [],    "owner": "creator",    "clankers": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": null  }}