Create a campaign
POST/campaigns
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.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
- 429
- 503
Created — or the replay of an earlier create with this key.
Response Headers
Strong hash of this response body.
The created campaign: /api/public/v1/campaigns/{campaignId}.
Bad Request. The Idempotency-Key header is missing (IDEMPOTENCY_KEY_REQUIRED) or malformed (INVALID_IDEMPOTENCY_KEY).
Unauthorized. Missing, malformed, unknown, revoked, or expired bearer token — or the token owner no longer holds the required entitlement (ENTITLEMENT_LOST). A uniform problem body is returned with a distinct code; no owner/condition detail (no-leak).
Forbidden. The key lacks the campaigns:write scope (API_TOKEN_SCOPE_DENIED); the account's plan does not include campaigns (TIER_REQUIRED); or the account is at its plan's campaign or products-per-campaign limit (LIMIT_EXCEEDED, with limitKey, limit and current) — a plan limit is 403, never 429.
Conflict. a request under this key is still in progress (IDEMPOTENCY_IN_PROGRESS, retry after Retry-After); or the key was already used for a different request (IDEMPOTENCY_KEY_REUSED).
Response Headers
Seconds to wait before retrying — on an in-progress or cascade-pending conflict only.
Unprocessable Content (VALIDATION_ERROR). The body is malformed — an unknown field, an empty productIds, a VIDEO format outside the video ratios, an invalid metadata — or brandId or a product id is not the account's own (a missing id and another account's are the same answer); every offending field is listed in errors[].
Too Many Requests. The per-token sliding window of 60 requests/minute was exceeded. The body is express-rate-limit's DEFAULT plain-text message (NOT the JSON problem+json envelope).
Response Headers
IETF draft-7 rate-limit policy/state (limit, remaining, reset).
Seconds to wait before retrying.
Service Unavailable. Writes are paused for this account (WRITES_PAUSED), or too many campaigns were being created at once and this one lost the race (SERVICE_UNAVAILABLE). Nothing was created and the Idempotency-Key is still usable: retry the SAME request after Retry-After.
Response Headers
Seconds to wait before retrying.