Agent instructions

Agent instructions teach a team's agents 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 AgentInstructions object

The instructions of one kind that a team's agents 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 agent should write, in Markdown.

defaultsnullable objectRequired

What new tickets from agents 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 AgentInstructions 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": "Todo",    "tags": [],    "owner": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": null  }}

Get agent instructions

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

Returns the instructions a team's agents 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 AgentInstructions 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}/agent-instructions

1curl "https://api.qa.clankership.net/v1/workspaces/acme/agent-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": "Todo",    "tags": [],    "owner": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": null  }}

Set agent instructions

PUT/v1/workspaces/{slug}/agent-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 agent should write, in Markdown, up to 20,000 characters.

defaultsobject

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

Returns

Returns the AgentInstructions 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}/agent-instructions

1curl -X PUT https://api.qa.clankership.net/v1/workspaces/acme/agent-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": "Todo",19      "tags": [],20      "owner": "creator"21    }22  }'

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": "Todo",    "tags": [],    "owner": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": null  }}

Reset agent instructions

DELETE/v1/workspaces/{slug}/agent-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 AgentInstructions 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}/agent-instructions

1curl -X DELETE "https://api.qa.clankership.net/v1/workspaces/acme/agent-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": "Todo",    "tags": [],    "owner": "creator"  },  "updatedAt": "2026-10-14T09:05:12.000Z",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": null  }}

NextAgents