---
title: "Set the capture region"
method: POST
path: "/v1/vision/region"
tags: ["Capture"]
---

# Set the capture region

`POST /v1/vision/region`

## Request

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

Steers VisionPiper's one stored capture region (`vision_region_set`).
Supply exactly one of:

- a rect: all four of `x`, `y`, `width`, `height`, in `space`
  (`display` = points from the target display's top-left, the default;
  `global` = global points with the main display at the origin);
- a named target: `window_title` and/or `bundle_id` (a window),
  `selector` (an accessibility element, optionally scoped by
  `bundle_id`) or `description` (something to find on screen);
- `pick: true`, which opens VisionPiper's drag-to-select overlay and
  waits for the user.

An explicit rect outranks a named target and the overlay. VisionPiper
stays the region's owner: it trims an overhang, and the applied rect it
reports is what the response carries. Every refusal rides the
`precondition_failed` envelope with a typed `reason`:
`visionpiper_unavailable`, `screen_recording_denied`, `invalid_region`,
`unknown_display`, `selection_cancelled`, `selection_timed_out`, or a
named-target resolver reason such as `window_not_found`. Tolerate
unknown reasons.

## Request body

- object
  - `x` number, double
  - `y` number, double
  - `width` number, double: At least 1 point.
  - `height` number, double: At least 1 point.
  - `space` 'display' | 'global': Coordinate space of the rect. Defaults to `display`.
  - `display_id` integer: CGDirectDisplayID from `system_display_list`. With `space=display` it names the target display (default is VisionPiper's main display); with `space=global` it is the preferred display when the rect overlaps it.
  - `window_title` string: Title of a window to take the region from.
  - `bundle_id` string: Bundle id of the app whose window (or, with `selector`, whose element) supplies the region.
  - `selector` string: Accessibility selector of an element whose frame becomes the region.
  - `description` string: A description of something on screen to find and use as the region.
  - `pick` boolean: Open VisionPiper's drag-to-select overlay and wait for the user.

## Response `200`

Region applied (`status` is `region_set`)

- VisionRegionState: The capture region VisionPiper holds. `region` and `display_id` are absent when `status` is `no_region`; `indicator_visible` is absent when VisionPiper does not report it.
  - `status` 'ready' | 'no_region' | 'region_set', required
  - `generation` integer, required: Region generation; moves every time the region changes.
  - `recording` boolean, required: Whether a recording is running.
  - `selection_pending` boolean, required: Whether the drag-to-select overlay is waiting for the user.
  - `region` object: The applied rect, in points from the display's top-left.
    - `x` number, double, required
    - `y` number, double, required
    - `width` number, double, required
    - `height` number, double, required
  - `display_id` integer: CGDirectDisplayID the region sits on.
  - `indicator_visible` boolean: Whether the region's border indicator is showing.

## Other responses

- `412`: The region could not be set; branch on `error.reason`

---

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