Capture

Take a screenshot

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.

post/v1/screenshot

Request

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

Request body

mode'full' | 'display' | 'region' | 'window' | 'element' | 'find'

Capture mode. Defaults to full. window/element/find are reserved (501).

display_idinteger

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.

xinteger

Region left — device pixels from the display's top-left when space=display, global points when space=global (may be negative) (mode=region)

yinteger

Region top — device pixels when space=display, global points when space=global (may be negative) (mode=region)

widthinteger

Region width — device pixels when space=display, points when space=global (mode=region)

heightinteger

Region height — device pixels when space=display, points when space=global (mode=region)

save_pathstring

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_cursorboolean

Include the mouse cursor in the capture. Default false.

Response

Captured screenshot (inline base64 or written to disk)

modestring required
pathstring required

Absolute path the PNG was written to (caller-supplied save_path or an auto-generated path under ~/Library/Application Support/ToolPiper/screenshots/)

bytesinteger required
widthinteger required
heightinteger required
display_idinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.