Tool reference

Get account and balance

• Read only

Read this account: prepaid balance (current_balance_cents), daily spend cap, trust tier, status, and profile. Call it first to see whether there is money to launch with. A zero balance blocks launching only; when the person wants to launch or add funds, use request_prepay_link and give them the link. Do not attach a payment link to answers about anything else.

Register a new account

• Changes things

Register a new Adprime Zero account at Tier 0 ($100/day cap). Returns an api_key the caller must store immediately; it is shown exactly once.

Create a payment link

• Changes things
• Not in ChatGPT

Request a funding handoff URL for the operator. amount_cents is required, from 500 ($5) to 500000 ($5,000); if the person named no amount, ask, or use 2000 ($20). External-agent keys receive an Adprime Zero login URL with the account email pre-filled; after browser verification, the flow continues to Stripe Checkout or Demo Wallet. The returned funding_intent_id is the durable status object to poll after the browser flow.

List payment links

• Read only
• Not in ChatGPT

List recent funding attempts for the account. Use this after a browser payment handoff to explain pending, succeeded, failed, expired, and provider status.

Get payment link status

• Read only
• Not in ChatGPT

Check the durable status of one funding intent after a human opens the hosted payment page. This reports local ledger state and provider payment status; a browser redirect alone is not proof of added balance.

List receipts

• Read only

List durable Adprime Zero receipt PDF records for card charges and prepaid funding (Stripe Checkout, automatic top-up, refunds, and adjustments). Ad spend and assistant usage are ledger history, not receipt PDFs.

Get receipt

• Read only

Fetch one receipt record. The PDF itself is available through GET /account/receipts/{receipt_document_id}/pdf with the same bearer credential, or through the dashboard/CLI download command.

List creatives

• Read only

List recent creatives with their exchange approval status and landing-page approval status. A campaign can launch only with a creative whose status is approved and whose destination is approved. Newest first; pass next_cursor as cursor for older creatives.

Get creative and approval status

• Read only

Read one creative: exchange approval status, landing-page approval with the reasons for any review or rejection, and the click URL. Poll this after submit_creative; exchange approval can take from minutes to about a day.

Check a creative before submitting

• Read only

Dry-run submit_creative: same body, returns would_be_status and reasons from the destination and format checks. Stores nothing and creates no exchange object. Use it before a real submit, especially for trusted click-tracker creatives with landing_page_url. It needs exactly one image source (image_url, image_base64, or account_media_id) even when you only want the landing-page verdict; there is no page-only check, so make a draft banner first (upload_media, then derive_banner_from_image) and pre-check with that.

Submit a creative for approval

• Changes things

Submit a banner creative for Beeswax/FreeWheel approval. Send the image as exactly one of account_media_id (a media item at the exact format size, e.g. from derive_banner_from_image), image_url, or image_base64. Adprime Zero validates the image shape and approves the landing page, then Beeswax is the approval authority. If destination.click_url uses a host from list_trusted_click_trackers, also send destination.landing_page_url (the final page the tracker redirects to): approval crawls that page and never fetches the tracker. landing_page_url is refused for any other click host.

List trusted click trackers

• Read only

Read-only list of click-tracker hosts the Adprime Zero operator trusts for this account. A creative whose click_url uses one of these hosts must also send destination.landing_page_url. Agents cannot add hosts.

Upload an image

• Changes things

Store an image in the account media library (PNG, JPEG, WebP, or GIF, up to 8MB). Returns its account_media_id and an expiring preview_url. Uploading does not submit or approve anything; use derive_banner_from_image to make a submittable banner from it.

List media library

• Read only

List images in the account media library, newest first: uploads, generated images, and derived banners (source_kind rendered_variant).

Get media item

• Read only

One media-library item with its size, byte count, and a fresh preview_url (expires in 72 hours) that a person can open in a browser.

Make a banner from an image

• Changes things

Cut a PNG or JPEG media item to an exact IAB banner size under 200KB (default) and store it as a new media item. cover (default) crops to the aspect ratio, steered by gravity or focal_point; contain keeps the whole image on a padded background. Returns account_media_id, the crop, warnings about anything cut off or degraded, and a preview_url. Read the warnings and look at the preview, then call pre_check_creative and submit_creative with account_media_id. Free; does not submit or approve anything.

