> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retriever.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Plays

> Create a play, change its target and limits, launch it, and keep or reject the leads it finds.

A play finds leads on a cadence: each run looks for accounts that show its `signal`, keeps the ones in its `segment`, finds the `whoToTarget` person there, and writes them a first message. The user keeps or rejects each lead; a kept lead enters the play's sequence. Plays belong to the organization of the user who created the key, whoever created the play. Each run spends the organization's credits.

| Endpoint | Body | Response |
| - | - | - |
| `POST /v1/plays` | `PlayDraft`: `name`, `signal`, `segment`, `whoToTarget`, optional `why`, `context`, `sequence`, `delivery`, `limits` | `201`, the draft, with `defaulted` |
| `GET /v1/plays` | | `items` |
| `GET /v1/plays/{id}` | | The play |
| `PATCH /v1/plays/{id}` | At least one of `name`, `changes`, `limits` | The play, with `changed` |
| `GET /v1/plays/{id}/versions` | | `items`: its versions, newest first |
| `POST /v1/plays/{id}/versions/{version}/restore` | None | The play, with `changed` |
| `POST /v1/plays/{id}/launch` | `timezone` | The play, `active` |
| `POST /v1/plays/{id}/pause` | None | The play, `paused` |
| `POST /v1/plays/{id}/resume` | None | The play, `active` |
| `POST /v1/plays/{id}/run` | None | The run, `queued` (`202`): a full run now, the cadence stays |
| `POST /v1/plays/{id}/archive` | None | The play, `archived` |
| `POST /v1/plays/{id}/restore` | None | The play, `paused` or `draft` |
| `GET /v1/plays/{id}/leads` | Query: `review_state`, `limit` (25 by default, 100 at most), `offset` | `items`, `total`, `next_offset` |
| `POST /v1/plays/{id}/leads/{leadId}/accept` | None | The lead, `accepted` |
| `POST /v1/plays/{id}/leads/{leadId}/reject` | `reasons`, optional `note` | The lead, `rejected` |
| `POST /v1/plays/{id}/leads/{leadId}/replace` | Optional `instruction` | The lead, set aside, with `replacement` |
| `POST /v1/plays/{id}/leads/{leadId}/message/rewrite` | Optional `instructions`, `overwrite_hand_edit` | The lead, with `voice_rule_added` |
| `PUT /v1/plays/{id}/leads/{leadId}/message` | `text`, optional `subject` | The lead |
| `POST /v1/plays/{id}/steps/rewrite` | `request` | The play |
| `POST /v1/plays/{id}/leads/move` | Optional `lead_ids` | The play |
| `GET /v1/plays/news` | Query: optional `play_id` | `items`: leads to review, proposals, finished runs |
| `POST /v1/plays/{id}/proposals/{proposalId}/apply` | None | The play, a new version |
| `POST /v1/plays/{id}/proposals/{proposalId}/dismiss` | None | `id`, `status` |
| `DELETE /v1/plays/{id}` | None | `id`, `deleted` |

## Create and change

A draft runs nothing and costs nothing. The fields left out take their default: review before sending, a run every day at 07:00, 10 qualified leads per run, the channel's usual steps. `defaulted` lists them.

`config` and `limits` in a play have the shape the bodies take, so a client can send back what it read. In `PATCH`, a block in `changes` replaces the play's: `sequence` and `context` whole, `delivery` field by field. A new `sequence.channel` without `steps` gets that channel's steps, written for the play from the organization's Brain; without a Brain the change answers `409 company_icp_brief_not_found`.

```bash theme={null}
curl -X PATCH "$RETRIEVER_API/v1/plays/$PLAY_ID" \
  -H "Authorization: Bearer $RETRIEVER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Series A, France", "changes": { "segment": "Fintech in France, 50 to 200 people." }, "limits": { "targetQualifiedLeadsPerRun": 5 } }'
```

Each change is a version. `GET /v1/plays/{id}/versions` lists them, newest first: who made it (`made_by`), when, and `changes`, each field before and after. `versions/{version}/restore` brings the play back to one of them: a new version with its content (its blocks and its limits; the play keeps its current name), checked as a `PATCH` is. The versions in between stay in the history.

## Launch and follow

`launch` starts the play's scheduled run with the delivery the play has. The first run comes at the next run time. `schedule_id` is then set. That scheduled run belongs to the member the play acts for, usually its creator: with that member's key, `GET /v1/scheduled-runs/{schedule_id}/runs` lists the runs and `POST /v1/scheduled-runs/{schedule_id}/run` starts one now; with another member's key they answer `404 scheduled_run_not_found`. `missing_accounts` names the channels no connected account can send from: kept leads wait there until an account is connected in the app.

`delivery.mode: auto` (autopilot) keeps every lead without review and sends its messages. Set it only when the user asks.

## Sort the leads

Read the leads waiting for review with `review_state=review`. A lead kept or rejected leaves that list: after deciding some, read again from `offset=0`. Keeping one puts it in the sequence, which sends its first message (`first_message`). Rejecting one needs `reasons`: the next runs learn from them, and the person and their company are excluded for the whole organization. A lead already decided answers `409 play_lead_decided`; one the sequence turns down answers `422 play_lead_not_enrolled` with the reason in `message`.

The right company with the wrong person: `replace` sets the lead aside (only the person is excluded) and starts a run of the play to find someone else there; it spends credits like any run, and needs a launched play that is not archived.

## Messages and proposals

`message/rewrite` has a model write the lead's first message again; `PUT message` saves it as written, with `subject` only when the sequence's first message is an email. Once the lead is in its sequence, a message that fits that step is the one it sends (one that does not fit stays on the lead only), and a message edited by hand there answers `409 play_message_edited_by_hand` unless `overwrite_hand_edit` is true. `steps/rewrite` rewrites the steps' writing instructions for every next message. `leads/move` moves leads in review found for an earlier channel to the play's channel, each with a new message. The models these calls use are debited at their cost.

After its runs and the user's verdicts, a play can propose a change to itself or to the Brain. `GET /v1/plays/news` lists the proposals with what else is new. `apply` makes a new version; a proposal made for blocks that changed since answers `409 play_update_stale`, and one with no change to the play's blocks `409 play_update_not_applicable`.

## Delete

`DELETE /v1/plays/{id}` stops the play's runs and deletes its sequences, so nothing more is sent. Its table stays in its workspace. To keep a play, archive it instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.