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-1099.adcrunch.dev

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.

Campaigns

The campaigns of your advertisers. Every provider calls a campaign campaign. This tag holds the live reads and the changes of one advertiser. For the stored list of every advertiser of your organization, see Stored reads. On Meta, you can also change the status, the name, the budget and the bidding of a campaign. You can also create a campaign or copy one. A change is asynchronous. The operation answers 202 and starts a Mutation. You poll the Mutation for its outcome.

Ad groups

The ad groups of your advertisers. The providers use different words for one concept. Meta calls it an ad set. TikTok and Google Ads call it an ad group. Each row keeps the word of its provider in type. A Performance Max campaign has no ad groups. Read its asset groups instead. This tag holds the live reads and the changes of one advertiser. For the stored list of every advertiser of your organization, see Stored reads. On Meta, you can also change the status, the name, the budget, the bidding and the schedule of an ad set. You can also create an ad set or copy one. A change is asynchronous. The operation answers 202 and starts a Mutation. You poll the Mutation for its outcome.

Ads

The ads of your advertisers. Meta and TikTok call it an ad. Google Ads calls it an ad_group_ad. That is a link resource, and its id is the composite {adGroupId}~{adId}. Filter by adGroupId for the ads of one ad group. Filter by campaignId for every ad of a campaign. A Performance Max campaign has no ads. This tag holds the live reads and the changes of one advertiser. For the stored list of every advertiser of your organization, see Stored reads. On Meta, you can also change the status and the name of an ad. You can also create an ad. A change is asynchronous. The operation answers 202 and starts a Mutation. You poll the Mutation for its outcome.

Creatives

The creatives of your advertisers. A provider assembles a creative for an ad: the image or video, the headline, the body copy and the call to action. A Creative belongs to the account. Meta is the only provider that has one. TikTok puts its creative material in the Ad itself. Google Ads keeps its creative material on the ad_group_ad link resource. A Creative is not an Asset. An Asset is a source media file that your organization owns. This tag holds the live reads and the changes of one advertiser. For the stored list of every advertiser of your organization, see Stored reads. On Meta, you can also create a creative from an Asset that you registered to the advertiser. A change is asynchronous. The operation answers 202 and starts a Mutation. You poll the Mutation for its outcome.

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.

Stored reads

The stored lists of campaigns, ad groups, ads, creatives and asset groups. A stored read answers from what the AdCrunch ingestion stored. It reads every advertiser of your organization in one request. Send advertiserId to read one advertiser. A stored read does not call the provider. To ask the provider now, use the live read under the tag of the resource.

Mutations

Poll a Mutation that you started, and read the organization history. The route of each change sits under the tag of the object that it changes, beside the reads of that object. POST /mutations is deprecated.

Skills

Your organization’s ad-ops playbooks. List them, read one, or write one. The slug is the handle an agent uses. You can also import a Catalog Skill from the Skill Catalog, the playbooks that AdCrunch writes, and re-import it when AdCrunch publishes a later version.

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?