---
title: "Take a screenshot"
method: POST
path: "/v1/screenshot"
tags: ["Capture"]
---

# Take a screenshot

`POST /v1/screenshot`

## Request

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

Captures the screen as a still PNG. Supports `full` (primary display), `display` (a specific monitor), and `region` (an exact rect, in either coordinate space — see `space`). **Always writes the PNG to disk and returns metadata only**; inline base64 is never returned, so `save_path` chooses *where* the file lands rather than whether one is written, and an omitted `save_path` is auto-generated under `~/Library/Application Support/ToolPiper/screenshots/`. Modes `window`, `element`, and `find` are reserved and currently return 501.

## Request body

- ScreenshotRequest
  - `mode` 'full' | 'display' | 'region' | 'window' | 'element' | 'find': Capture mode. Defaults to `full`. `window`/`element`/`find` are reserved (501).
  - `display_id` integer: CGDirectDisplayID. Required for `mode=display`; optional for `mode=region` (defaults to primary, and with `space=global` it is only a preference — the region resolves its own display).
  - `space` 'display' | 'global': Coordinate space of the region rect (mode=region). `display` (the default) is device pixels measured from the target display's top-left. `global` is points in the space AX frames, `system_window_list` bounds, `CGDisplayBounds` and CGEvent mouse locations all report, with the main display at the origin — so `x`/`y` are negative for a display to its left or above, and the display is resolved from the rect by greatest overlap.
  - `x` integer: Region left — device pixels from the display's top-left when `space=display`, global points when `space=global` (may be negative) (mode=region)
  - `y` integer: Region top — device pixels when `space=display`, global points when `space=global` (may be negative) (mode=region)
  - `width` integer: Region width — device pixels when `space=display`, points when `space=global` (mode=region)
  - `height` integer: Region height — device pixels when `space=display`, points when `space=global` (mode=region)
  - `save_path` string: Optional absolute file path for PNG output, under the current user's home. If omitted, the tool auto-generates a path under `~/Library/Application Support/ToolPiper/screenshots/` and returns it. Inline base64 is never returned.
  - `show_cursor` boolean: Include the mouse cursor in the capture. Default false.

## Response `200`

Captured screenshot (inline base64 or written to disk)

- ScreenshotResponse
  - `mode` string, required
  - `path` string, required: Absolute path the PNG was written to (caller-supplied `save_path` or an auto-generated path under `~/Library/Application Support/ToolPiper/screenshots/`)
  - `bytes` integer, required
  - `width` integer, required
  - `height` integer, required
  - `display_id` integer, required

## Other responses

- `400`: Invalid request
- `403`: Screen recording permission denied or save_path not writable
- `404`: Display not found
- `501`: Mode not implemented
- `503`: No display available

---

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