Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

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

idstringRequired

Unique ID of the pin.

kindstringRequired

What the pin points at: ticket, project, product, environment or team.

One ofticketprojectproductenvironmentteam
keystringRequired

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.

namestringRequired

The ticket's title, or the project's, product's, environment's or team's name.

The Pin object
{  "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.

Path parameters

slugstringRequired

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

Returns

Returns an object with these fields. Status 200.

The caller's pins in their order.

pinsarray of Pin objectsRequired

The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out.

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}/pins
curl https://api.qa.clankership.net/v1/workspaces/acme/pins \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "pins": [    {      "id": "Pn3HdT6wQa8K",      "kind": "project",      "key": "docs-launch",      "name": "Docs launch"    },    {      "id": "Pn5MvB2xRc7L",      "kind": "ticket",      "key": "WEB-31",      "name": "Add docs search"    }  ]}

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.

Path parameters

slugstringRequired

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

Body parameters

kindstringRequired

What the pin points at: ticket, project, product, environment or team.

One ofticketprojectproductenvironmentteam
keystringRequired

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

The caller's pins in their order.

pinsarray of Pin objectsRequired

The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out.

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}/pins
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/pins \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "kind": "ticket",    "key": "WEB-31"  }'
Response200
{  "pins": [    {      "id": "Pn3HdT6wQa8K",      "kind": "project",      "key": "docs-launch",      "name": "Docs launch"    },    {      "id": "Pn5MvB2xRc7L",      "kind": "ticket",      "key": "WEB-31",      "name": "Add docs search"    }  ]}

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.

Path parameters

slugstringRequired

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

kindstringRequired

What the pin points at: ticket, project, product, environment or team.

keystringRequired

The key of what the pin points at, such as WEB-31, WEB or docs-launch.

Returns

Returns an object with these fields. Status 200.

The caller's pins in their order.

pinsarray of Pin objectsRequired

The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out.

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}/pins/{kind}/{key}
curl -X DELETE https://api.qa.clankership.net/v1/workspaces/acme/pins/{kind}/{key} \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "pins": [    {      "id": "Pn3HdT6wQa8K",      "kind": "project",      "key": "docs-launch",      "name": "Docs launch"    },    {      "id": "Pn5MvB2xRc7L",      "kind": "ticket",      "key": "WEB-31",      "name": "Add docs search"    }  ]}

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.

Path parameters

slugstringRequired

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

kindstringRequired

What the pin points at: ticket, project, product, environment or team.

keystringRequired

The key of what the pin points at, such as WEB-31, WEB or docs-launch.

Body parameters

beforeobject

The pin to go right before.

afterobject

The pin to go right after.

Returns

Returns an object with these fields. Status 200.

The caller's pins in their order.

pinsarray of Pin objectsRequired

The caller's pins in their order. Pins of archived entities, and of ones the caller no longer sees, are left out.

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}/pins/{kind}/{key}/reorder
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/pins/{kind}/{key}/reorder \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "before": {      "kind": "project",      "key": "docs-launch"    }  }'
Response200
{  "pins": [    {      "id": "Pn3HdT6wQa8K",      "kind": "project",      "key": "docs-launch",      "name": "Docs launch"    },    {      "id": "Pn5MvB2xRc7L",      "kind": "ticket",      "key": "WEB-31",      "name": "Add docs search"    }  ]}
NextProducts