# Campaigns (/api/campaigns)

All endpoints require `Authorization: Bearer ck_...`.

## List campaigns [#list-campaigns]

`GET /v1/campaigns`

**Scope:** `campaigns:list`

### Query parameters [#query-parameters]

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | `1` | Page number (min 1) |
| `limit` | integer | `10` | One of `1`, `5`, `10`, `25`, `50`, `100` |
| `active` | boolean | — | Filter by active status |
| `name` | string | — | Max 255 chars |
| `network` | string | — | `facebook`, `google`, `tiktok`, `kwai`, `taboola`, `pinterest`, `yandex`, `mgid`, `outbrain`, `sms`, `revcontent`, `adskeeper`, `newsbreak` |

### Response `200` [#response-200]

```json
{
  "count": 0,
  "data": []
}
```

Each item in `data` is a [CampaignShort](/reference/schemas#campaignshort). The `in_review` field mirrors `filters.deny_always`.

### Example [#example]

```bash
curl -H "Authorization: Bearer ck_YOUR_KEY" \
  "https://api.cloakup.me/v1/campaigns?page=1&limit=10"
```

---

## Create campaign [#create-campaign]

`POST /v1/campaigns`

**Scope:** `campaigns:create`

### Request body [#request-body]

[CampaignBody](/reference/schemas#campaignbody). See [Campaign create](/guides/campaign-create) for defaults and minimal example.

### Response `201` [#response-201]

[CampaignFull](/reference/schemas#campaignfull)

---

## Get campaign [#get-campaign]

`GET /v1/campaigns/:id`

**Scope:** `campaigns:show`

### Path parameters [#path-parameters]

| Name | Type | Description |
|------|------|-------------|
| `id` | integer | Campaign ID |

### Response `200` [#response-200-1]

[CampaignFull](/reference/schemas#campaignfull) — includes `is_test_mode` (true if caller IP is in `filters.whitelist`).

---

## Update campaign [#update-campaign]

`PUT /v1/campaigns/:id`

**Scope:** `campaigns:update`

Full replace — same schema as create. **Not** a partial PATCH.

### Request body [#request-body-1]

[CampaignBody](/reference/schemas#campaignbody)

### Response `200` [#response-200-2]

[CampaignFull](/reference/schemas#campaignfull)

---

## Delete campaign [#delete-campaign]

`DELETE /v1/campaigns/:id`

**Scope:** `campaigns:delete`

Soft-deletes the campaign.

### Response `204` [#response-204]

HTTP status is `204`. The handler may attach a JSON body `{ "message": "..." }` (Express quirk). Treat success as status `204`.

---

## Clone campaign [#clone-campaign]

`POST /v1/campaigns/:id/clone`

**Scope:** `campaigns:clone`

No request body.

### Response `200` [#response-200-3]

[CampaignFull](/reference/schemas#campaignfull)

---

## Toggle status [#toggle-status]

`PUT /v1/campaigns/:id/toggle-status`

**Scope:** `campaigns:toggle`

Toggles the campaign `active` flag. No request body.

### Response `200` [#response-200-4]

Empty body. Re-fetch with GET show if you need the updated `active` value.