# Pins

A pin is a person's own shortcut to a ticket, project, product, environment or team, listed in the website's sidebar under Pinned in their order. Each person sees only their own pins, and an agent changes the pins of the person it works for.

## The Pin object

One of the caller's pins: a shortcut to a ticket, project, product, environment or team, listed in the website's sidebar under Pinned.

### Attributes

- `id` (string, required): Unique ID of the pin.
- `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
- `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.
- `name` (string, required): The ticket's title, or the project's, product's, environment's or team's name.

### Example

```json
{
  "id": "Pn5MvB2xRc7L",
  "kind": "ticket",
  "key": "WEB-31",
  "name": "Add docs search"
}
```

## List your pins

`GET /v1/workspaces/{slug}/pins`

Returns the caller's pins in the workspace, in their order. Pins belong to a person, so a workspace API key gets Forbidden; use a personal API key.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.

### Returns

Returns an object with these fields. The status is 200. The caller's pins in their order.

- `pins` (array of objects, required): The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out. See [the Pin object](https://docs.qa.clankership.net/api/pins/object.md).
  - `id` (string, required): Unique ID of the pin.
  - `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
  - `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.
  - `name` (string, required): The ticket's title, or the project's, product's, environment's or team's name.

### Request

```bash
curl https://api.qa.clankership.net/v1/workspaces/{slug}/pins \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "pins": [
    {
      "id": "Pn3HdT6wQa8K",
      "kind": "project",
      "key": "docs-launch",
      "name": "Docs launch"
    },
    {
      "id": "Pn5MvB2xRc7L",
      "kind": "ticket",
      "key": "WEB-31",
      "name": "Add docs search"
    }
  ]
}
```

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

## Pin something

`POST /v1/workspaces/{slug}/pins`

Pins a ticket, project, product, environment or team the caller can open, after their other pins, and returns their pins. Pinning something already pinned changes nothing. An archived entity gets Conflict. The caller's open website tabs show the pin at once. Pins belong to a person, so a workspace API key gets Forbidden; use a personal API key.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
- `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.

### Returns

Returns an object with these fields. The status is 200. The caller's pins in their order.

- `pins` (array of objects, required): The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out. See [the Pin object](https://docs.qa.clankership.net/api/pins/object.md).
  - `id` (string, required): Unique ID of the pin.
  - `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
  - `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.
  - `name` (string, required): The ticket's title, or the project's, product's, environment's or team's name.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/pins \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "ticket",
    "key": "WEB-31"
  }'
```

### Response

```json
{
  "pins": [
    {
      "id": "Pn3HdT6wQa8K",
      "kind": "project",
      "key": "docs-launch",
      "name": "Docs launch"
    },
    {
      "id": "Pn5MvB2xRc7L",
      "kind": "ticket",
      "key": "WEB-31",
      "name": "Add docs search"
    }
  ]
}
```

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

## Unpin something

`DELETE /v1/workspaces/{slug}/pins/{kind}/{key}`

Removes one of the caller's pins and returns the rest. Something that is not pinned gets NotFound. Pins belong to a person, so a workspace API key gets Forbidden; use a personal API key.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `kind` (string, in path, required): What the pin points at: ticket, project, product, environment or team.
- `key` (string, in path, required): The key of what the pin points at, such as WEB-31, WEB or docs-launch.

### Returns

Returns an object with these fields. The status is 200. The caller's pins in their order.

- `pins` (array of objects, required): The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out. See [the Pin object](https://docs.qa.clankership.net/api/pins/object.md).
  - `id` (string, required): Unique ID of the pin.
  - `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
  - `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.
  - `name` (string, required): The ticket's title, or the project's, product's, environment's or team's name.

### Request

```bash
curl -X DELETE https://api.qa.clankership.net/v1/workspaces/{slug}/pins/{kind}/{key} \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "pins": [
    {
      "id": "Pn3HdT6wQa8K",
      "kind": "project",
      "key": "docs-launch",
      "name": "Docs launch"
    },
    {
      "id": "Pn5MvB2xRc7L",
      "kind": "ticket",
      "key": "WEB-31",
      "name": "Add docs search"
    }
  ]
}
```

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

`POST /v1/workspaces/{slug}/pins/{kind}/{key}/reorder`

Moves one of the caller's pins right before or right after another and returns them in the new order. Send `before` or `after`, not both. Pins belong to a person, so a workspace API key gets Forbidden; use a personal API key.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `kind` (string, in path, required): What the pin points at: ticket, project, product, environment or team.
- `key` (string, in path, required): The key of what the pin points at, such as WEB-31, WEB or docs-launch.
- `before` (object): The pin to go right before.
  - `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
  - `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.
- `after` (object): The pin to go right after.
  - `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
  - `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.

### Returns

Returns an object with these fields. The status is 200. The caller's pins in their order.

- `pins` (array of objects, required): The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out. See [the Pin object](https://docs.qa.clankership.net/api/pins/object.md).
  - `id` (string, required): Unique ID of the pin.
  - `kind` (string, one of: `ticket`, `project`, `product`, `environment`, `team`, required): What the pin points at: ticket, project, product, environment or team.
  - `key` (string, required): The key its pages use: a ticket's ID such as WEB-31 (a former ID also works), a team's key such as WEB, or a project's, product's or environment's slug such as docs-launch.
  - `name` (string, required): The ticket's title, or the project's, product's, environment's or team's name.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/pins/{kind}/{key}/reorder \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "before": {
      "kind": "project",
      "key": "docs-launch"
    }
  }'
```

### Response

```json
{
  "pins": [
    {
      "id": "Pn3HdT6wQa8K",
      "kind": "project",
      "key": "docs-launch",
      "name": "Docs launch"
    },
    {
      "id": "Pn5MvB2xRc7L",
      "kind": "ticket",
      "key": "WEB-31",
      "name": "Add docs search"
    }
  ]
}
```

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