# Milestones

A milestone is a checkpoint within a project, numbered M1, M2 and so on. A ticket in the project can belong to one of its milestones. A project returns its milestones, so there is no separate list.

## The Milestone object

A checkpoint within a project, labeled M1, M2 and so on.

### Attributes

- `id` (string, required): Unique ID of the milestone.
- `number` (number, required): The milestone's number within its project: 2 is M2.
- `name` (string, required): The milestone's name.
- `summary` (nullable string, required): A short summary, or null.

### Example

```json
{
  "id": "Ms2SrC9vLm4D",
  "number": 2,
  "name": "Search",
  "summary": "Readers find any page from the docs header."
}
```

## Create a milestone

`POST /v1/workspaces/{slug}/projects/{project}/milestones`

Adds a milestone numbered one past the project's highest, such as M3 after M2. Viewers cannot add milestones, and an archived project takes none.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `project` (string, in path, required): The project's slug, such as docs-launch.
- `name` (string, required): The milestone's name, up to 100 characters.
- `summary` (nullable string): A short summary, up to 280 characters.

### Returns

Returns the [Milestone](https://docs.qa.clankership.net/api/milestones/object.md) object. The status is 201.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/projects/{project}/milestones \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search",
    "summary": "Readers find any page from the docs header."
  }'
```

### Response

```json
{
  "id": "Ms2SrC9vLm4D",
  "number": 2,
  "name": "Search",
  "summary": "Readers find any page from the docs header."
}
```

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

`PATCH /v1/workspaces/{slug}/projects/{project}/milestones/{milestone}`

Changes only the fields sent. Viewers cannot change milestones, and an archived project's milestones take no changes.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `project` (string, in path, required): The project's slug, such as docs-launch.
- `milestone` (string, in path, required): The milestone's label or number within the project, such as M2 or 2.
- `name` (string): The milestone's name, up to 100 characters.
- `summary` (nullable string): A short summary, up to 280 characters. `null` clears it.

### Returns

Returns the [Milestone](https://docs.qa.clankership.net/api/milestones/object.md) object. The status is 200.

### Request

```bash
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/{slug}/projects/{project}/milestones/{milestone} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search and filters"
  }'
```

### Response

```json
{
  "id": "Ms2SrC9vLm4D",
  "number": 2,
  "name": "Search",
  "summary": "Readers find any page from the docs header."
}
```

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

`DELETE /v1/workspaces/{slug}/projects/{project}/milestones/{milestone}`

Deletes the milestone and takes it off its tickets, which stay in the project. Viewers cannot delete milestones, and an archived project keeps its milestones.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `project` (string, in path, required): The project's slug, such as docs-launch.
- `milestone` (string, in path, required): The milestone's label or number within the project, such as M2 or 2.

### Returns

Returns no content. The status is 204.

### Request

```bash
curl -X DELETE https://api.qa.clankership.net/v1/workspaces/{slug}/projects/{project}/milestones/{milestone} \
  -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.