v1

latestOpenAPI 3.0.42026-08-068161,1253.1 MB

Advertising

Create a campaign

Creates an ad campaign in the billing account. The creatives you reference must already exist as Open Cloud image assets that you have permission to use; they are validated and saved to your account's reusable creatives when the campaign is created. On success the campaign is returned with deliveryStatus IN_REVIEW, meaning it is queued for ad-policy review and not yet serving — poll the campaign (or campaigns:batchGetStatus) until this changes. budget.amountMicros is the budget in micro-USD as a decimal string (e.g. "5000000" = $5.00). It must be at least the minimum campaign budget; an amount below the minimum returns 400 with the required minimum stated in the error message. schedule.durationInDays must not exceed 3650 (~10 years). The x-idempotency-key header is required and must be a UUID: retrying the same key with an identical body within 24 hours returns the original campaign (200), while reusing a key with a different body returns 409.

post/ads-management/v1/campaigns

Headers

x-idempotency-keystring required

Idempotency key (UUID); 24h dedupe window. Identical replay returns the original campaign (200); mismatched replay may conflict (409).

Request body

creativeAssetIdsstring[] required

The Open Cloud image asset IDs to advertise, as decimal strings. Required. The assets must already exist and be usable by the caller.

namestring required

The display name of the campaign. Required.

objective'ENGAGEMENT' required

The advertising goal. Required. Only ENGAGEMENT is supported in v1.

paymentType'CREDIT_CARD' | 'ADS_CREDIT' | 'INVOICE' required

How the campaign is paid for. Required. Can be CREDIT_CARD, ADS_CREDIT, or INVOICE, subject to what the billing account supports.

targetUniverseIdstring required

The identifier of the experience to advertise. Required.

Response

Campaign created, or idempotent replay of a prior create with the same key and body

billingAccountIdstring

The billing account that owns and funds the campaign.

createTimestring

The time the campaign was created, as an RFC 3339 UTC timestamp.

creativeAssetIdsstring[]

The Open Cloud image asset IDs the campaign advertises, as decimal strings.

deliveryStatus'SERVING' | 'IN_REVIEW' | 'NOT_SERVING' | 'REJECTED'

The current serving state, derived by the system (read-only). Can be SERVING, IN_REVIEW, NOT_SERVING, or REJECTED.

deliveryStatusReasonsstring[]

The reasons behind the current deliveryStatus, such as why a campaign is not serving or was rejected, or LEARNING while a serving campaign ramps up. Omitted when there are none.

idstring

The server-assigned unique identifier of the campaign.

namestring

The display name of the campaign.

objective'ENGAGEMENT'

The advertising goal of the campaign. Only ENGAGEMENT is supported in v1.

paymentType'CREDIT_CARD' | 'ADS_CREDIT' | 'INVOICE'

How the campaign is paid for. Fixed when the campaign is created. Can be CREDIT_CARD, ADS_CREDIT, or INVOICE.

status'ACTIVE' | 'PAUSED' | 'CANCELLED'

The lifecycle state you control through update requests. Can be ACTIVE, PAUSED, or CANCELLED. CANCELLED is permanent.

targetUniverseIdstring

The identifier of the experience the campaign advertises.

updateTimestring

The time the campaign was last updated, as an RFC 3339 UTC timestamp.