---
title: "Arm a competitor scan"
method: POST
path: "/competitor-scans/{id}/start"
tags: ["Competitor scans"]
---

# Arm a competitor scan

`POST /competitor-scans/{id}/start`

## Request

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

The engine is asked and the balance is debited by `estimated_cost_minor`, so name the amount
to the person first. Replaying it answers with the scan already armed.

## Response `200`

The scan, armed.

- 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.
- `402`: `insufficient_credits`: the prepaid balance does not cover this scan. Top up, then arm it again.
- `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`: `no_question`, `no_engine_available` or `already_starting`. Nothing was charged.
- `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)