Advertising API Reference: Endpoints and Examples

OpenAPI YAML OpenAPI JSON problems YAML API overview

This group has 46 operations, generated from api/openapi.yaml. Filter by path, action, or authentication. Each endpoint lists its inputs; expand it for a request template and response codes. Templates need your own values and a schema-valid body.

Replace uppercase placeholders with your values. For a JSON request, save a body matching the schema in request.json. Cookie examples use a local cookie jar from an authenticated session.

Private advertising networks and campaigns

GET/api/advertising/network¶

Get Advertising Network

The calling seller's one network, including its resolved ScreenRig serving fee. Sellers cannot change that fee.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingNetwork

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/network'

Responses

Status	Meaning	Body and headers
200	Network.	AdvertisingNetwork (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/network¶

Create Advertising Network

Creates the calling seller's one network if absent. Requires screens=true. Idempotent; repeating returns the same network.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingNetworkCreate
Operation ID: createAdvertisingNetwork

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request body fields

Field	Description
name (required, string)	maxLength: 120

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/network'

Responses

Status	Meaning	Body and headers
200	Network.	AdvertisingNetwork (application/json)
403	forbidden - the project lacks screen capability or has an unknown plan.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/network/rate¶

Set Advertising Default Rate

Sets the seller's project default rate per 15 seconds of completed playback. A change that alters an accepted campaign's effective rate pauses that whole campaign with price_change_pending; a masked or no-op change does not. If-Match carries the network revision.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingRate
Operation ID: setAdvertisingDefaultRate

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
rate_mcr_per_15s (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/network/rate'

Responses

Status	Meaning	Body and headers
200	Updated network.	AdvertisingNetwork (application/json)
412	revision_conflict - If-Match is stale.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/inventory¶

List Advertising Inventory

The calling seller's opted-in inventory.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/inventory'

Responses

Status	Meaning	Body and headers
200	Inventory.	AdvertisingInventoryList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

PUT/api/advertising/inventory/{screen_id}¶

Put Advertising Inventory

Upserts one owned screen's inventory. Verifies screen ownership. A rate override of null restores inheritance, not zero. A change that alters an accepted campaign's effective rate pauses that campaign. A screen in a protected screen folder is protected_target (409).

Authentication: projectBearer
Request body: AdvertisingInventoryWrite
Operation ID: putAdvertisingInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
screen_id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
impressions_per_hour (optional, inline)	The seller's estimate of the impressions this screen delivers in an hour. Each completed play counts this times its seconds over 3600 as estimated impressions in reports. Null or absent means no estimate.
ads_enabled (required, boolean)
site_name (optional, string)	maxLength: 120
city (optional, string)	maxLength: 120
region (optional, string)	maxLength: 120
venue_type (optional, string)	maxLength: 64
audience_tags (optional, array)
placement (optional, string)	maxLength: 120
public_description (optional, string)	maxLength: 500
rate_override_mcr_per_15s (optional, inline)	Null restores inheritance from the project default; it never means zero.

Request template and responses

shell · request template

curl --request PUT --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/inventory/SCREEN_ID'

Responses

Status	Meaning	Body and headers
200	Stored inventory.	AdvertisingInventory (application/json)
403	forbidden - the screen is not owned by this project; outside_screen_scope or approver_required for a caller limited to screens.	Problem (application/problem+json)
409	protected_target - the screen is in a protected screen folder and the change has no review form (docs/screen-scope.md); clear the folder's protection through a review, make the change, and protect the folder again.	Problem (application/problem+json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/slots¶

List Advertising Slots

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingSlots

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/slots'

Responses

Status	Meaning	Body and headers
200	Slots.	AdvertisingSlotList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/slots¶

Create Advertising Slot

Creates a reusable seller slot. Images are 5-30 seconds and videos at most the platform ceiling of 120 seconds. Ads are always muted.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingSlotWrite
Operation ID: createAdvertisingSlot

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
enabled (optional, boolean)
accepted_media (required, array)
max_image_duration_ms (required, integer)	minimum: 5000 maximum: 30000
max_video_duration_ms (required, integer)	minimum: 1000 maximum: 120000
rate_override_mcr_per_15s (optional, inline)
vast_tag_url (optional, inline)	The seller's own VAST 2-4 ad tag, tried when no invited campaign fills this slot on the seller's own screens. HTTPS on port 443 or 8443 to a public host only. The backend fetches it, follows up to five Wrappers, ingests the chosen progressive MP4 or WebM MediaFile into the project's media, and fires Impression, creativeView and start on an accepted start, complete on an accepted completion, and Error on failure. Quartile trackers are not fired. Macros [CACHEBUSTING], [TIMESTAMP], [SCREENRIG_SCREEN_ID], [SCREENRIG_SLOT_ID] and [SCREENRIG_PAGE_ID] are expanded. The slot must accept video. Null, absent, or empty clears the tag. Buyers never see it.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/slots'

Responses

Status	Meaning	Body and headers
201	Slotslot.	AdvertisingSlot (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/slots/{id}¶

Update Advertising Slot

Updates one seller slot. If-Match carries the slot revision. A rate override change re-runs the pricing fence. An optional Idempotency-Key replays the original committed result for 24 hours with the same slot, body and If-Match, even after later edits. Changed reuse returns idempotency_mismatch. A new stale write returns revision_conflict.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingSlotWrite
Operation ID: updateAdvertisingSlot

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
enabled (optional, boolean)
accepted_media (required, array)
max_image_duration_ms (required, integer)	minimum: 5000 maximum: 30000
max_video_duration_ms (required, integer)	minimum: 1000 maximum: 120000
rate_override_mcr_per_15s (optional, inline)
vast_tag_url (optional, inline)	The seller's own VAST 2-4 ad tag, tried when no invited campaign fills this slot on the seller's own screens. HTTPS on port 443 or 8443 to a public host only. The backend fetches it, follows up to five Wrappers, ingests the chosen progressive MP4 or WebM MediaFile into the project's media, and fires Impression, creativeView and start on an accepted start, complete on an accepted completion, and Error on failure. Quartile trackers are not fired. Macros [CACHEBUSTING], [TIMESTAMP], [SCREENRIG_SCREEN_ID], [SCREENRIG_SLOT_ID] and [SCREENRIG_PAGE_ID] are expanded. The slot must accept video. Null, absent, or empty clears the tag. Buyers never see it.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/slots/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated slot.	AdvertisingSlot (application/json)
409	idempotency_mismatch.	Problem (application/problem+json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/memberships¶

List Advertising Memberships

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingMemberships

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/memberships'

Responses

Status	Meaning	Body and headers
200	Memberships.	AdvertisingMembershipList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/memberships/{id}¶

Update Advertising Membership

Explicit seller policy/scope edit. An active membership is changed here, never by sending a second invitation. Scope changes stop new selection; financial history is preserved.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingMembershipScope
Operation ID: updateAdvertisingMembership

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
policy (required, string)	Allowed: "trusted", "review_required"
screen_ids (required, array)
slot_ids (required, array)

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/memberships/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated membership.	AdvertisingMembership (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/memberships/{id}/revoke¶

Revoke Advertising Membership

Revokes one membership. Stops new selection for that network; it does not clear the advertiser flag, other memberships, or settled history.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: revokeAdvertisingMembership

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/memberships/RESOURCE_ID/revoke'

Responses

Status	Meaning	Body and headers
200	Revoked membership.	AdvertisingMembership (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/networks¶

List Advertising Joined Networks

Networks the calling advertiser currently belongs to, with the scope and review policy it was granted. Screen count is not a guaranteed impression count.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingJoinedNetworks

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/networks'

Responses

Status	Meaning	Body and headers
200	Joined networks.	AdvertisingJoinedNetworkList (application/json)
403	forbidden - the project lacks the advertiser flag.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/networks/{seller_project_id}/inventory¶

List Advertising Joined Inventory

Opted-in inventory and reusable slots inside the caller's membership. Never exposes the seller's screenshots, playlists, or project-wide data.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingJoinedInventory

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
seller_project_id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/networks/SELLER_PROJECT_ID/inventory'

Responses

Status	Meaning	Body and headers
200	Permitted inventory and slots.	AdvertisingJoinedInventory (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/creatives¶

List Advertising Creatives

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingCreatives

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/creatives'

Responses

Status	Meaning	Body and headers
200	Creatives.	AdvertisingCreativeList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/creatives¶

Create Advertising Creative

Binds one ready owned media revision to an immutable creative. Does not copy bytes, re-upload, or re-charge generation. Unknown or non-ready media is rejected.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingCreativeCreate
Operation ID: createAdvertisingCreative

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
media_id (required, string)
copy (optional, string)	maxLength: 500

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/creatives'

Responses

Status	Meaning	Body and headers
201	Creative.	AdvertisingCreative (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/creatives/{id}¶

Get Advertising Creative

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingCreative

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/creatives/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Creative.	AdvertisingCreative (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/seller-campaigns¶

List Advertising Seller Campaigns

The calling seller's submitted buyer campaigns, including campaigns with no plays and history after buyer access is revoked. Returns at most 100 campaigns in identifier order. Drafts, other networks and buyer-wide budgets are private. Follow next_after with after until it is absent.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingSellerCampaigns

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
after	query	optional	The preceding page's next_after.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/seller-campaigns'

Responses

Status	Meaning	Body and headers
200	Submitted buyer campaigns on this seller's network.	AdvertisingSellerCampaignList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/seller-campaigns/{id}¶

Get Advertising Seller Campaign

One submitted buyer campaign's read-only seller view. Inventory and lifetime settled delivery cover the calling seller only. Buyer-wide finances and other networks are private. An unrelated seller gets not_found.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingSellerCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/seller-campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	The seller's campaign and delivery details.	AdvertisingSellerCampaignDetail (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/campaigns¶

List Advertising Campaigns

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingCampaigns

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns'

Responses

Status	Meaning	Body and headers
200	Campaigns.	AdvertisingCampaignList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns¶

Create Advertising Campaign

Creates a draft campaign. Drafts hold no money, reserve nothing, and authorize no delivery. Activation requires an explicitly accepted quote.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingCampaignDraft
Operation ID: createAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
category (optional, AdvertisingCategory)	The advertiser category. Two ads of one category never play in the same ad break on a screen; an ad without a category is never separated. Allowed: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"
daily_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
lifetime_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
image_duration_ms (optional, integer)	Campaign-wide image dwell time. Videos keep their server-verified duration. default: 10000 minimum: 5000 maximum: 30000
max_play_price_mcr (optional, inline)	Positive maximum completed-play price. Omit for no additional ceiling.
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
networks (required, array)

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns'

Responses

Status	Meaning	Body and headers
201	Draft campaign.	AdvertisingCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/campaigns/{id}¶

Get Advertising Campaign

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Campaign.	AdvertisingCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}¶

Update Advertising Campaign

Updates a draft campaign. If-Match carries the campaign revision. A budget reduction below already spent plus committed reservations is rejected with the minimum permitted value.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingCampaignDraft
Operation ID: updateAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 120
category (optional, AdvertisingCategory)	The advertiser category. Two ads of one category never play in the same ad break on a screen; an ad without a category is never separated. Allowed: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"
daily_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
lifetime_cap_mcr (required, McrString)	Exact integer millicredit amount as a canonical decimal string. 1 credit is 1000 mcr. pattern: "^-?[0-9]+$"
image_duration_ms (optional, integer)	Campaign-wide image dwell time. Videos keep their server-verified duration. default: 10000 minimum: 5000 maximum: 30000
max_play_price_mcr (optional, inline)	Positive maximum completed-play price. Omit for no additional ceiling.
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
networks (required, array)

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated campaign.	AdvertisingCampaign (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/quote¶

Quote Advertising Campaign

Prices the campaign's current effective rates, formats, durations, flight and caps before activation. The quote is time-bounded and becomes stale when any pricing generation or effective rate changes.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: quoteAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/quote'

Responses

Status	Meaning	Body and headers
201	Quote.	AdvertisingQuote (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/activate¶

Activate Advertising Campaign

Explicitly accepts the named current quote and activates the campaign. Atomically checks ownership, membership, quote expiry, rate revisions, accepted scope and same-project denial, then records purchase terms. No wallet debit and no seller revenue occur from accepting terms. The same key with the same body replays; a changed body is a conflict.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingQuoteAccept
Operation ID: activateAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.
Idempotency-Key	header	optional	Omit for a fresh operation. Supply and reuse a key to deduplicate retries; the CLI manages keys automatically.

Request body fields

Field	Description
quote_id (required, string)

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/activate'

Responses

Status	Meaning	Body and headers
200	Active or pending-review campaign.	AdvertisingCampaign (application/json)
409	quote_stale or self_deal or resource_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/pause¶

Pause Advertising Campaign

Pauses new reservations for this campaign. Already-started valid ads normally finish and are charged on completion.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: pauseAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/pause'

Responses

Status	Meaning	Body and headers
200	Paused campaign.	AdvertisingCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/resume¶

Resume Advertising Campaign

Resumes a manually paused campaign. It cannot clear a price_change_pending block; a top-up, schedule tick, or seller action cannot supply that consent.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: resumeAdvertisingCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/resume'

Responses

Status	Meaning	Body and headers
200	Resumed campaign.	AdvertisingCampaign (application/json)
409	price_change_pending - accept current rates first.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/campaigns/{id}/accept-rates¶

Accept Advertising Rates

The buyer's explicit acceptance of changed effective rates, bound to quote ID, campaign revision and current pricing generations. It atomically replaces future delivery terms, records the actor and time, and clears the sticky price-change block. Another concurrent rate change leaves the campaign paused.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingQuoteAccept
Operation ID: acceptAdvertisingRates

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
quote_id (required, string)

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/campaigns/RESOURCE_ID/accept-rates'

Responses

Status	Meaning	Body and headers
200	Reactivated campaign.	AdvertisingCampaign (application/json)
409	price_change_pending or quote_stale.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reviews¶

List Advertising Reviews

Creative versions submitted to the calling seller for review. A seller sees only exact submitted creative, never the buyer's library.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingReviews

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews'

Responses

Status	Meaning	Body and headers
200	Reviews.	AdvertisingReviewList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/reviews/{id}/approve¶

Approve Advertising Review

Approves one exact submitted creative revision. Approval does not choose the buyer's budget or grant access to its media library. A person must be able to approve reviews (approver_required). The same review is also reachable as kind ad_creative under /api/reviews.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: approveAdvertisingReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/approve'

Responses

Status	Meaning	Body and headers
200	Approved review.	AdvertisingReview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/reviews/{id}/reject¶

Reject Advertising Review

Rejects one exact submitted creative revision with a reason the buyer reads on the creative. A person must be able to approve reviews (approver_required).

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingReviewRejection
Operation ID: rejectAdvertisingReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request body fields

Field	Description
reason (required, string)	minLength: 1 maxLength: 500

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/reject'

Responses

Status	Meaning	Body and headers
200	Rejected review.	AdvertisingReview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reports/spend¶

Get Advertising Spend

Buyer-scoped spend and delivery counts for one campaign. Amounts are decimal mcr strings. It never exposes the seller's income, bank status, or project-wide usage.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingSpend

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
format	query	optional	json (default) returns the report as JSON. csv, xlsx and pdf return the same rows as a file attachment (every page of a paged report, up to 50000 rows).
campaign_id	query	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/spend?campaign_id=CAMPAIGN_ID'

Responses

Status	Meaning	Body and headers
200	Spend report.	AdvertisingSpendReport (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reports/delivery¶

Get Advertising Delivery

Seller-scoped gross, serving fee and net for one window, with its own delivery evidence. It never exposes the buyer's wallet or other networks. Only authorized completed-play evidence establishes billable delivery. The window is at most 92 days; a wider window is invalid_request.

When it holds more than 5000 settlements the response sets truncated, totals and counts still cover all of them and rows lists only the earliest 5000.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingDelivery

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
format	query	optional	json (default) returns the report as JSON. csv, xlsx and pdf return the same rows as a file attachment (every page of a paged report, up to 50000 rows).
from	query	required
to	query	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/delivery?from=FROM&to=TO'

Responses

Status	Meaning	Body and headers
200	Delivery report.	AdvertisingDeliveryReport (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/direct-campaigns¶

List Advertising Direct Campaigns

The calling seller's direct campaigns, newest first, with their pace.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: listAdvertisingDirectCampaigns

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns'

Responses

Status	Meaning	Body and headers
200	Direct campaigns.	AdvertisingDirectCampaignList (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/direct-campaigns¶

Create Advertising Direct Campaign

Books a direct campaign, a deal the seller made with an outside advertiser, on the seller's own ad inventory. It moves no money; the seller bills the advertiser and the price is recorded for the report's value. It is active at once and fills before marketplace campaigns.

A goal campaign is paced evenly over its flight and plays first while behind pace; a campaign without a goal takes every eligible slot during its flight. Two ads of one category never play in the same ad break on a screen. A goal above the availability estimate is refused with goal_overbooked unless overbook is true.

The same key with the same body replays; a changed body is a conflict.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingDirectCampaignDraft
Operation ID: createAdvertisingDirectCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
Idempotency-Key	header	required

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 200
advertiser (required, string)	minLength: 1 maxLength: 200
category (optional, AdvertisingCategory)	The advertiser category. Two ads of one category never play in the same ad break on a screen; an ad without a category is never separated. Allowed: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
goal_plays (optional, integer)	The plays to deliver, paced evenly over the flight. Zero or omitted takes every eligible slot during the flight. minimum: 0 maximum: 1000000000000
price (optional, AdvertisingDirectPrice)	The deal price the seller recorded. screenRIG never charges it; it values the report.
media_ids (required, array)	The seller's ready images and videos, each named once.
image_duration_ms (optional, integer)	Campaign-wide image dwell time. Videos keep their server-verified duration. default: 10000 minimum: 5000 maximum: 30000
screen_ids (optional, array)	Empty means every opted-in screen.
slot_ids (optional, array)	Empty means every enabled slot.
venue_types (optional, array)
cities (optional, array)
tags (optional, array)
dayparts (optional, array)
overbook (optional, boolean)	Books a goal above the availability estimate. Without it the request is refused with goal_overbooked. default: false

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Idempotency-Key: REQUEST_ID' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/direct-campaigns'

Responses

Status	Meaning	Body and headers
201	Direct campaign.	AdvertisingDirectCampaign (application/json)
402	feature_not_in_plan — the project's plan does not include direct campaigns; required_plan names the plan that does.	Problem (application/problem+json)
409	goal_overbooked or resource_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/direct-campaigns/{id}¶

Get Advertising Direct Campaign

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingDirectCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Direct campaign.	AdvertisingDirectCampaign (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/direct-campaigns/{id}¶

Update Advertising Direct Campaign

Replaces the campaign's draft fields. If-Match carries the campaign revision. Delivered plays are kept. The plays still to deliver are checked against the availability estimate with the campaign's own booking left out, and overbook books them anyway.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingDirectCampaignDraft
Operation ID: updateAdvertisingDirectCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request body fields

Field	Description
name (required, string)	minLength: 1 maxLength: 200
advertiser (required, string)	minLength: 1 maxLength: 200
category (optional, AdvertisingCategory)	The advertiser category. Two ads of one category never play in the same ad break on a screen; an ad without a category is never separated. Allowed: "alcohol", "apparel", "automotive", "beauty", "cannabis", "consumer_electronics", "education", "entertainment", "financial_services", "food_and_beverage", "gambling", "government", "grocery", "health_and_pharma", "home_and_garden", "insurance", "jobs", "legal", "media", "political", "quick_service_restaurants", "real_estate", "restaurants", "retail", "sports_and_fitness", "technology", "telecom", "tobacco_and_vaping", "travel", "utilities"
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
goal_plays (optional, integer)	The plays to deliver, paced evenly over the flight. Zero or omitted takes every eligible slot during the flight. minimum: 0 maximum: 1000000000000
price (optional, AdvertisingDirectPrice)	The deal price the seller recorded. screenRIG never charges it; it values the report.
media_ids (required, array)	The seller's ready images and videos, each named once.
image_duration_ms (optional, integer)	Campaign-wide image dwell time. Videos keep their server-verified duration. default: 10000 minimum: 5000 maximum: 30000
screen_ids (optional, array)	Empty means every opted-in screen.
slot_ids (optional, array)	Empty means every enabled slot.
venue_types (optional, array)
cities (optional, array)
tags (optional, array)
dayparts (optional, array)
overbook (optional, boolean)	Books a goal above the availability estimate. Without it the request is refused with goal_overbooked. default: false

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Updated direct campaign.	AdvertisingDirectCampaign (application/json)
402	feature_not_in_plan — the project's plan does not include direct campaigns; required_plan names the plan that does.	Problem (application/problem+json)
409	goal_overbooked or resource_conflict.	Problem (application/problem+json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/direct-campaigns/{id}/pause¶

Pause Advertising Direct Campaign

Stops new plays for an active campaign. Delivered plays and the flight are kept. A paused or ended campaign is a resource_conflict.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: pauseAdvertisingDirectCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/pause'

Responses

Status	Meaning	Body and headers
200	Paused direct campaign.	AdvertisingDirectCampaign (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/direct-campaigns/{id}/resume¶

Resume Advertising Direct Campaign

Resumes a paused direct campaign. A goal campaign that fell behind pace while paused plays first until it is back on pace. An active or ended campaign is a resource_conflict.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: resumeAdvertisingDirectCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/resume'

Responses

Status	Meaning	Body and headers
200	Resumed direct campaign.	AdvertisingDirectCampaign (application/json)
402	feature_not_in_plan — the project's plan does not include direct campaigns; required_plan names the plan that does.	Problem (application/problem+json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/direct-campaigns/{id}/end¶

End Advertising Direct Campaign

Ends an active or paused campaign before its flight does. An ended campaign plays no more and keeps its report.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: endAdvertisingDirectCampaign

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
If-Match	header	optional	Optional positive resource revision. Omit to write the current resource; a supplied stale revision is revision_conflict.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/end'

Responses

Status	Meaning	Body and headers
200	Ended direct campaign.	AdvertisingDirectCampaign (application/json)
412	revision_conflict.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/direct-campaigns/{id}/report¶

Get Advertising Direct Campaign Report

One direct campaign's delivery for a window, with its pace, the recorded value of the delivered plays and rows by UTC day, screen, slot and media. Without from and to the window is the whole flight. When the window holds more rows than the report lists, the response sets truncated and the totals still cover every play.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingDirectCampaignReport

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
format	query	optional	json (default) returns the report as JSON. csv, xlsx and pdf return the same rows as a file attachment (every page of a paged report, up to 50000 rows).
id	path	required
from	query	optional
to	query	optional

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/direct-campaigns/RESOURCE_ID/report'

Responses

Status	Meaning	Body and headers
200	Direct campaign report.	AdvertisingDirectReport (application/json)
402	feature_not_in_plan — the project's plan does not include direct campaigns; required_plan names the plan that does.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/availability¶

Estimate Advertising Availability

Estimates the plays a direct goal can book on the given inventory and flight. It is a read and changes nothing. The estimate is the targeted screens' recent ad slot occurrences projected over the flight, less the goals other direct campaigns still need on the same screens.

Authentication: projectBearer OR dashboardSession
Request body: AdvertisingAvailabilityQuery
Operation ID: estimateAdvertisingAvailability

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.

Request body fields

Field	Description
screen_ids (optional, array)	Empty means every opted-in screen.
slot_ids (optional, array)	Empty means every enabled slot.
venue_types (optional, array)
cities (optional, array)
tags (optional, array)
dayparts (optional, array)
flight_start (required, string)	format: "date-time"
flight_end (required, string)	format: "date-time"
exclude_campaign_id (optional, string)	Leaves this direct campaign's own booking out of booked_plays, for an edit.

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/availability'

Responses

Status	Meaning	Body and headers
200	Availability estimate.	AdvertisingAvailability (application/json)
402	feature_not_in_plan — the project's plan does not include direct campaigns; required_plan names the plan that does.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reports/fill¶

Get Advertising Fill Stats

The calling seller's ad slot supply for a window, per UTC day and in total. Each occurrence is filled by a direct campaign, a marketplace campaign or the VAST tag, or it is unfilled with the reason. The requested window is at most 35 days and defaults to the last 7. Supply has hourly precision.

All UTC hours overlapping the requested half-open window are included in full; from is rounded down and to up to UTC hour boundaries. An already aligned to remains exclusive. The response returns these effective bounds, which can span up to 35 days plus one hour.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingFillStats

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
format	query	optional	json (default) returns the report as JSON. csv, xlsx and pdf return the same rows as a file attachment (every page of a paged report, up to 50000 rows).
from	query	optional
to	query	optional

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reports/fill'

Responses

Status	Meaning	Body and headers
200	Fill statistics.	AdvertisingFillStats (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reviews/{id}¶

Get Advertising Review

Seller detail for one review of its network. Returns the review and the exact submitted creative revision. It never exposes the buyer's other media.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingReview

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID'

Responses

Status	Meaning	Body and headers
200	Review and its creative.	AdvertisingReviewDetail (application/json)
404	not_found - the review is unknown to this seller.	Problem (application/problem+json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

GET/api/advertising/reviews/{id}/content¶

Get Advertising Review Content

Streams only the exact creative revision this seller's own review refers to. Ownership stays with the buyer project; no object key or signed location is published, and no other buyer media is reachable. The ETag is the creative's strong SHA-256 and never changes for a review.

A dashboard session response is private, no-cache, so the browser keeps one copy and revalidates it; a project bearer response stays private, no-store.

Authentication: projectBearer OR dashboardSession
Request body: none
Operation ID: getAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Range	header	optional	V1 accepts one byte range only.
If-None-Match	header	optional	Strong creative SHA-256 ETag returned by this route.

Request template and responses

shell · request template

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	The review's exact creative bytes.	no body; headers: Accept-Ranges, Content-Length, ETag, Cache-Control
206	One standards-correct byte range.	no body; headers: Content-Range, ETag, Cache-Control
304	The creative's ETag matches If-None-Match, checked after the review resolves in the seller project. No body or egress increment is produced.	no body; headers: ETag, Cache-Control
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

HEAD/api/advertising/reviews/{id}/content¶

Head Advertising Review Content

Authentication: projectBearer
Request body: none
Operation ID: headAdvertisingReviewContent

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required
Range	header	optional	V1 accepts one byte range only.

Request template and responses

shell · request template

curl --request HEAD --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/content'

Responses

Status	Meaning	Body and headers
200	Metadata only.	no body; headers: Content-Length, ETag
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)

POST/api/advertising/reviews/{id}/request-changes¶

Request Advertising Review Changes

The seller asks the buyer for changes to one submitted creative revision. The review becomes changes_requested with the note in reason; the buyer reads it on the creative, and the next review the campaign opens for this seller links previous_review_id. A person must be able to approve reviews (approver_required).

Authentication: projectBearer OR dashboardSession
Request body: ReviewChangesRequest
Operation ID: requestAdvertisingReviewChanges

Parameters

Name	Send in	Required?	Description
ScreenRig-Project	header	optional	Deprecated for one release. Must be consistent with the JWT projects grants; adds Deprecation and Warning headers. No token exchange.
id	path	required

Request body fields

Field	Description
note (required, string)	minLength: 1 maxLength: 500

Request template and responses

shell · request template

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/advertising/reviews/RESOURCE_ID/request-changes'

Responses

Status	Meaning	Body and headers
200	The review, state changes_requested.	AdvertisingReview (application/json)
default	Stable RFC 9457 problem response. A 421 server_draining carries Retry-After of 1 second, a 500 not_ready or dependency_unavailable carries 5, and a 500 manifest_degraded carries 60, unless the handler set a more specific value.	Problem (application/problem+json)