---
title: "Re-resolve a switch advisory under a hand-supplied policy (A/B taste; not persisted)"
method: POST
path: "/v1/projects/{id}/selector/preview"
tags: ["selector"]
---

# Re-resolve a switch advisory under a hand-supplied policy (A/B taste; not persisted)

`POST /v1/projects/{id}/selector/preview`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/projects/{id}/selector/preview`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `media:read`)
  - API key in header `PAYMENT-SIGNATURE`

Required permission: media:read

## Path parameters

- `id` string, required

## Request body

- SelectorPreviewRequest
  - `groupId` string, required
  - `weights` object: Sparse prominence weights (the taste knob, non-negative). Default = DOMINANCE_WEIGHTS.
  - `minHoldSec` number
  - `enterSec` number
  - `switchMargin` number
  - `cooldownSec` number
  - `maxHoldSec` number
  - `lockSourceId` string: Pin a camera/angle for the whole timeline.
  - `overrides` object[]
    - `startSec` number, required
    - `endSec` number, required
    - `candidateId` string, required

## Response `200`

The re-resolved advisory under the supplied policy.

- SelectorCandidatesResponse: Selector (switch) candidates + recommendation for a synced-angle group. Every candidate carries score + contributions + reasons so the agent reweights from evidence; the recommendation is the lowered cut schedule + best-audio bed.
  - `projectId` string, required
  - `groupId` string, required
  - `selectorVersion` string, required
  - `signalVersions` object, required
  - `moments` SelectorMomentGroup[], required
    - `startSec` number, required: Span start (output seconds).
    - `endSec` number, required: Span end (output seconds).
    - `chosen` string, required: The recommended candidateId, or "__hold__" (abstain).
    - `pacingNote` string, nullable: Which mechanism produced the pick (argmax / hysteresis / override / hold …).
    - `candidates` SelectorScoredCandidate[], required
      - `candidateId` string, required: Stable angle/source id. An unknown id is rejected, never remapped.
      - `role` string, nullable: Agent-declared semantic tag (e.g. "wide", "webcam").
      - `score` number, required: The weighted prominence score (Σ weights·signal).
      - `contributions` object, required: signalKey → weighted contribution (the agent reweights from this).
      - `reasons` string[], required
  - `recommendation` object, required
    - `cutSchedule` SelectorCutSpan[], required
      - `startSec` number, required
      - `endSec` number, required
      - `candidateId` string, required
      - `sourceInSec` number, required: Chosen source window start (declared-offset resolved).
      - `sourceOutSec` number, required
      - `reasons` string[], required
    - `audioBed` SelectorAudioSpan[], required: Best-audio bed (instance #3): the clearest mic per span.
      - `startSec` number, required
      - `endSec` number, required
      - `candidateId` string, required: The chosen audio source (the clearest mic) for this span → programAudioSourceId.
      - `reasons` string[], required
    - `suppressedSwitches` object[], required: Switches the stabilizer suppressed (the anti-ping-pong audit).
      - `atSec` number, required
      - `wouldHaveBeenCandidateId` string, required
      - `byScore` number, required
      - `blockedBy` string, required
      - `releaseAtSec` number, nullable, required
  - `divergesFromComposition` boolean

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.

---

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