---
title: "Prepare a competitor scan, as a draft"
method: POST
path: "/competitor-scans"
tags: ["Competitor scans"]
---

# Prepare a competitor scan, as a draft

`POST /competitor-scans`

## Request

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

Prepares a scan on a basket of up to 5 companies of the same market, as a DRAFT: the answer
carries the questions it derived for you to read, and the amount it would cost as
`estimated_cost_minor`. Each subject needs a `website`, since a whole domain found in a page
is what tells two companies with the same name apart. Three companies or more and the places
rank by recurrence, by how many of the basket each one covers.

## Request body

- object
  - `project_id` string, uuid, required
  - `title` string: Omitted, it takes the category, or the name of the project.
  - `engine` 'chatgpt' | 'claude' | 'gemini' | 'perplexity' | 'mistral' | 'grok': The AI assistants the questions are asked to.
  - `language` string: The language the questions are asked in. Omitted, the canonical language of the project, or `en`.
  - `country` string, nullable
  - `category` string: What qualifies each company in the questions.
  - `usage` string: What buyers use it for. Omitted, the category.
  - `subjects` object[], required
    - `name` string, required
    - `website` string, required
  - `templates` CompetitorTemplate[]: Which of the four questions each company gets. Omitted, all four.

## Response `201`

The scan, in draft, with the questions it derived.

- 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.
- `422`: `invalid_project`, `invalid_engine`, `invalid_template` or `invalid_competitor_scan`.
- `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)