Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Ticket statuses

A ticket status is a step in a team's workflow, such as Todo or In Progress, in one of five fixed categories: backlog, unstarted, started, completed and canceled. Each team has its own statuses, copied from the workspace's template when the team is created. Owners and admins change them.

The TicketStatus object

A step in a team's workflow, such as Todo or In Progress.

Attributes

idstringRequired

Unique ID of the ticket status.

namestringRequired

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

categorystringRequired

The fixed group the status belongs to: backlog, unstarted, started, completed or canceled. It cannot change.

One ofbacklogunstartedstartedcompletedcanceled
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": "St3IpV6nHs9D",  "name": "In Progress",  "category": "started",  "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.

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 TicketStatus objectsRequired

The statuses 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.
GET/v1/workspaces/{slug}/ticket-statuses
curl https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "statuses": [    {      "id": "St3IpV6nHs9D",      "name": "In Progress",      "category": "started",      "position": 2,      "isDefault": false    }  ]}

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 ofbacklogunstartedstartedcompletedcanceled

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
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "team": "WEB",    "name": "In QA",    "category": "started"  }'
Response201
{  "id": "St3IpV6nHs9D",  "name": "In Progress",  "category": "started",  "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 or unstarted 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}
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "In development"  }'
Response200
{  "id": "St3IpV6nHs9D",  "name": "In Progress",  "category": "started",  "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.

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}
curl -X DELETE https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status} \  -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
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/ticket-statuses/{status}/reorder \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "after": "St4IrG2wZf5M"  }'
Response200
{  "statuses": [    {      "id": "St3IpV6nHs9D",      "name": "In Progress",      "category": "started",      "position": 2,      "isDefault": false    }  ]}
NextTags