Read the video ad guide

• Read only

Read this before making a video ad: the workflow, channel presets and safe zones, scene types, image and voice rules, disclosure, costs, and the AdSpec JSON Schema.

List video ad projects

• Read only

List video ad projects, newest first, with status, rendered presets, and a poster link.

Create a video ad project

• Changes things

Start a video ad project. Give the landing page URL; optionally a first spec. Returns video_project_id. Free.

Get video ad project

• Read only

One project: its current spec, version history, generated images and voice takes (ids, preview links, costs), and renders with download links.

Draft a video ad from the landing page (paid)

• Changes things
• Costs money

Write a first spec from the brief and the landing page's own text (claims are only taken from the page). Saves it as a new version and returns image suggestions to generate. Costs about 1-3 cents.

Save a video ad spec version

• Changes things

Save a new spec version (an edit). Returns the version number and preflight checks; fix every blocking check before rendering. Saving an identical spec returns the existing version. Free.

Generate an image for a video ad (paid)

• Changes things
• Costs money

Generate one image for a video ad or banner (photo, transparent product cutout, or texture), on brand when given a brand kit. Pass the kit product photos as reference_media_ids whenever the product appears, so the model draws the real product. Returns account_media_id for the spec and a preview_url. About 1-2 cents, 2-5 with references.

Record a voiceover line (paid)

• Changes things
• Costs money

Record one voiceover line with OpenAI's GPT-Live voice (checked word for word against the script). Renders record missing lines automatically; use this to hear a line or get a retake. About 1 cent; a line already recorded is free.

Check a video ad before rendering

• Read only

Preflight a spec version for each preset: channel shape and length, hook length, voice pace, captions, AI disclosure, claims, images, and that the CTA names the landing page. Free.

Preview frames of a video ad

• Read only

Render stills from the spec (rendered by the real composition) and return them as images, each with a signed link. Look at every frame before rendering: overflow, contrast, empty space, a slow first second. With record_voice the first call can take about a minute; if it times out, call it again: recorded lines are kept, so the retry is quick and not charged again. Free apart from voice.

Render a video ad

• Changes things

Render MP4s for 1-4 presets in the cloud (records any missing voice lines first, which is paid). Returns render ids at once; a render takes about 1-2 minutes, so poll get_video_render. Rendering itself is free.

Get a video render

• Read only

Status of one render. While it is still rendering this waits up to about 25 seconds before answering, so call it again only if status is still not succeeded or failed. When succeeded, download_url is a signed link to the MP4 (72 hours) and validation lists the delivery checks it passed.

List brand kits

• Read only

List the workspace's brand kits (the default first): colors, fonts, logo, voice, tone, image style, guidelines, and reference images with preview links. Read this before making images or videos so they are on brand.

Get a brand kit

• Read only

One brand kit with its reference images (logo, product photos, style references) and preview links.

Create a brand kit

• Changes things

Save a brand kit: name, six colors, fonts, voiceover defaults, tone, image style, guidelines, disclosure line. The workspace's first kit becomes its default. Then add the logo and product photos with add_brand_asset. Free.

Update a brand kit

• Changes things

Change any field of a brand kit, make it the default, or archive it. Free.

Add an image to a brand kit

• Changes things

Attach an image to a brand kit with a role: logo (drawn by the video composer), product (real product photos; used as references for generated images and directly in video scenes), or style (look and mood references). Free.

Remove an image from a brand kit

• Changes things
• Confirm first

Detach an image from a brand kit (the image stays in the media library). Free.

Make a brand kit from a website (paid)

• Changes things
• Costs money

Read a website's own colors, fonts, name, and copy and propose a brand kit (text colors are contrast-checked). Saves it with the site icon as a starting logo unless save is false. Show the buyer the result. About 1-2 cents.

List targeting sets

• Read only

List saved targeting sets (geography, audiences, inventory rules) to reuse in create_campaign.

Get targeting set

• Read only

Read one saved targeting set, including resolved audience segments and their data cost.

Create a targeting set

• Changes things

