Ad Placement Inventory
Manage ad placements on your website
List ad placements
List all ad placements for a workspace with filtering and pagination.
Authentication: Requires API Key in the Authorization header.
Query Parameters:
search: Filter by group_name, URL, or placement_idstatus: Filter by status (0=UNVERIFIED, 1=NOT_CONNECTED, 2=INSTALLED, 3=ACTIVE, 4=INACTIVE)format: Filter by ad formatgroup_name: Filter by group namegroup_by_url: If 'true', return one row per URL with placement countpage: Page number (default: 1)page_size: Items per page (default: 20)
path Parameters
project_idquery Parameters
group_by_urlGroup results by URL
pagePage number
page_sizeItems per page
searchSearch in group_name, URL, or placement_id
statusFilter by status
List ad placements › Responses
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Create/sync placements
Create or sync ad placements (bulk operation).
Send an array of placements to register. If a placement with the same
(project, url, placement_id) already exists, it won't be duplicated.
Authentication: Requires API Key.
WordPress Plugin Usage:
- Generate unique
placement_idvalues for each<div smalk-ads id="...">element - Call this endpoint to register all placements on page save
- Check the response to see which placements were created vs already existed
path Parameters
project_idCreate/sync placements › Request Body
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Create/sync placements › Responses
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Get placement details
Retrieve details for a specific ad placement by ID.
path Parameters
idA UUID string identifying this ad placement.
project_idGet placement details › Responses
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Update placement
Update an existing ad placement's settings.
path Parameters
idA UUID string identifying this ad placement.
project_idUpdate placement › Request Body
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Update placement › Responses
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Partially update placement
Update specific fields of an ad placement (e.g., status, active flag).
path Parameters
idA UUID string identifying this ad placement.
project_idPartially update placement › Request Body
idprojectcitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
urlURL of the page containing this placement
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
placement_position_displayposition_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
status_displayactiveIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
minimum_daily_rate^-?\d{0,6}(?:\.\d{0,…minimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idauto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Per-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,…Total revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datePartially update placement › Responses
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Verify placement HTML and ad server connection
Verify if the ad placement div exists on the page and test the ad server connection.
Verification process:
- Fetches the page HTML to check if
<div smalk-ads>element is present - The page fetch triggers the ad server (SSAI) to call our API
- Waits 2 seconds for the ad server to respond
- Checks if placement status was updated to INSTALLED
Status transitions:
- UNVERIFIED → NOT_CONNECTED: When HTML tag is found
- NOT_CONNECTED → INSTALLED: When ad server successfully calls our API
Note: Also verifies all other placements sharing the same URL.
path Parameters
idA UUID string identifying this ad placement.
project_idVerify placement HTML and ad server connection › Request Body
idprojecturlURL of the page containing this placement
placement_position_displaystatus_displayminimum_daily_rate^-?\d{0,6}(?:\.\d{0,… · requiredminimum_daily_rate_currencyis_auto_adsactive_bookings_countactive_booking_idPer-placement frame style. Overrides the project-level PublisherBrandSafety.frame_color when set. Null = inherit project default. Applies to the booking path for every value. The no-booking shell renders only for summary_toc and summary_video_transcript (other variants need an active booking to surface).
no- Nogrey- Greyblack- Blackclear- Cleargradient- Gradientshadow- Shadowlabel- Label onlypreview- Preview with gradient fadesummary_boxed_reveal- Summary — Boxed Revealsummary_editorial_brief- Summary — Editorial Briefsummary_video_transcript- Summary — Video Transcriptsummary_toc- Summary — Table of Contentssummary_expert_content- Summary — Expert Content2mo- Minimal · Ad Only2mc- Minimal · Toc2ms- Minimal · Summary2md- Minimal · Tldr2mv- Minimal · Video2to- Teaser · Ad Only2tc- Teaser · Toc2ts- Teaser · Summary2td- Teaser · Tldr2tv- Teaser · Video2po- Paragraph · Ad Only2pc- Paragraph · Toc2ps- Paragraph · Summary2pd- Paragraph · Tldr2pv- Paragraph · Video2fo- Full · Ad Only2fc- Full · Toc2fs- Full · Summary2fd- Full · Tldr2fv- Full · Video
last_served_atLast time an ad was served on this placement
total_impressionsTotal impressions served (denormalized)
total_revenue^-?\d{0,8}(?:\.\d{0,… · requiredTotal revenue generated (denormalized)
total_revenue_currencycreatedmodifiedpublisher_project_namecan_booknext_available_datecitation_sourcegroup_nameOptional group name for this placement (e.g., 'Homepage Hero Banner')
placement_idPublisher-defined placement ID (e.g., 'sidebar-top')
placement_typeType of placement (manual vs auto-generated)
MANUAL- Manual ValidationAUTO- Auto approval
Position of the placement on the page (not specified, top of page, bottom of page, middle of page, before comments, after comments, middle of comments)
0- Not Specified1- Top of Page2- Bottom of Page3- Middle of the page4- Before comments5- After Comments6- Middle of Comments
position_offset_charsVisible-text char count from start of main content container up to the placement div. Raw measurement backing placement_position. 0 with content_total_chars=0 indicates a structural fallback (div inside
content_total_charsVisible-text char count of the main content container on the page. Raw measurement backing placement_position.
statusCurrent status of the placement
0- Unverified (awaiting HTML verification)1- Not Connected (awaiting SSAI call)2- Installed (SSAI verified, no campaign)3- Active (has active campaign)4- Inactive (manually deactivated)5- Lazy (declared inventory, awaiting first serve)
activeIf False, this placement is excluded and will never receive ads (publisher preference)
allowed_formatsAllowed ad formats for this placement (empty = all)
auto_approve_bookingsEnable automatic approval of bookings for this placement
auto_approve_threshold_score^-?\d{0,3}(?:\.\d{0,…Minimum AI validation score required for auto-approval (0-100)
Verify placement HTML and ad server connection › Responses
Verification completed
List the URLs on your site that serve Smalk content
Returns the URLs on your site that are currently serving Smalk content, so you can refresh them and purge your CDN cache.
By default the response includes:
- URLs with an active ad booking, and
- URLs serving a video-transcript block.
Use the query parameters below to include additional URL types or to receive a lighter response shape.
URLs are returned exactly as you registered them (with www. where applicable) so they match your own canonical URLs.
Large inventories (?frames=toc can reach tens of thousands of URLs): the response supports two transfer optimisations — send Accept-Encoding: gzip to receive a gzip-compressed body (~85% smaller), and use conditional requests — the response carries an ETag; send it back as If-None-Match and you get 304 Not Modified with an empty body while the URL set is unchanged. Combining ?flat=true + gzip + If-None-Match is recommended for frequent polling.
path Parameters
project_idquery Parameters
flatWhen true, urls is a flat array of URL strings instead of objects — a lighter payload. Default false returns [{"url": …}] objects.
framesInclude summary-widget URLs (opt-in). Repeatable or comma-separated. toc → pages showing the table-of-contents summary widget; summary → pages showing another summary widget. Omitted by default. Values cumulate, e.g. ?frames=toc,summary.
transcriptsInclude video-transcript URLs. Default true. Set false to return only URLs that have an active ad booking.
List the URLs on your site that serve Smalk content › Responses
project_idgenerated_atcountList of URLs serving Smalk content. With ?flat=true this is a flat array of URL strings instead of objects.
Get inventory statistics
Get aggregated statistics for ad placement inventory.
Returns:
active_placements: Count of INSTALLED + ACTIVE placementsnon_installed_placements: Count of UNVERIFIED + NOT_CONNECTED + INACTIVE placementstotal_urls: Count of unique URLs with ad placementsactive_campaigns: Count of placements with ACTIVE statusinactive_placements: Count of INSTALLED placements (no active campaign)
path Parameters
project_idGet inventory statistics › Responses
Statistics retrieved successfully