--- 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-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. - [`GET /observe/campaigns`](/api/campaigns/list-campaigns) — Stored read: List campaigns - [`GET /observe/{advertiserId}/campaigns`](/api/campaigns/list-advertiser-campaigns) — Live read: List an advertiser’s campaigns - [`GET /observe/{advertiserId}/campaigns/{id}`](/api/campaigns/get-campaign) — Live read: Get one campaign ## 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. - [`GET /observe/ad-groups`](/api/ad-groups/list-ad-groups) — Stored read: List ad groups - [`GET /observe/{advertiserId}/ad-groups`](/api/ad-groups/list-advertiser-ad-groups) — Live read: List an advertiser’s ad groups - [`GET /observe/{advertiserId}/ad-groups/{id}`](/api/ad-groups/get-ad-group) — Live read: Get one ad group ## 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. - [`GET /observe/ads`](/api/ads/list-ads) — Stored read: List ads - [`GET /observe/{advertiserId}/ads`](/api/ads/list-advertiser-ads) — Live read: List an advertiser’s ads - [`GET /observe/{advertiserId}/ads/{id}`](/api/ads/get-ad) — Live read: Get one ad ## 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. - [`GET /observe/creatives`](/api/creatives/list-creatives) — Stored read: List creatives - [`GET /observe/{advertiserId}/creatives`](/api/creatives/list-advertiser-creatives) — Live read: List an advertiser’s creatives - [`GET /observe/{advertiserId}/creatives/{id}`](/api/creatives/get-creative) — Live read: Get one 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/asset-groups`](/api/asset-groups/list-asset-groups) — Stored read: List asset groups - [`GET /observe/{advertiserId}/asset-groups`](/api/asset-groups/list-advertiser-asset-groups) — Live read: List an advertiser’s asset groups - [`GET /observe/{advertiserId}/asset-groups/{id}`](/api/asset-groups/get-asset-group) — Live read: Get one asset 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. - [`GET /observe/insights`](/api/insights/list-insights) — Stored read: List insights ## Mutations Start a change on an advertiser, poll the one you started, and read the organization history. - [`GET /mutations`](/api/mutations/list-mutations) — List mutations - [`POST /mutations`](/api/mutations/start-mutation) — Start a mutation - [`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. - [`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 ## 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