---
title: "Let the user pick a reference"
method: POST
path: "/api/v1/picks"
tags: ["picks"]
---

# Let the user pick a reference

`POST /api/v1/picks`

## Request

- Base URL: `https://screenrove.com`
- URL: `https://screenrove.com/api/v1/picks`
- Auth: none declared

Show the user several matching UI references side by side in their browser and let them click
the one to build from. Returns a URL to open for them.

Prefer this over sending full-page images whenever the user should decide which reference to
use. The picker shows real screenshots at scroll depth so they can evaluate long pages.

After calling this, tell them to choose in the picker, then call waitForPick with the pickId
to get their choice and a complete build prompt.

## Request body

- object
  - `q` string: Search words, e.g. "pricing page", "onboarding", "empty state". The best matches become the options.
  - `screens` string: Comma-separated screen ids to show instead of searching, e.g. from an earlier searchScreens.
  - `product` string: Only search this product id.
  - `kind` 'flow' | 'marketing' | 'product': Only search this kind of screen.
  - `count` integer: How many options to show when searching, 2 to 6.
  - `goal` string: What the user is building, shown on the page and used in the build prompt, e.g. "NSDR premium upgrade page".
  - `stack` string: Preferred stack for the build prompt.

## Response `201`

The pick page is ready.

- PickCreated
  - `pickId` string
  - `url` string: Open this for the user.
  - `canvasUrl` string: Experimental pan-and-zoom canvas view of the same pick.
  - `status` 'pending'
  - `options` ScreenSummary[]
    - `id` string
    - `product` string
    - `kind` 'flow' | 'marketing' | 'product': flow is an onboarding step, marketing a public web page, product an in-app screen.
    - `title` string
    - `notes` string
    - `imageUrl` string
    - `previewUrl` string: Screen-sized preview (the top of long pages). Present on pick options.
    - `productName` string: Present on pick options.
  - `next` string: What to do next.

## Other responses

- `400`: The request could not be used.
- `404`: No product, screen or reference with that id.

---

[API](https://skmtc.dev/screenrove/apis/screenrove-api.md) · [All operations](https://skmtc.dev/screenrove/apis/screenrove-api/llms.txt) · [OpenAPI document](https://skmtc.dev/screenrove/apis/screenrove-api/revisions/9383a872c966?raw)