---
title: "Pick a color from the screen"
method: POST
path: "/v1/color/pick"
tags: ["Capture"]
---

# Pick a color from the screen

`POST /v1/color/pick`

## Request

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

Eyedropper color picker — opens the native macOS magnifier loupe and waits for the user to click a pixel, then returns the sampled color. User cancellation (Escape) returns `{cancelled: true}` rather than an error. Requires user interaction; not scriptable at coordinates.

## Request body

- object
  - `format` 'hex' | 'rgb' | 'hsl' | 'hsv' | 'all': Output format. Default `all`.

## Response `200`

Sampled color (or cancelled)

- ColorPickResponse
  - `cancelled` boolean, required: True when the user pressed Escape without clicking a pixel
  - `hex` string: Hex color, e.g. `#4ADE80` (omitted when cancelled)
  - `rgb` object
    - `r` integer
    - `g` integer
    - `b` integer
    - `a` number
  - `hsl` object
    - `h` number
    - `s` number
    - `l` number
  - `hsv` object
    - `h` number
    - `s` number
    - `v` number

## Other responses

- `400`: Invalid request

---

[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)