> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Pins

> /v0/workspaces/:id/pins — Ordered markdown every load returns first

Pins are markdown artifacts in the workspace that [Load](/api-reference/workspaces/load) returns first, in order, as read-first context. A workspace holds at most 20. Managing pins requires `manageContext` (internal admins and editors). Visibility is resolved on load: an external member never learns that an internal pin exists. MCP: `workspace_pin` / `workspace_unpin`. CLI: `rip workspace pin add|remove`.

**Auth:** `Authorization: Bearer tr_...` (an account API key). `{id}` is the workspace UUID.

## `POST /v0/workspaces/{id}/pins`

| Field | Type | Required | Description |
| - | - | - | - |
| `artifactId` | string | Yes | Public id or alias of an active markdown artifact in this workspace |
| `position` | integer | No | Zero-based slot; clamped to the current range. Omit to append |

Returns (201):

```json theme={null}
{ "ok": true, "data": { "artifactId": "<public id>", "position": 0 } }
```

Pinning an artifact that is already pinned returns its current position and changes nothing.

## `DELETE /v0/workspaces/{id}/pins/{artifactId}`

`{artifactId}` is the public id or alias. Returns `204`, also when the artifact was not pinned. The artifact itself is untouched, and later pins move up one slot.

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_INPUT` | Missing `artifactId` |
| `400` | `INVALID_WORKSPACE_PIN` | The artifact is not active markdown in this workspace |
| `404` | `NOT_FOUND` | No artifact with that id or alias |
| `409` | `WORKSPACE_PIN_LIMIT` | The workspace already has 20 pins |
| `409` | `WORKSPACE_ARCHIVED` | The workspace is archived |
| `404` | `WORKSPACE_NOT_FOUND` | No workspace with that id |
| `403` | `WORKSPACE_FORBIDDEN` | You lack `manageContext` |