Clanker instructions

Clanker instructions teach a team's clankers how to write tickets and plans: templates, writing guidance and, for tickets, default values. A workspace and each team can set their own; a team's replace the workspace's, which replace Clanker Ship's defaults.

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 a ticket's summary, plan for its plan, 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 ofticketplantest-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.

guidancestringRequired

How the clanker should write, in Markdown.

defaultsnullable objectRequired

What new tickets from clankers get; null for plan instructions.

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": [    {      "tag": null,      "body": "## Problem\nWhat is wrong or missing, and for whom.\n\n## Outcome\nWhat is true when this ticket is done."    },    {      "tag": "bug",      "body": "## Steps to reproduce\n\n## Expected\n\n## Actual"    }  ],  "guidance": "- Keep the title short: what changes, and where.\n- Use the team's tags. Do not invent new ones.",  "defaults": {    "status": "In Planning",    "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

One ofticketplantest-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.qa.clankership.net/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": [    {      "tag": null,      "body": "## Problem\nWhat is wrong or missing, and for whom.\n\n## Outcome\nWhat is true when this ticket is done."    },    {      "tag": "bug",      "body": "## Steps to reproduce\n\n## Expected\n\n## Actual"    }  ],  "guidance": "- Keep the title short: what changes, and where.\n- Use the team's tags. Do not invent new ones.",  "defaults": {    "status": "In Planning",    "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

One ofticketplantest-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.

guidancestring

How the clanker should write, in Markdown, up to 20,000 characters.

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.qa.clankership.net/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    "templates": [8      {9        "tag": null,10        "body": "## Problem\nWhat is wrong or missing, and for whom.\n\n## Outcome\nWhat is true when this ticket is done."11      },12      {13        "tag": "bug",14        "body": "## Steps to reproduce\n\n## Expected\n\n## Actual"15      }16    ],17    "defaults": {18      "status": "In Planning",19      "tags": [],20      "owner": "creator",21      "clankers": "creator"22    }23  }'

Response200

{  "kind": "ticket",  "source": "team",  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web"  },  "templates": [    {      "tag": null,      "body": "## Problem\nWhat is wrong or missing, and for whom.\n\n## Outcome\nWhat is true when this ticket is done."    },    {      "tag": "bug",      "body": "## Steps to reproduce\n\n## Expected\n\n## Actual"    }  ],  "guidance": "- Keep the title short: what changes, and where.\n- Use the team's tags. Do not invent new ones.",  "defaults": {    "status": "In Planning",    "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

One ofticketplantest-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.qa.clankership.net/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": [    {      "tag": null,      "body": "## Problem\nWhat is wrong or missing, and for whom.\n\n## Outcome\nWhat is true when this ticket is done."    },    {      "tag": "bug",      "body": "## Steps to reproduce\n\n## Expected\n\n## Actual"    }  ],  "guidance": "- Keep the title short: what changes, and where.\n- Use the team's tags. Do not invent new ones.",  "defaults": {    "status": "In Planning",    "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  }}

NextClankers