# 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

- `id` (string, required): Unique ID of the ticket status.
- `name` (string, required): The status's name, unique within its team, such as In Progress.
- `category` (string, one of: `backlog`, `unstarted`, `started`, `completed`, `canceled`, required): The fixed group the status belongs to: backlog, unstarted, started, completed 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": "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.

### 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. See [the TicketStatus object](https://docs.qa.clankership.net/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 In Progress.
  - `category` (string, one of: `backlog`, `unstarted`, `started`, `completed`, `canceled`, required): The fixed group the status belongs to: backlog, unstarted, started, completed 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 https://api.qa.clankership.net/v1/workspaces/{slug}/ticket-statuses \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "statuses": [
    {
      "id": "St3IpV6nHs9D",
      "name": "In Progress",
      "category": "started",
      "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.

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

### 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`, `unstarted`, `started`, `completed`, `canceled`, required): The status's category. It cannot change later.

### Returns

Returns the [TicketStatus](https://docs.qa.clankership.net/api/ticket-statuses/object.md) object. The status is 201.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/ticket-statuses \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "WEB",
    "name": "In QA",
    "category": "started"
  }'
```

### Response

```json
{
  "id": "St3IpV6nHs9D",
  "name": "In Progress",
  "category": "started",
  "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 or unstarted status can be the default. Always `true`.

### Returns

Returns the [TicketStatus](https://docs.qa.clankership.net/api/ticket-statuses/object.md) object. The status is 200.

### Request

```bash
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/{slug}/ticket-statuses/{status} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "In development"
  }'
```

### Response

```json
{
  "id": "St3IpV6nHs9D",
  "name": "In Progress",
  "category": "started",
  "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`.

### 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.qa.clankership.net/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.qa.clankership.net/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 In Progress.
  - `category` (string, one of: `backlog`, `unstarted`, `started`, `completed`, `canceled`, required): The fixed group the status belongs to: backlog, unstarted, started, completed 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.qa.clankership.net/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": "St3IpV6nHs9D",
      "name": "In Progress",
      "category": "started",
      "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.