Create a named Targeting object reusable across campaigns. For audience segments, submit ids returned by discover_segments, not segment names; data CPM is estimated before delivery reconciliation. State/province targeting uses geo.include_regions / geo.exclude_regions with Beeswax region keys such as USA/WA (Washington), USA/CO, USA/NV; unknown keys are refused, never dropped, an included region must belong to an included country, and include_regions and exclude_regions cannot be combined (the exchange rejects both; to leave out a state, list every allowed state in include_regions).

Search audience segments

• Read only

Discover real third-party audience segments from the Adprime Zero Beeswax/LiveRamp catalog. Use the returned id as audience_segments.include_segments/exclude_segments in create_targeting; do not target by name. Each row includes estimated data CPM, reach, provider, and policy tier. Skip a row whose reach_nam is 0 or whose seat_serving.status is no_users or failed: nothing will match it, and a campaign that relies on it will not bid.

List campaigns

• Read only

List campaigns with status (draft, running, paused, auto_paused_daily_cap, ...), budgets, creative, and targeting ids. auto_paused_daily_cap is normal: the campaign spent its daily budget and resumes after midnight UTC. A member key lists only campaigns in its own teams; team_id narrows to one team or "unassigned". Newest first; pass next_cursor as cursor for older campaigns.

Get campaign

• Read only

Read one campaign: status, budgets, schedule, creative and targeting ids, and exchange ids once launched. Use get_campaign_performance for delivery numbers.

Create a draft campaign

• Changes things

Create a campaign linking an approved creative to a targeting with a budget. Optional team_id puts it in a team (see list_teams). A member key sees only campaigns in its own teams: with exactly one edit seat the campaign defaults to that team, with more than one team_id is required, and a key with only read seats cannot create. Owner and admin keys that omit team_id create an unassigned campaign.

Copy a campaign

• Changes things

Copy a campaign into a new pending-review campaign, optionally overriding name, flight dates, the creative set, targeting_id, and team_id. Omitted team_id keeps the source campaign team; null makes the copy unassigned (owner and admin keys only). A member key needs an edit seat on the source campaign team.

Launch a campaign (spends money)

• Changes things
• Costs money
• Confirm first

Launch a campaign: it starts bidding and spends the prepaid balance, up to its daily budget. The API refuses, and lists what is missing, unless the creative is approved by the exchange, its landing page is approved, and the account has available balance. A future start_at is honored: the campaign is set up now and serves from that time.

Pause a campaign

• Changes things

Pause a running campaign. It is switched off at the exchange right away. Spend from the last couple of hours can still appear afterwards, because reporting runs about two hours behind.

Resume a campaign (spends money)

• Changes things
• Costs money
• Confirm first

Resume a paused campaign. The same launch checks as activate_campaign run again (approvals and balance).

List creatives on a campaign

• Read only

List first-class creative associations for a campaign, including creative approval state, destination state, external Beeswax association ids, and per-creative performance totals. Per-creative totals count hourly Beeswax reporting only, which runs about two hours behind, so a creative can read zero while get_campaign_performance already shows the line item delivering. That zero means not reported per creative yet, not did not serve.

Add a creative to a campaign

• Changes things

Add an approved creative to an existing campaign rotation. The API enforces creative approval, destination approval, blocked-domain policy, and exchange sync safety.

Replace a creative on a campaign

• Changes things
• Confirm first

Add a replacement creative and optionally pause the prior active/primary creative association. This keeps a durable replacement trail.

Pause a creative on a campaign

• Changes things

Pause one creative association on a campaign. The API blocks pausing the final active creative; pause the whole campaign instead.

Resume a creative on a campaign (spends money)

• Changes things
• Costs money
• Confirm first

Resume one paused creative association after the creative and destination gates are valid again.

Remove a creative from a campaign

• Changes things
• Confirm first

Remove one creative association from a campaign after first deactivating it externally when possible.

Query performance

• Read only

Query campaign reporting from Adprime Zero rollups. Supports delivery metrics (impressions, clicks, spend_cents, ctr_bps) and conversion metrics (conversions, cvr_bps, cpa_cents, roas_bps) when conversion events are linked. Read freshness_status, metric_sources, and warnings before concluding zero clicks: snapshot rows can provide timely impressions/spend while Beeswax Reporting rows are the provider click source. Beeswax provider reports must use clicks plural; ad_click_tokens are not delivery click truth.

List campaign performance

• Read only

