Campaigns

📄️List campaigns (keyset-paginated)

Returns one page of the owner's non-deleted campaigns in the uniform list envelope `{ data, pagination }`, newest first. Keep paginating while `pagination.nextCursor` is non-null — even when `data` is empty — passing it back verbatim as `?cursor=`. Filter by `?status=` for an exact status match; omit it for all campaigns. Add `?showDeleted=true` to include deleted campaigns (every row then carries `deletedAt`).

📄️Create a campaign

Creates a campaign for a brand and opens one empty creative (`NOT_GENERATED`) per product; they have no public representation until generated, and generating them happens in the Mocart dashboard. Creating a campaign spends no credits. The `201` carries the campaign the way `GET /campaigns/{id}` returns it, and a `Location` header. `Idempotency-Key` is required: a retry with the same key and body returns the same campaign, never a second one. The account must be under its plan's campaign limit.

📄️Get a single campaign by id

Returns the single non-deleted campaign with the given stable Mocart campaign document id. Add `?showDeleted=true` to read a deleted campaign too (the body then carries `deletedAt`). The strong `ETag` header on the plain read identifies the campaign state; send it back as `If-Match` on `PATCH` or `DELETE`.

📄️Update a campaign

Renames the campaign and/or merges your own `metadata` map, and returns the campaign — the same body `GET /campaigns/{id}` returns. A request that changes nothing is a `200` that records nothing. `Idempotency-Key` and `If-Match` are optional.

📄️Delete a campaign

Deletes a campaign and every creative in it, and returns the campaign with `deletedAt` set. Nothing is destroyed: `POST /campaigns/{campaignId}/undelete` restores the campaign and the creatives that went with it, and `?showDeleted=true` still reads it. A campaign holding a creative that is `QUEUED` or `GENERATING` cannot be deleted yet. Deleting spends and refunds no credits and never cancels a run.

📄️Restore a deleted campaign

Restores a deleted campaign and the creatives that were deleted with it, and returns the campaign — the same body `GET /campaigns/{id}` returns. There is no time limit, but the restored campaign counts against the plan’s campaign limit like a new one (`403 LIMIT_EXCEEDED` at the cap). A creative deleted on its own stays deleted, and the campaign’s review links stay revoked. Restoring a campaign that is already live is a no-op `200`; `Idempotency-Key` is required.