--- seo: description: >- Every AdCrunch API, in one document. Each API also publishes its own, at /openapi/.json. sidebar: label: Overview title: AdCrunch API --- Every AdCrunch API, in one document. Each API also publishes its own, at `/openapi/.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 URL: `https://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. - [`GET /observe/insights`](/api/insights/list-insights) — List insights. ## 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. - [`GET /observe/{advertiserId}/campaigns`](/api/campaigns/list-advertiser-campaigns) — List an advertiser’s campaigns. - [`GET /observe/{advertiserId}/campaigns/{id}`](/api/campaigns/get-campaign) — Get one campaign. - [`POST /mutations/{advertiserId}/campaigns`](/api/campaigns/create-campaign) — Create a campaign. - [`PATCH /mutations/{advertiserId}/campaigns/{id}/status`](/api/campaigns/update-campaign-status) — Update a campaign’s status. - [`PATCH /mutations/{advertiserId}/campaigns/{id}/budget`](/api/campaigns/update-campaign-budget) — Update a campaign’s budget. - [`PATCH /mutations/{advertiserId}/campaigns/{id}/bidding`](/api/campaigns/update-campaign-bidding) — Update a campaign’s bidding. - [`PATCH /mutations/{advertiserId}/campaigns/{id}/name`](/api/campaigns/update-campaign-name) — Update a campaign’s name. - [`POST /mutations/{advertiserId}/campaigns/{id}/copies`](/api/campaigns/copy-campaign) — Copy a campaign. ## 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. - [`GET /observe/{advertiserId}/ad-groups`](/api/ad-groups/list-advertiser-ad-groups) — List an advertiser’s ad groups. - [`GET /observe/{advertiserId}/ad-groups/{id}`](/api/ad-groups/get-ad-group) — Get one ad group. - [`POST /mutations/{advertiserId}/ad-groups`](/api/ad-groups/create-ad-group) — Create an ad group. - [`PATCH /mutations/{advertiserId}/ad-groups/{id}/status`](/api/ad-groups/update-ad-group-status) — Update an ad group’s status. - [`PATCH /mutations/{advertiserId}/ad-groups/{id}/budget`](/api/ad-groups/update-ad-group-budget) — Update an ad group’s budget. - [`PATCH /mutations/{advertiserId}/ad-groups/{id}/schedule`](/api/ad-groups/update-ad-group-schedule) — Update an ad group’s schedule. - [`PATCH /mutations/{advertiserId}/ad-groups/{id}/bidding`](/api/ad-groups/update-ad-group-bidding) — Update an ad group’s bidding. - [`PATCH /mutations/{advertiserId}/ad-groups/{id}/name`](/api/ad-groups/update-ad-group-name) — Update an ad group’s name. - [`POST /mutations/{advertiserId}/ad-groups/{id}/copies`](/api/ad-groups/copy-ad-group) — Copy an ad group. ## 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. - [`GET /observe/{advertiserId}/ads`](/api/ads/list-advertiser-ads) — List an advertiser’s ads. - [`GET /observe/{advertiserId}/ads/{id}`](/api/ads/get-ad) — Get one ad. - [`POST /mutations/{advertiserId}/ads`](/api/ads/create-ad) — Create an ad. - [`PATCH /mutations/{advertiserId}/ads/{id}/status`](/api/ads/update-ad-status) — Update an ad’s status. - [`PATCH /mutations/{advertiserId}/ads/{id}/name`](/api/ads/update-ad-name) — Update an ad’s name. ## 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. - [`GET /observe/{advertiserId}/creatives`](/api/creatives/list-advertiser-creatives) — List an advertiser’s creatives. - [`GET /observe/{advertiserId}/creatives/{id}`](/api/creatives/get-creative) — Get one creative. - [`POST /mutations/{advertiserId}/creatives`](/api/creatives/create-creative) — Create a creative. ## 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. - [`GET /observe/{advertiserId}/asset-groups`](/api/asset-groups/list-advertiser-asset-groups) — List an advertiser’s asset groups. - [`GET /observe/{advertiserId}/asset-groups/{id}`](/api/asset-groups/get-asset-group) — Get one asset 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. - [`GET /observe/campaigns`](/api/stored-reads/list-campaigns) — List campaigns. - [`GET /observe/ad-groups`](/api/stored-reads/list-ad-groups) — List ad groups. - [`GET /observe/ads`](/api/stored-reads/list-ads) — List ads. - [`GET /observe/creatives`](/api/stored-reads/list-creatives) — List creatives. - [`GET /observe/asset-groups`](/api/stored-reads/list-asset-groups) — List asset groups. ## 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. - [`GET /mutations`](/api/mutations/list-mutations) — List mutations. - [`POST /mutations`](/api/mutations/start-mutation) — Start a mutation. Deprecated. - [`GET /mutations/{id}`](/api/mutations/get-mutation-status) — Read a mutation. ## 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. - [`GET /context/skills`](/api/skills/list-skills) — List the Skills. - [`POST /context/skills`](/api/skills/create-skill) — Create a Skill. - [`GET /context/skills/{slug}`](/api/skills/get-skill) — Get a Skill by slug. - [`DELETE /context/skills/{slug}`](/api/skills/delete-skill) — Delete a Skill. - [`PATCH /context/skills/{slug}`](/api/skills/update-skill) — Update a Skill. - [`POST /context/skills/{slug}/re-import`](/api/skills/reimport-skill) — Re-import a Skill. - [`GET /context/skill-catalog`](/api/skills/list-skill-catalog) — List the Skill Catalog. - [`POST /context/skill-catalog/{catalogSlug}/import`](/api/skills/import-catalog-skill) — Import a Catalog Skill. ## 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. - [`GET /context/brands`](/api/brands/list-brands) — List the Brands. - [`POST /context/brands`](/api/brands/create-brand) — Create a Brand. - [`GET /context/brands/{slug}`](/api/brands/get-brand) — Get a Brand by slug. - [`DELETE /context/brands/{slug}`](/api/brands/delete-brand) — Delete a Brand. - [`PATCH /context/brands/{slug}`](/api/brands/update-brand) — Update a Brand. - [`GET /context/brands/{slug}/advertisers`](/api/brands/list-brand-advertisers) — List a Brand's advertisers. - [`POST /context/brands/{slug}/advertisers`](/api/brands/attach-brand-advertiser) — Attach an advertiser. - [`DELETE /context/brands/{slug}/advertisers/{advertiserId}`](/api/brands/detach-brand-advertiser) — Detach an advertiser. ## 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. - [`GET /context/brands/{slug}/personas`](/api/personas/list-personas) — List a Brand's Personas. - [`POST /context/brands/{slug}/personas`](/api/personas/create-persona) — Create a Persona. - [`GET /context/brands/{slug}/personas/{personaSlug}`](/api/personas/get-persona) — Get a Persona. - [`DELETE /context/brands/{slug}/personas/{personaSlug}`](/api/personas/delete-persona) — Delete a Persona. - [`PATCH /context/brands/{slug}/personas/{personaSlug}`](/api/personas/update-persona) — Update a 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. - [`GET /context/brands/{slug}/documents`](/api/documents/list-brand-documents) — List a Brand's documents. - [`POST /context/brands/{slug}/documents`](/api/documents/create-brand-document-upload) — Start a document upload. - [`POST /context/brands/{slug}/documents/{documentId}/finalize`](/api/documents/finalize-brand-document) — Finalize a document upload. - [`GET /context/brands/{slug}/documents/{documentId}`](/api/documents/get-brand-document) — Get a document. - [`DELETE /context/brands/{slug}/documents/{documentId}`](/api/documents/delete-brand-document) — Delete a document. ## 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. - [`GET /context/campaign-plans`](/api/campaign-plans/list-campaign-plans) — List the Campaign Plans. - [`POST /context/campaign-plans`](/api/campaign-plans/create-campaign-plan) — Create a Campaign Plan. - [`GET /context/campaign-plans/{slug}`](/api/campaign-plans/get-campaign-plan) — Get a Campaign Plan. - [`DELETE /context/campaign-plans/{slug}`](/api/campaign-plans/delete-campaign-plan) — Delete a Campaign Plan. - [`PATCH /context/campaign-plans/{slug}`](/api/campaign-plans/update-campaign-plan) — Update a Campaign Plan. - [`POST /context/campaign-plans/{slug}/approve`](/api/campaign-plans/approve-campaign-plan) — Approve a 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. - [`POST /context/campaign-plans/{slug}/line-items`](/api/line-items/create-line-item) — Add a Line Item. - [`DELETE /context/campaign-plans/{slug}/line-items/{lineItemId}`](/api/line-items/delete-line-item) — Delete a Line Item. - [`PATCH /context/campaign-plans/{slug}/line-items/{lineItemId}`](/api/line-items/update-line-item) — Update a Line Item. - [`POST /context/campaign-plans/{slug}/line-items/{lineItemId}/validate`](/api/line-items/validate-line-item) — Validate a Line Item. - [`GET /context/campaign-plans/{slug}/line-items/{lineItemId}/readiness`](/api/line-items/get-line-item-execution-readiness) — Check a Line Item’s execution readiness. - [`POST /context/campaign-plans/{slug}/line-items/{lineItemId}/executions`](/api/line-items/record-line-item-execution) — Record what a Line Item spawned. ## 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. - [`GET /assets`](/api/assets/list-assets) — List the organization Assets. - [`POST /assets/uploads`](/api/assets/create-asset-upload) — Reserve an Asset and mint an upload URL. - [`POST /assets/{id}/finalize`](/api/assets/finalize-asset) — Finalize an uploaded Asset. - [`GET /assets/{id}`](/api/assets/get-asset) — Get one Asset. - [`DELETE /assets/{id}`](/api/assets/delete-asset) — Delete an Asset. - [`PATCH /assets/{id}`](/api/assets/rename-asset) — Rename an Asset. - [`POST /assets/{id}/registrations`](/api/assets/register-asset) — Register an Asset to an advertiser.