Return a one-call account-wide campaign performance table with campaign status, budgets, exchange IDs, delivery, conversions, freshness_status, metric_sources, warnings, and next actions. Use this first when the buyer asks how all campaigns are doing or whether zero clicks is real. totals cover every matching campaign; items are a newest-first page (limit, default 100, max 500), so pass next_cursor as cursor for the rest.

Get campaign performance

• Read only

Fetch the campaign-scoped hourly delivery rollup convenience view, including conversion totals when events are linked. The response includes local read time, provider sync timestamps, metric sources, and warnings. If impressions/spend exist but clicks are zero, inspect freshness_status before telling the user the campaign had no clicks.

Get reporting freshness

• Read only

Check Beeswax Reporting freshness for one campaign. Use this when campaign performance has impressions/spend but zero clicks, or whenever freshness_status from performance is not fresh.

Refresh campaign reporting

• Changes things

Ask Adprime Zero to run the due Beeswax Reporting reconciliation, then return a durable reporting_refresh_id and poll URL. This does not bypass provider async lag; if status is pending, call get_beeswax_reporting_refresh_status before treating zero clicks as final.

Get reporting refresh status

• Read only

Poll a durable Beeswax Reporting refresh request returned by refresh_beeswax_campaign_reporting. Use the reporting_refresh_id, not a provider task id.

List reporting sync runs

• Read only

List recent Beeswax Reporting provider sync runs for recovery/debugging. This is provider control-plane metadata; use campaign performance/status tools to interpret a specific campaign.

Get landing funnel summary

• Read only

Summarize first-party funnel evidence for owned campaigns: traffic-split assignments, landing-page visits, landing-page leads, click-token issuance, and clicked-token counts. This is not Beeswax delivery click truth.

List campaign click tokens

• Read only

List first-party click-token records for a campaign. These records support redirect/attribution debugging; provider delivery clicks still come from Beeswax Reporting.

Create a conversion event

• Changes things

Create an advertiser conversion event. Returns ingest_secret once. Use kind=lead for form fills and kind=honeypot for bot traps that must never be a campaign optimization goal. postback_auth defaults to secret; set event_id for an ID-only postback URL with no secret in it (the usual affiliate-network pattern). Never embed ak_ API keys in tags.

List conversion events

• Read only

List conversion events for the account.

Get conversion event

• Read only

Fetch one conversion event with recent ingest counters.

Update a conversion event

• Changes things

Update a conversion event name, value defaults, attribution windows, status, or postback_auth. Use this instead of creating a duplicate event when the buyer is correcting setup. postback_auth=event_id makes public ingest accept fires with only the event id (no secret), rate limited per event and client IP; a supplied secret is still checked and a wrong one rejected. postback_auth=secret requires the ingest secret again. Re-read get_conversion_event_install afterwards, because get_postback_url changes.

Get conversion install code

• Read only

Return the GET postback URL (get_postback_url) plus browser pixel, JS, and POST examples. Agents must paste get_postback_url verbatim. Do not invent tag URLs. When postback_auth is event_id, none of the URLs carry a secret; do not add one.

Link a conversion event to a campaign

• Changes things

Link a conversion event to a campaign for attribution.

Unlink a conversion event from a campaign

• Changes things
• Confirm first

Remove the attribution link between a conversion event and a campaign. This does not delete historical ingest or attribution rows.

Send a test conversion

• Changes things

Fire a synthetic test conversion through the ingest pipeline.

Get conversion ingest log

• Read only

Fetch recent ingest attempts for one conversion event. Use this to verify browser pixels, server postbacks, and test fires before optimizing campaigns toward conversions. ingest_auth says how each row was authenticated: secret, event_id (accepted without a secret), or api_key (test fire).

Turn conversion optimization on or off

• Changes things
• Confirm first

Turn the conversion optimization loop on or off for one campaign. Opt-in is required: the loop evaluates nothing until this is enabled. Set conversion_optimization_auto_apply true for AUTOPILOT: the server applies waste bid-downs (placement/site at 0.3x) itself and judges each about a day later, reverting automatically if delivery collapsed; bid strategy and CPA target changes are still only proposed. Disabling stops new proposals, turns autopilot off, and does NOT revert changes that were already applied, which still need judging.

Get campaign conversion signal

• Read only

