# Ticket statuses A ticket status is a step in a team's workflow, such as Plan or Build, in one of seven fixed categories, the stages every ticket moves through: backlog, plan, build, review, ship, done and canceled. Each team has its own statuses, copied from the workspace's template when the team is created. A status holds a checklist template, which a ticket copies into its own checklist when it first enters the status, and instructions: the document its tickets keep there and how a clanker works it. Owners and admins add, rename, move and delete statuses; a team's members also change its statuses' templates and instructions. ## The TicketStatus object A step in a team's workflow, such as Plan or Build. ### Attributes - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. ### Example ```json { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false } ``` ## List ticket statuses `GET /v1/workspaces/{slug}/ticket-statuses` Returns a team's statuses or, without `team`, the workspace's template that new teams copy, with each status's checklist template and instructions. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in query): A team's key, such as WEB. Leave it out for the workspace's template. ### Returns Returns an object with these fields. The status is 200. - `statuses` (array of objects, required): The statuses in board order: by category, then by position, each with its checklist template. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order: the items a ticket's checklist starts with when the ticket first enters the status. Empty when the status has none. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `instructions` (object, required): What a status asks of a clanker: the document its tickets keep there, the Markdown that document starts from, and how to work the status. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "statuses": [ { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "instructions": { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end." } } ] } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Create a ticket status `POST /v1/workspaces/{slug}/ticket-statuses` Owners and admins add statuses. The new status goes last in its category and starts from its stage's checklist template and instructions; its document takes the stage's name, or the status's own when another status already keeps that one. A status added to the template reaches only teams created afterwards. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (nullable string): The key of the team to add the status to, such as WEB. Leave it out to add it to the workspace's template. - `name` (string, required): The status's name, up to 40 characters, unique within the team. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The status's category. It cannot change later. ### Returns Returns the [TicketStatus](https://docs.clankership.com/api/ticket-statuses/object.md) object. The status is 201. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "team": "WEB", "name": "In QA", "category": "review" }' ``` ### Response ```json { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Update a ticket status `PATCH /v1/workspaces/{slug}/ticket-statuses/{status}` Owners and admins rename a status or make it the default. Saved view filters follow a new name. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `name` (string): The status's name, up to 40 characters, unique within the team. - `isDefault` (boolean): `true` makes this the status new tickets get when none is named. Only a backlog status can be the default. Always `true`. ### Returns Returns the [TicketStatus](https://docs.clankership.com/api/ticket-statuses/object.md) object. The status is 200. ### Request ```bash curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status} \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "In development" }' ``` ### Response ```json { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Delete a ticket status `DELETE /v1/workspaces/{slug}/ticket-statuses/{status}` Owners and admins delete statuses. Every category keeps at least one status, and the default status cannot be deleted. Tickets that use the status move to `moveTo`, and tickets' checklists for the status join their checklists for `moveTo`. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `moveTo` (string, in query): The ID of another status of the same team that takes this status's tickets. Required when tickets use the status. ### Returns Returns no content. The status is 204. ### Request ```bash curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Reorder a ticket status `POST /v1/workspaces/{slug}/ticket-statuses/{status}/reorder` Moves a status right before or after another status of its category. Send `before` or `after`, not both. Owners and admins reorder statuses. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `before` (string): The ID of a status of the same category to go right before. - `after` (string): The ID of a status of the same category to go right after. ### Returns Returns an object with these fields. The status is 200. - `statuses` (array of objects, required): Every status of the same team, or of the template, in board order: by category, then by position. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/reorder \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "after": "St4IrG2wZf5M" }' ``` ### Response ```json { "statuses": [ { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false } ] } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Add a checklist template item `POST /v1/workspaces/{slug}/ticket-statuses/{status}/checklist` Adds an item to the end of a status's checklist template, which holds up to 30 items. Tickets that enter the status afterwards get it; tickets that already have the status's checklist keep theirs. A team's members change its statuses' templates; owners and admins change any, and the workspace's. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `doer` (string, one of: `human`, `clanker`): Who does the item, human or clanker; clanker when left out. ### Returns Returns an object with these fields. The status is 201. A ticket status with its checklist template and instructions. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order: the items a ticket's checklist starts with when the ticket first enters the status. Empty when the status has none. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `instructions` (object, required): What a status asks of a clanker: the document its tickets keep there, the Markdown that document starts from, and how to work the status. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/checklist \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Design review", "doer": "human" }' ``` ### Response ```json { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "instructions": { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end." } } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Update a checklist template item `PATCH /v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}` Renames an item of a status's checklist template, or changes who does it. Tickets that already have the status's checklist keep their copies. The people who add template items change them. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `item` (string, in path, required): The template item's ID, or its title. - `title` (string): The item's new title, up to 120 characters. - `doer` (string, one of: `human`, `clanker`): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. ### Returns Returns an object with these fields. The status is 200. A ticket status with its checklist template and instructions. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order: the items a ticket's checklist starts with when the ticket first enters the status. Empty when the status has none. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `instructions` (object, required): What a status asks of a clanker: the document its tickets keep there, the Markdown that document starts from, and how to work the status. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. ### Request ```bash curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item} \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Specs generated and passing" }' ``` ### Response ```json { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "instructions": { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end." } } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Delete a checklist template item `DELETE /v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}` Deletes an item from a status's checklist template. Tickets keep the copies they have. The people who add template items delete them. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `item` (string, in path, required): The template item's ID, or its title. ### Returns Returns no content. The status is 204. ### Request ```bash curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Reorder a checklist template item `POST /v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}/reorder` Moves a template item right before or after another. Send `before` or `after`, not both. The people who add template items reorder them. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `item` (string, in path, required): The template item's ID, or its title. - `before` (string): The ID or title of a template item to go right before. - `after` (string): The ID or title of a template item to go right after. ### Returns Returns an object with these fields. The status is 200. A ticket status with its checklist template and instructions. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order: the items a ticket's checklist starts with when the ticket first enters the status. Empty when the status has none. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `instructions` (object, required): What a status asks of a clanker: the document its tickets keep there, the Markdown that document starts from, and how to work the status. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}/reorder \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "after": "Ct3CkP2sLx6T" }' ``` ### Response ```json { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "instructions": { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end." } } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Get a status's instructions `GET /v1/workspaces/{slug}/ticket-statuses/{status}/instructions` Returns what the status asks of a clanker, with its checklist template: the document its tickets keep there, the Markdown that document starts from, and how to work the status. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. ### Returns Returns an object with these fields. The status is 200. A status's instructions and the checklist they go with. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. - `team` (nullable object, required): The team whose status this is, or null for the workspace's template. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `isStageDefault` (boolean, required): Whether the instructions are still Clanker Ship's for the status: its stage's, with the document named after the status when another status of its set keeps the stage's. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/instructions \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end.", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "status": { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false }, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "isStageDefault": false } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Set a status's instructions `PUT /v1/workspaces/{slug}/ticket-statuses/{status}/instructions` Changes a status's instructions. Fields left out keep their values. A team's members change its statuses' instructions; owners and admins change any, and the workspace's. Tickets that already wrote the status's document keep it. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. - `document` (nullable string): The name of the status's document, up to 40 characters, unique within the team. `null` or blank for no document. - `template` (string): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string): How a clanker works the status, in Markdown, up to 20,000 characters. ### Returns Returns an object with these fields. The status is 200. A status's instructions and the checklist they go with. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. - `team` (nullable object, required): The team whose status this is, or null for the workspace's template. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `isStageDefault` (boolean, required): Whether the instructions are still Clanker Ship's for the status: its stage's, with the document named after the status when another status of its set keeps the stage's. ### Request ```bash curl -X PUT https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/instructions \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end." }' ``` ### Response ```json { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end.", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "status": { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false }, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "isStageDefault": false } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Reset a status's instructions `DELETE /v1/workspaces/{slug}/ticket-statuses/{status}/instructions` Puts a status's instructions back to Clanker Ship's for its stage and returns them. The people who set a status's instructions can reset them. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `status` (string, in path, required): The ticket status's ID. ### Returns Returns an object with these fields. The status is 200. A status's instructions and the checklist they go with. - `document` (nullable string, required): The name of the document tickets keep in this status, such as Plan, unique within the team; null when the status keeps none. - `template` (string, required): The Markdown the status's document starts from, up to 20,000 characters. - `guidance` (string, required): How a clanker works the status, writes its document and moves on, in Markdown, up to 20,000 characters. - `team` (nullable object, required): The team whose status this is, or null for the workspace's template. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `checklist` (array of objects, required): The status's checklist template, in order. - `id` (string, required): Unique ID of the checklist template item. - `title` (string, required): What has to be done, up to 120 characters, unique within the template. - `position` (number, required): Orders the item within the template, from 0. - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval. - `isStageDefault` (boolean, required): Whether the instructions are still Clanker Ship's for the status: its stage's, with the document named after the status when another status of its set keeps the stage's. ### Request ```bash curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/ticket-statuses/{status}/instructions \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "document": "Build record", "template": "## Progress\nOne entry per plan step: what was done, the files and commits.", "guidance": "- Update the build record after every step. Never write it at the end.", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "status": { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false }, "checklist": [ { "id": "Ct1ImP4dNq8R", "title": "Cases written", "position": 0, "doer": "clanker" }, { "id": "Ct2SpG7nKw3V", "title": "Specs generated", "position": 1, "doer": "clanker" }, { "id": "Ct3CkP2sLx6T", "title": "Tests pass", "position": 2, "doer": "clanker" } ], "isStageDefault": false } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.