Ticket statuses

A ticket status is a step in a team's workflow, such as In Planning or In Build, in one of six fixed categories, the stages every ticket moves through: backlog, planning, build, review, shipped and canceled. Each team has its own statuses, copied from the workspace's template when the team is created. A status can hold a checklist template, which a ticket copies into its own checklist when it first enters the status. Owners and admins change statuses and their templates.

The TicketStatus object

A step in a team's workflow, such as In Planning or In Build.

Attributes

idstringRequired

Unique ID of the ticket status.

namestringRequired

The status's name, unique within its team, such as In Build.

categorystringRequired

The fixed stage the status belongs to: backlog, planning, build, review, shipped or canceled. It cannot change.

One ofbacklogplanningbuildreviewshippedcanceled

positionnumberRequired

Orders the status within its category; lower comes first.

isDefaultbooleanRequired

Whether new tickets get this status when none is named.

The TicketStatus object

{  "id": "St3BdV6nHs9D",  "name": "In 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.

Path parameters

slugstringRequired

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

Query parameters

teamstring

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

Returns

Returns an object with these fields. Status 200.

statusesarray of objectsRequired

The statuses in board order: by category, then by position, each with its checklist template.

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}/ticket-statuses

1curl https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "statuses": [    {      "id": "St3BdV6nHs9D",      "name": "In Build",      "category": "build",      "position": 2,      "isDefault": false,      "checklist": [        {          "id": "Ct1ImP4dNq8R",          "title": "Implementation done",          "position": 0        },        {          "id": "Ct2SpG7nKw3V",          "title": "Specs generated",          "position": 1        },        {          "id": "Ct3CkP2sLx6T",          "title": "Checks pass",          "position": 2        }      ]    }  ]}

Create a ticket status

POST/v1/workspaces/{slug}/ticket-statuses

Owners and admins add statuses. The new status goes last in its category. A status added to the template reaches only teams created afterwards.

Path parameters

slugstringRequired

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

Body parameters

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

namestringRequired

The status's name, up to 40 characters, unique within the team.

categorystringRequired

The status's category. It cannot change later.

One ofbacklogplanningbuildreviewshippedcanceled

Returns

Returns the TicketStatus 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}/ticket-statuses

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "team": "WEB",6    "name": "In QA",7    "category": "review"8  }'

Response201

{  "id": "St3BdV6nHs9D",  "name": "In Build",  "category": "build",  "position": 2,  "isDefault": false}

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.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

Body parameters

namestring

The status's name, up to 40 characters, unique within the team.

isDefaultboolean

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 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}/ticket-statuses/{status}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "In development"6  }'

Response200

{  "id": "St3BdV6nHs9D",  "name": "In Build",  "category": "build",  "position": 2,  "isDefault": false}

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.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

Query parameters

moveTostring

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. Status 204.

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}/ticket-statuses/{status}

1curl -X DELETE https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status} \2  -H "Authorization: Bearer $CLANKER_API_KEY"

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.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

Body parameters

beforestring

The ID of a status of the same category to go right before.

afterstring

The ID of a status of the same category to go right after.

Returns

Returns an object with these fields. Status 200.

statusesarray of TicketStatus objectsRequired

Every status of the same team, or of the template, in board order: by category, then by position.

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}/ticket-statuses/{status}/reorder

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status}/reorder \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "after": "St4IrG2wZf5M"6  }'

Response200

{  "statuses": [    {      "id": "St3BdV6nHs9D",      "name": "In Build",      "category": "build",      "position": 2,      "isDefault": false    }  ]}

Add a checklist template item

POST/v1/workspaces/{slug}/ticket-statuses/{status}/checklist

Owners and admins add 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.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

Body parameters

titlestringRequired

What has to be done, up to 120 characters, unique within the template.

Returns

Returns an object with these fields. Status 201.

A ticket status with its checklist template.

idstringRequired

Unique ID of the ticket status.

namestringRequired

The status's name, unique within its team, such as In Build.

categorystringRequired

The fixed stage the status belongs to: backlog, planning, build, review, shipped or canceled. It cannot change.

One ofbacklogplanningbuildreviewshippedcanceled