Read one campaign conversion picture over a window: goal conversions, funnel (lead/form-fill) conversions, honeypot trap fires, attribution confidence, raw CPA, and quality-adjusted CPA. Trap fires are reported separately and must never be treated as conversions. Spend is already reconciled across the two reporting sources; do not re-derive it.

List proposed optimizations

• Read only

List reversible conversion-optimization proposals for a campaign, newest first. Each carries a rationale, the deciding metric named before the change, a confidence score, before_state, and a revert_command. Read this before proposing anything yourself.

Apply an optimization to live bidding

• Changes things
• Confirm first

Apply one proposed optimization action to live delivery. You must restate expected_lever, which fails the call if the proposal changed since you read it. Only one action per campaign may be in flight, because two simultaneous changes make the result unattributable. After applying you are expected to judge it.

Keep or revert an applied optimization

• Changes things
• Confirm first

Record whether an applied optimization action is kept or reverted, with a note. REVERT IS A NORMAL OUTCOME, not a failure. An applied change that is never judged becomes permanent policy by default, which is the state this surface exists to prevent. Reverting restores the exact provider payload captured before the change.

Get traffic audit status

• Read only

Check Supply Audit (Beta) status for this account: whether nightly supply scanning is active, the detector thresholds in force, open finding counts, and the last scan including whether its provider read was truncated. Read this before interpreting findings.

Turn on the nightly traffic audit

• Changes things

Turn on nightly supply-quality scanning for this account. The scan is read-only against provider reporting: it never changes budgets, pauses campaigns, or writes exchange objects. Findings are recommendations only in this release.

Turn off the nightly traffic audit

• Changes things

Stop nightly supply-quality scanning for this account. Existing findings are retained so historical evidence is not lost.

Update traffic audit settings

• Changes things

Tune Supply Audit detector thresholds and scan cadence. Thresholds are in basis points where noted (100 bps = 1.00%). Raise floors to reduce noise; lower them to catch more marginal waste. Changes apply to the next scan, and existing findings keep the thresholds they were created under.

List traffic audit findings

• Read only

List supply-quality findings for this account, highest wasted spend first. Each finding names the supply entity, the detector that fired, the delivery metrics, and an evidence object with the thresholds and metric sources used. IMPORTANT: confidence `instrumentation_gap` means downstream behavior could not be measured and must NOT be read as proof of invalid traffic. Clicks are provider delivery clicks from the Reporting API `clicks` field, which is distinct from click tokens and from landing page views.

Acknowledge a traffic finding

• Changes things

Mark a supply finding as reviewed without rejecting it. Use this when you have seen a finding and plan to act on it later, so the next scan does not treat it as new.

Dismiss a traffic finding

• Changes things

Reject a supply finding as a false positive. The evidence is preserved rather than deleted so threshold tuning can be reviewed later.

Create targeting that excludes a finding

• Changes things

Act on an exchange-grain supply finding by creating a NEW targeting set that leaves the flagged exchange out. The new targeting is cloned from the targeting the flagged campaign already used, so geo, content, segment, environment, and device choices are preserved and only the exchange allowlist changes. This does NOT pause, edit, or activate any campaign or line item, does NOT write to Beeswax, and does NOT change any budget: point your next campaign at the returned targeting_id. Only `inventory_source` findings can be applied; placement, domain, site, and app_bundle findings are refused with code `grain_not_applicable` because Beeswax app_site list targeting is not available on this seat. An apply that would leave the allowlist empty is refused with `would_exclude_everything`, because an empty allowlist matches no inventory and the next campaign would not serve. If the source targeting had no exchange restriction, the response sets `narrowed_from_unrestricted` and the new allowlist contains only exchanges actually observed in the audit window, which narrows future reach; tell the buyer when that happens.

Run a traffic audit scan now

• Changes things

Request a supply-quality scan now rather than waiting for the nightly run. The scan reads provider reporting for a window of COMPLETE days only, never the partial current day, because provider click counts keep settling after delivery stops. Provider reporting is asynchronous, so a scan left in `running` continues on the platform cron and does not need to be re-requested.

List traffic audit scans

• Read only

List recent supply scan runs with their windows, row counts, finding deltas, and coverage caveats. Check `partial_coverage` before computing any share-of-spend figure from findings.

Set sprint budget policy

• Changes things
• Confirm first

