---
title: "Read, write, or manage clipboard history"
method: POST
path: "/v1/clipboard"
tags: ["Utilities"]
---

# Read, write, or manage clipboard history

`POST /v1/clipboard`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/clipboard`
- Auth: HTTP bearer

Action dispatcher for ToolPiper's managed clipboard history. Supported actions:
`read` (most-recent item), `write` (text / image_base64 / file_paths),
`history` (paginated list), `get` (single item by id), `search` (full-text),
`restore` (re-copy item to NSPasteboard), `pin` / `unpin`, `delete`, `clear`.
The clipboard manager polls NSPasteboard every 250 ms and captures items
with OCR, source-app, and category metadata.

## Request body

- ClipboardRequest
  - `action` 'read' | 'write' | 'history' | 'get' | 'search' | 'restore' | 'pin' | 'unpin' | 'delete' | 'clear', required: * `read` — most-recent item. * `write` — set NSPasteboard from `text`, `image_base64`, or `file_paths`. * `history` — paginated history (`limit`, `content_type`, `include_thumbnails`, `include_ocr`). * `get` / `restore` / `pin` / `unpin` / `delete` — operate on `item_id`. * `search` — full-text query (`query`, `limit`, `content_type`, ...). * `clear` — wipe history.
  - `text` string: Text payload for `action=write`.
  - `image_base64` string: Base64-encoded image (PNG/TIFF) for `action=write`.
  - `file_paths` string[]: Absolute file paths to copy as a file reference for `action=write`.
  - `item_id` string: History item id for `action=get|restore|pin|unpin|delete`.
  - `limit` integer: Max items to return for `action=history|search`. Default 20.
  - `content_type` 'text' | 'image' | 'file': Filter by content type for `action=history|search`.
  - `include_thumbnails` boolean: Embed base64 thumbnails for image items. Default false.
  - `include_ocr` boolean: Include OCR text on image items. Default true.
  - `query` string: Search query for `action=search`.
  - `plain_text_only` boolean: Restore as plain text (drop rich formatting). Default false. `action=restore` only.

## Response `200`

Action-specific response (shape varies by action)

- object: Shape depends on `action`. See `ClipboardRequest` for per-action semantics.

## Other responses

- `400`: Invalid request
- `403`: Pasteboard access denied by macOS privacy controls
- `404`: Resource not found
- `503`: Clipboard manager unavailable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)