positionnumberRequired

Orders the status within its category; lower comes first.

isDefaultbooleanRequired

Whether new tickets get this status when none is named.

checklistarray of objectsRequired

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.

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}/ticket-statuses/{status}/checklist

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status}/checklist \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "title": "Docs updated"6  }'

Response201

{  "id": "St3BdV6nHs9D",  "name": "In Build",  "category": "build",  "position": 2,  "isDefault": false,  "checklist": [    {      "id": "Ct1ImP4dNq8R",      "title": "Implementation done",      "position": 0    },    {      "id": "Ct2SpG7nKw3V",      "title": "Specs generated",      "position": 1    },    {      "id": "Ct3CkP2sLx6T",      "title": "Checks pass",      "position": 2    }  ]}

Rename a checklist template item

PATCH/v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}

Owners and admins rename an item of a status's checklist template.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

itemstringRequired

The template item's ID, or its title.

Body parameters

titlestringRequired

The item's new title, up to 120 characters.

Returns

Returns an object with these fields. Status 200.

A ticket status with its checklist template.

idstringRequired

Unique ID of the ticket status.

namestringRequired

The status's name, unique within its team, such as In Build.

categorystringRequired

The fixed stage the status belongs to: backlog, planning, build, review, shipped or canceled. It cannot change.

One ofbacklogplanningbuildreviewshippedcanceled

positionnumberRequired

Orders the status within its category; lower comes first.

isDefaultbooleanRequired

Whether new tickets get this status when none is named.

checklistarray of objectsRequired

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.

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}/ticket-statuses/{status}/checklist/{item}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status}/checklist/{item} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "title": "Specs generated and passing"6  }'

Response200

{  "id": "St3BdV6nHs9D",  "name": "In Build",  "category": "build",  "position": 2,  "isDefault": false,  "checklist": [    {      "id": "Ct1ImP4dNq8R",      "title": "Implementation done",      "position": 0    },    {      "id": "Ct2SpG7nKw3V",      "title": "Specs generated",      "position": 1    },    {      "id": "Ct3CkP2sLx6T",      "title": "Checks pass",      "position": 2    }  ]}

Delete a checklist template item

DELETE/v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}

Owners and admins delete an item from a status's checklist template. Tickets keep the copies they have.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

itemstringRequired

The template item's ID, or its title.

Returns

Returns no content. Status 204.

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}/ticket-statuses/{status}/checklist/{item}

1curl -X DELETE https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status}/checklist/{item} \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Reorder a checklist template item

POST/v1/workspaces/{slug}/ticket-statuses/{status}/checklist/{item}/reorder

Owners and admins move a template item right before or after another. Send before or after, not both.

Path parameters

slugstringRequired

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

statusstringRequired

The ticket status's ID.

itemstringRequired

The template item's ID, or its title.

Body parameters

beforestring

The ID or title of a template item to go right before.

afterstring

The ID or title of a template item to go right after.

Returns

Returns an object with these fields. Status 200.

A ticket status with its checklist template.

idstringRequired

Unique ID of the ticket status.

namestringRequired

The status's name, unique within its team, such as In Build.

categorystringRequired

The fixed stage the status belongs to: backlog, planning, build, review, shipped or canceled. It cannot change.

One ofbacklogplanningbuildreviewshippedcanceled

positionnumberRequired

Orders the status within its category; lower comes first.

isDefaultbooleanRequired

Whether new tickets get this status when none is named.

checklistarray of objectsRequired

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.

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}/ticket-statuses/{status}/checklist/{item}/reorder

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status}/checklist/{item}/reorder \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "after": "Ct3CkP2sLx6T"6  }'

Response200

{  "id": "St3BdV6nHs9D",  "name": "In Build",  "category": "build",  "position": 2,  "isDefault": false,  "checklist": [    {      "id": "Ct1ImP4dNq8R",      "title": "Implementation done",      "position": 0    },    {      "id": "Ct2SpG7nKw3V",      "title": "Specs generated",      "position": 1    },    {      "id": "Ct3CkP2sLx6T",      "title": "Checks pass",      "position": 2    }  ]}

NextTags