Enable or disable testing sprints for this account and set the daily ceiling (total across all sprints, UTC day) and per-arm budget limits. Enabling adds a server-enforced ceiling and anti-circling rules around campaigns; every arm still passes the normal creative, destination and prepaid-balance gates.

Get sprint ledger

• Read only

READ THIS FIRST before proposing a sprint. Returns the policy, today's budget, the champion config the control must copy, open and closed variable families, every hypothesis already tested and its verdict, replicate_candidates ranked by pooled evidence with estimated spend to a verdict, supply_yield (human landings per dollar by exchange and environment: a hypothesis source for an exchange allowlist, never a verdict), eligible creatives, and the rules. Never re-propose a value that LOST.

Launch a testing sprint (spends money)

• Changes things
• Costs money
• Confirm first

Create and activate 2-4 NEW test campaigns (arms); this spends real money. The first sprint on an account must be an A/A (kind "aa", two identical arms). After that: one control equal to the champion, and challengers that each change exactly ONE variable family (use variable_family "mixed" with a per-arm variable_family to test several families around one shared control). A refusal carries a `guard` and is final for that idea. There is no campaign update verb; arms are only created new.

Get sprint

• Read only

Sprint and arms. Also advances a running sprint to spent_out from live spend and sets readout_due_at (at most 2 hours after spend-out for landing sprints, earlier once reporting has covered the hour after the last spend; 24 hours for conversion sprints).

Get sprint readout

• Read only

Per-arm spend, impressions, human (publisher-referred) landings with scanner traffic broken out, human landings by exchange, conversions for conversion sprints, and the first-party traffic grade. `ready` says whether the sprint can be closed yet.

Close a sprint

• Changes things
• Confirm first

Close a sprint whose readout is ready. The SERVER computes the verdict (WIN, LOSE, or INCONCLUSIVE) from pooled evidence; report the verdict it returns. The agent_summary may quote only dollar figures present in the readout.

Get my workspace access

• Read only

Read what THIS API key may do before acting. A key is bound to exactly ONE organization (returned as organization: account_id, name, role); to work in another organization, connect it separately and pick it on the consent screen. Returns account_id plus access: role (owner, admin, or member), scope (all_campaigns or team_campaigns), can_create_campaigns, can_manage_workspace, can_manage_billing, and the teams it holds seats on with read or edit permission. A member key only sees campaigns in its own teams; others return 404 rather than appearing in lists, and billing, webhooks, sprints, Supply Audit, and people management return 403. Call this first when a campaign you expect is missing or a call is refused, instead of retrying.

List teams

• Read only

List teams in this workspace with member_count, campaign_count, and my_permission (read or edit). Owner and admin keys see every live team. A member key sees only the teams it sits on, and only the campaigns in those teams anywhere in the API. Teams group campaigns for access; the wallet, creatives, targeting, and conversion events stay shared across the workspace.

Create a team

• Changes things

Create a named team (owner and admin keys only). Names are unique among live teams. A new team is empty: put campaigns in it with move_campaign_to_team or team_id on create_campaign / copy_campaign, and add people with invite_teammate.

List workspace members

• Read only

List everyone in this workspace: user_id, email, role (owner, admin, member), joined_at, last_login_at, and team seats with read or edit permission. Owner and admin keys only; a member key gets 403 and should use get_my_workspace_access to read its own seats.

Invite a teammate by email

• Changes things

Invite a person by email (owner and admin keys only). role member needs team_id and permission: read views the campaigns and reporting in that team; edit can also create, copy, activate, pause, and change creatives on them. role admin takes no team_id or permission, because admins see and manage every team, billing, and people. The API emails the invite; accepting needs a six-digit code sent to the invited address, so invite_url is safe to give the human but cannot be used to join without that inbox. If the email already belongs to this workspace, no invite is created and the person is seated on the team directly (added_existing_member: true). If email_sent is false, share invite_url.

Move a campaign to a team

• Changes things

Move one campaign to another team, or to unassigned with team_id null (unassigned is owner and admin keys only). Moving changes only who can see and edit the campaign. It never changes delivery, budgets, targeting, creatives, the exchange line item, or spend history. A member key needs edit on BOTH the current and the destination team, and cannot see unassigned campaigns or campaigns outside its teams (404).