---
title: "Reword the questions of a draft, or set its rescan cadence"
method: PATCH
path: "/competitor-scans/{id}"
tags: ["Competitor scans"]
---

# Reword the questions of a draft, or set its rescan cadence

`PATCH /competitor-scans/{id}`

## Request

- Base URL: `https://api.epovest.com/v1`
- URL: `https://api.epovest.com/v1/competitor-scans/{id}`
- Auth: HTTP bearer

`questions` is the list of the ones to KEEP with the text to ask, an omitted `text` keeping
the current one; a question of the scan left out of the list is removed, and
`estimated_cost_minor` follows it. `rescan_cadence` set to `weekly` or `monthly` runs the
scan again on that cadence, `null` stops it: it states a state, and replays safely both ways.

## Request body

- object
  - `questions` object[]
    - `id` string, uuid, required
    - `text` string
  - `rescan_cadence` 'weekly' | 'monthly', nullable

## Response `200`

The scan as it now stands.

- CompetitorScanEnvelope
  - `competitor_scan` CompetitorScan, required
    - `id` string, uuid, required
    - `project_id` string, uuid, required
    - `project` string, required
    - `title` string, required
    - `engine` 'chatgpt' | 'claude' | 'gemini' | 'perplexity' | 'mistral' | 'grok', required: The AI assistants the questions are asked to.
    - `language` string, required
    - `country` string, nullable, required
    - `category` string, nullable, required
    - `usage` string, nullable, required
    - `status` 'draft' | 'measuring' | 'ready' | 'failed', required
    - `rescan_cadence` 'weekly' | 'monthly' | 'null', nullable, required
    - `checks_completed` integer, required
    - `estimated_cost_minor` integer, required: What arming the scan spends, in minor units of the wallet currency.
    - `subjects` object[], required
      - `name` string
      - `website` string
      - `domain` string
    - `questions` object[], required
      - `id` string, uuid
      - `subject` string
      - `family` 'about' | 'compared'
      - `template` 'about_reputation' | 'about_price' | 'about_customers' | 'compared_alternatives': Which of the four questions each company gets.
      - `text` string
    - `created_at` string, date-time, required
    - `launched_at` string, date-time, nullable, required
    - `author` string, nullable, required

## Other responses

- `401`: `unauthenticated`: missing, unknown or revoked key.
- `403`: `insufficient_scope`: the credential may not do this, either because the key lacks the scope, or, on a one-click connection, because the person lacks the role the action needs (manager, or owner to start, pause and top up). On that path, read it as "this person may not do this" and tell them which role the action needs.
- `404`: `not_found`: unknown for this account.
- `409`: `already_launched` (a measured scan keeps its questions: prepare another one to ask something else) or `scan_not_armed` (arm the scan first, the cadence follows the first check).
- `422`: `invalid_questions`, `unknown_question`, `no_question` or `invalid_cadence`.
- `429`: `rate_limited`: 120 requests per minute per credential, sliding window. Retry after `Retry-After` seconds.

---

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