Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview
On this page

AdCrunch API

Every AdCrunch API, in one document. Each API also publishes its own, at /openapi/<name>.json.

One origin serves the four, and the first segment of a path names the API. /observe reads the campaigns, the ads and the Insights of the ad accounts your organization connects. /mutations changes what runs on them. /context holds the Skills, Brands, Personas, Documents and Campaign Plans an organization writes down for its agents. /assets holds your images and videos, and places them in the library of an ad account.

One credential works on the four — see the security scheme.

The guide explains what these operations share: authentication, the failure shape, and the conventions for ids, money, time and pagination. It also describes three flows that span several operations: a change, an upload, and an edit that does not overwrite.

Start at https://docs.adcrunch.dev/api/introduction.

Version 1.0.0
Base URLhttps://api.pr-701.adcrunch.dev

Campaigns

The campaigns of your advertisers. Read every account of your organization at once, or one account on its own. A campaign is a campaign at every provider, so one listing spans them all.

Ad groups

The ad groups of your advertisers. One concept and three words: a Meta ad set, a TikTok ad group and a Google Ads ad group. Every row keeps the word its own provider writes, in type. Performance Max campaigns have no ad groups — read the asset groups instead.

Ads

The ads of your advertisers. An ad at Meta and TikTok; at Google Ads an ad_group_ad, the link resource whose id is the composite {adGroupId}~{adId}. Narrow by adGroupId for one ad group, or by campaignId for every ad of a campaign. Performance Max campaigns have no ads.

Creatives

The creatives of your advertisers: the image or video, the headline, the body copy and the call to action a provider assembles for an ad. A Creative is account-level, and Meta is the one provider that has one — TikTok embeds its creative material in the Ad itself, and Google Ads keeps its own on the ad_group_ad link resource. A Creative is not an Asset: an Asset is a source media file your organization owns.

Asset groups

The asset groups of your advertisers. Performance Max’s delivery container, and Google Ads only. A Performance Max campaign has no ad groups and no ads — the asset group holds what its automation assembles into placements. A child of a campaign and a sibling of an ad group.

Insights

Aggregated metrics for any level: advertiser, campaign, ad group or ad. The metrics include spend, impressions, clicks, reach and conversions. Group the rows into days, weeks or months, and break them down by provider, by advertiser or by entity type. A date range is required.

Mutations

Start a change on an advertiser, poll the one you started, and read the organization history.

Skills

Your organization’s ad-ops playbooks. List them, read one, or write one. The slug is the handle an agent uses.

Brands

Your organization’s brand context: identity, voice, guidelines and messaging, written as markdown. A list gives you the name, the description, the logo and which of the four sections carry prose. Read one Brand to get its narrative. The slug is the handle an agent uses.

Personas

The audiences a Brand speaks to, described as people. A Persona belongs to one Brand only, and you address it through that Brand. Its handle is thus the pair of slugs, and two Brands can each hold a loyalists. Two Brands that describe the same real person hold two Personas, and not one shared Persona.

Documents

Files attached to a Brand, such as a logo or a guidelines PDF. The bytes do not go through this API: reserve the upload, send the bytes to the URL you get back, then finalize. A Document is reference material that an agent reads. It never leaves AdCrunch, and this is what makes it different from an Asset.

Campaign Plans

What your organization intends to run, before it buys: on which channels, for whom, for how much, and over what period. A Campaign Plan is not a provider campaign. It belongs to AdCrunch, and it comes before any provider. The campaigns that a Campaign Plan later produces are in the Observe API. Write each amount in whole units of the currency of that Campaign Plan.

Line Items

The rows of a Campaign Plan. One Line Item is one thing you buy. It is coarser than an ad set: it holds the envelope of an intent, and it can produce more than one provider object. Therefore it holds only what is the same for all of them. A Line Item has no handle of its own. Address it through its Campaign Plan.

Assets

An organization’s source media. Reserve an upload, transfer the bytes directly to storage, then finalize — which is where what actually landed is validated.

Was this page helpful?