---
title: "Create a campaign"
method: POST
path: "/api/v1/campaigns"
tags: ["Campaigns"]
---

# Create a campaign

`POST /api/v1/campaigns`

## Request

- Base URL: `https://app.convertflow.co`
- URL: `https://app.convertflow.co/api/v1/campaigns`
- Auth: HTTP bearer

Creates a campaign. Without template_id: a blank campaign with a single "Champion" variant at 100% traffic, answered 201. With template_id (from GET /api/v1/templates): the campaign row is created right away (archived, `building: true`, no variants) and answered 202 while a job copies the template content and runs the AI remix when `remix.remix_all_text` asks for it; the campaign unarchives itself and `building` flips to false when the job finishes. A failed job leaves it archived with `building: false` and `build_failed: true`, and campaign mutations answer 422 while `building` is true. name and cta_type default to the template's. Popups, hooks, bars and embeds are not live on creation; a landing page is live once it exists and is not archived. page_path defaults to page-{id}. Requires campaigns:write.

## Request body

- object
  - `name` string: Required unless template_id is given
  - `cta_type` 'page' | 'overlay' | 'hook' | 'bar' | 'inline': Campaign format, required unless template_id is given
  - `test_type` string
  - `page_path` string: Landing page path (unique per website and domain)
  - `domain_id` integer
  - `template_id` integer: Template to build from (GET /api/v1/templates); answers 202
  - `remix` object
    - `remix_instructions` string
    - `remix_tone` string
    - `remix_all_text` string
    - `remix_asset_urls` string[]
    - `excluded_element_types` string[]

## Response `201`

campaign created

- object
  - `id` integer
  - `name` string
  - `cta_type` string: Campaign format
  - `format_type` string, nullable: Campaign sub-format. Null for page and bar campaigns, which have none.
  - `archived` boolean
  - `live` boolean: Whether visitors can reach the campaign: the live toggle for popups, hooks, bars and embeds; not archived for landing pages.
  - `building` boolean
  - `build_failed` boolean
  - `test_type` string
  - `page_path` string
  - `domain_id` unknown
  - `meta_title` unknown
  - `meta_description` unknown
  - `open_graph_title` unknown
  - `open_graph_description` unknown
  - `open_graph_image` unknown
  - `seo_index` unknown
  - `experiment_start_date` unknown
  - `experiment_end_date` unknown
  - `experiment_metric` unknown
  - `remix` object
    - `remix_tone` string
    - `remix_instructions` string
  - `published_at` unknown
  - `variants` object[]
    - `id` integer
    - `name` string
    - `variation` string
    - `percentage` integer, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `202`: campaign created from a template, content being copied
- `403`: AI remix not available on this plan
- `404`: template not visible to this account
- `409`: page path already used on this website
- `422`: invalid campaign format

---

[API](https://skmtc.dev/convertflow/apis/convertflow-api.md) - [All operations](https://skmtc.dev/convertflow/apis/convertflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/convertflow/apis/convertflow-api/revisions/9a45e0736b68?raw)