# Campaigns

> Create, list, retrieve, and edit creator- or agency-owned campaigns through Public API V1.
>
> Canonical URL: https://docs.creatorsjet.com/api/campaigns

Creator and agency keys can manage campaigns owned directly by their authenticated subject.

| Operation                  | Scope             |
| -------------------------- | ----------------- |
| List or retrieve campaigns | `campaigns:read`  |
| Create or update campaigns | `campaigns:write` |

## Create a campaign

`POST /campaigns` requires an `Idempotency-Key`. Only `name` is required. If `refresh_cadence` is omitted, the campaign uses `on_request` tracking.

```bash
curl https://api.creatorsjet.com/public/v1/campaigns \
  --request POST \
  --header "Authorization: Bearer $CREATORSJET_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "name": "Summer launch",
    "description": "Track creator content for the summer launch.",
    "refresh_cadence": "on_request",
    "cpm": {
      "instagram": 14,
      "tiktok": 11
    }
  }'
```

Automatic tracking supports `daily` and `every_2_days`. Both require `ends_at` to be a future ISO 8601 timestamp. Use `on_request` when the integration should create the campaign without scheduling automatic collection.

Campaign creation uses the account's existing active-campaign allowance. When the allowance is exhausted, the API returns `403 LIMIT_EXCEEDED`.

## List and retrieve campaigns

List campaigns with opaque cursor pagination. The optional `status` filter accepts `active`, `completed`, or `archived`.

```bash
curl "https://api.creatorsjet.com/public/v1/campaigns?status=active&limit=25" \
  --header "Authorization: Bearer $CREATORSJET_API_KEY"
```

The list response includes summary values when they are available. Retrieve one campaign by its returned `id`:

```bash
curl "https://api.creatorsjet.com/public/v1/campaigns/$CAMPAIGN_ID" \
  --header "Authorization: Bearer $CREATORSJET_API_KEY"
```

## Update supported settings

`PATCH /campaigns/{campaign_id}` updates only supplied fields and requires an idempotency key.

```bash
curl "https://api.creatorsjet.com/public/v1/campaigns/$CAMPAIGN_ID" \
  --request PATCH \
  --header "Authorization: Bearer $CREATORSJET_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "description": "Updated launch reporting scope.",
    "cpm": {
      "instagram": 16
    },
    "emv_override": 2500
  }'
```

Supported fields are:

* `name`
* `description`
* `starts_at`
* `ends_at`
* `refresh_cadence`
* `refresh_state`, limited to `active` or `paused`
* `cpm` values for Instagram, TikTok, YouTube, or Twitter
* `emv_override`

Partial `cpm` updates preserve platform values that are not supplied. Set `emv_override` to `null` to remove the override.

An `on_request` campaign remains paused even if an update asks for an active refresh state. Automatic cadence is required for an active schedule.

## Public-report state

Campaign responses include public-report state and an editor URL. `public_report.share_url` is `null` while the report is disabled.

Public API V1 does not enable reports or change their slug, password, visible metrics, sections, or branding. Configure those settings in CreatorsJet.

## Not included

Public API V1 does not manage campaign participants, tracked content, short links, metric overrides, refresh execution, completion, reopening, archiving, report publication, passwords, or deletion.

Use the [endpoint reference](/api/reference/campaigns/listCampaigns) for exact request and response schemas.