Context Pins

Pins are markdown artifacts in the workspace that 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):

{ "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`

Overview

Identity

Operators

Workspaces

Artifacts

Table Rows

Versions

Tasks

Activity

Search

Health

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

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

Errors

​POST /v0/workspaces/{id}/pins

​DELETE /v0/workspaces/{id}/pins/{artifactId}

​Errors

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

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

Errors