# AdCrunch Docs

> Documentation for AdCrunch — connect your ad platforms to AI agents and query campaigns in natural language.

## Docs

- [Welcome to AdCrunch](https://docs.pr-733.adcrunch.dev/): The documentation of AdCrunch. Connect Meta, TikTok and Google Ads to Claude, ChatGPT, Cursor, the console, or the REST API. Read your campaigns, and change what runs.

## Start here

- [Quickstart](https://docs.pr-733.adcrunch.dev/quickstart): Connect Meta, TikTok and Google Ads once. Read live campaign performance and change what is running — from Claude, Cursor, ChatGPT, the console, or the REST API.
- [Concepts](https://docs.pr-733.adcrunch.dev/concepts): Every noun AdCrunch uses, defined once — organization, advertiser, entity, insight, mutation, and the things you write down for an agent to read.

## Connect a provider

- [What each provider supports](https://docs.pr-733.adcrunch.dev/connect/providers): One table for every ad platform AdCrunch connects to — what it reads, what it can change, what you pass as the API value, and where each capability stops.
- [Connect Meta](https://docs.pr-733.adcrunch.dev/connect/meta): Authorize AdCrunch on a Meta ad account and pick which advertisers to sync.

## Work in the console

- [Advertisers](https://docs.pr-733.adcrunch.dev/console/advertisers): An advertiser is one ad account on one provider. Stable ID prefix acc_.
- [Performance](https://docs.pr-733.adcrunch.dev/console/insights): Read spend, clicks and conversions across every connected ad account on one page, grouped by the level you choose and converted into one currency.
- [Skills](https://docs.pr-733.adcrunch.dev/console/skills): Ad-ops playbooks your connected AI agents can run via the AdCrunch MCP server. Manage them in the console.
- [Brands](https://docs.pr-733.adcrunch.dev/console/brands): The context your agents read before they write anything — identity, voice, guidelines, messaging — plus the website, files, logo and ad accounts that go with it.

## Account

- [API keys](https://docs.pr-733.adcrunch.dev/account/api-keys): Create a key to call the AdCrunch REST API from your own code, understand whose permissions it uses and when it stops working, and revoke it.

## Connect to AI agents

- [Connect to AI agents](https://docs.pr-733.adcrunch.dev/mcp): Wire AdCrunch into Claude, Cursor, and ChatGPT via the MCP server. One page for each tool, and the boundary an agent works inside.

### Overview

- [What is MCP](https://docs.pr-733.adcrunch.dev/mcp/overview): How the Model Context Protocol lets AI agents query AdCrunch in natural language.

### Set up your AI client

- [Claude](https://docs.pr-733.adcrunch.dev/mcp/setup/claude-desktop): Add AdCrunch to Claude as a custom connector, on claude.ai, Claude Desktop, and the mobile apps.
- [Claude Code](https://docs.pr-733.adcrunch.dev/mcp/setup/claude-code): Install the AdCrunch MCP server in Claude Code and authorize your organization.
- [Cursor](https://docs.pr-733.adcrunch.dev/mcp/setup/cursor): Install the AdCrunch MCP server in Cursor and authorize your organization.
- [ChatGPT](https://docs.pr-733.adcrunch.dev/mcp/setup/chatgpt): Add AdCrunch to ChatGPT as an app in developer mode.

### Auth and errors

- [Auth & scopes](https://docs.pr-733.adcrunch.dev/mcp/auth): How OAuth works for the MCP server, what each scope grants, what an agent can and cannot change, and how access is revoked.
- [Errors](https://docs.pr-733.adcrunch.dev/mcp/errors): The one shape every AdCrunch failure arrives in, every status code you can meet, what is safe to retry, and how the same failure reaches an MCP client.

### Tools

#### Read your accounts

- [Read your accounts](https://docs.pr-733.adcrunch.dev/mcp/tools/read-your-accounts): Ask an AI agent which ad accounts you have, what runs in them, and what they spend and return. The agent reads what AdCrunch stores, and it changes nothing.
- [list_advertisers](https://docs.pr-733.adcrunch.dev/mcp/tools/list-advertisers): List the advertisers (ad accounts) in your organization, optionally filtered by provider.
- [list_entities](https://docs.pr-733.adcrunch.dev/mcp/tools/list-entities): List ad entities (campaigns, ad sets, ad groups, ads, creatives, …) under one advertiser, filtered by type or parent.
- [get_entity](https://docs.pr-733.adcrunch.dev/mcp/tools/get-entity): Fetch the full raw provider payload for one ad entity by provider, type, and id.
- [query_insights](https://docs.pr-733.adcrunch.dev/mcp/tools/query-insights): Aggregate spend / impressions / clicks / conversions over a date range, by entity.

#### Change what runs on Meta

- [Change what runs on Meta](https://docs.pr-733.adcrunch.dev/mcp/tools/change-what-runs-on-meta): Build a paused campaign on a Meta advertiser, then start it, stop it, or change its budget, from a conversation. Each change runs in the background, and nothing spends until you activate it.
- [get_mutation_status](https://docs.pr-733.adcrunch.dev/mcp/tools/get-mutation-status): Find out how a change on Meta ended, after a write tool started it.

##### meta_*

- [meta_list_pages](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-list-pages): List the Facebook Pages that your Meta connection can advertise from.
- [meta_list_pixels](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-list-pixels): List the Meta Pixels installed on a Meta advertiser.
- [meta_create_campaign](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-create-campaign): Create a Meta campaign from a conversation. It always arrives paused.
- [meta_create_adset](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-create-adset): Create a Meta ad set under a campaign, with its audience and its optimization goal. It always arrives paused.
- [meta_create_creative](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-create-creative): Build a Meta ad creative from an asset that you uploaded to AdCrunch. Image and video both work.
- [meta_create_ad](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-create-ad): Create a Meta ad under an ad set, with a creative that already exists. It always arrives paused.
- [meta_set_status](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-set-status): Pause, resume or archive a Meta campaign, ad set or ad.
- [meta_update_budget](https://docs.pr-733.adcrunch.dev/mcp/tools/meta-update-budget): Change the daily or lifetime budget of a Meta campaign or ad set, with a safety cap and a level check.

#### Plan a campaign

- [Plan a campaign](https://docs.pr-733.adcrunch.dev/mcp/tools/plan-a-campaign): Ask your agent to write down what you intend to run, approve it, build it on Meta, and record what it created.

##### campaign_plan_*

- [campaign_plan_list](https://docs.pr-733.adcrunch.dev/mcp/tools/campaign-plan-list): List the Campaign Plans of your organization, with the money figures that you rank them by.
- [campaign_plan_get](https://docs.pr-733.adcrunch.dev/mcp/tools/campaign-plan-get): Get one Campaign Plan with each Line Item in full, the money figures, and what each Line Item created.
- [campaign_plan_create](https://docs.pr-733.adcrunch.dev/mcp/tools/campaign-plan-create): Write down what you intend to run: the channels, the audience, the money and the dates.
- [campaign_plan_update](https://docs.pr-733.adcrunch.dev/mcp/tools/campaign-plan-update): Edit a Campaign Plan. A real change returns an approved Campaign Plan to draft.
- [campaign_plan_delete](https://docs.pr-733.adcrunch.dev/mcp/tools/campaign-plan-delete): Delete a Campaign Plan and its Line Items. What they created stays live.
- [campaign_plan_approve](https://docs.pr-733.adcrunch.dev/mcp/tools/campaign-plan-approve): Approve a Campaign Plan and validate each draft Line Item on it.

##### line_item_*

- [line_item_create](https://docs.pr-733.adcrunch.dev/mcp/tools/line-item-create): Add a Line Item to a Campaign Plan: one thing that you buy, with the limits of an intent.
- [line_item_update](https://docs.pr-733.adcrunch.dev/mcp/tools/line-item-update): Edit a Line Item. A real change returns that Line Item to draft, and no other.
- [line_item_delete](https://docs.pr-733.adcrunch.dev/mcp/tools/line-item-delete): Remove a Line Item from a Campaign Plan. What it created stays live.
- [line_item_validate](https://docs.pr-733.adcrunch.dev/mcp/tools/line-item-validate): Validate one Line Item, so that the agent can build it.
- [line_item_record_execution](https://docs.pr-733.adcrunch.dev/mcp/tools/line-item-record-execution): Record one provider object that a Line Item created, so that the Campaign Plan shows what came from where.

#### Describe a brand

##### brand_*

- [brand_list](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-list): List your organization's brands as slug + name + description, so an agent can pick one before loading its context.
- [brand_get](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-get): Fetch one brand by slug — its identity, voice, guidelines, messaging and personas — so an agent knows who it is acting for.
- [brand_resolve](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-resolve): Given an ad account, find which brands' context applies to it.
- [brand_create](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-create): Create a brand in your organization. Every context section is optional — start with a name and fill it in over time.
- [brand_update](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-update): Edit a brand's context, guarded by base_revision so a concurrent change can't be silently overwritten.
- [brand_attach_advertiser](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-attach-advertiser): Attach an ad account to a brand, so agents can resolve brand context from the account.
- [brand_detach_advertiser](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-detach-advertiser): Remove the link between an ad account and a brand, leaving the brand and its context untouched.
- [brand_delete](https://docs.pr-733.adcrunch.dev/mcp/tools/brand-delete): Delete a brand and the context authored on it, guarded by base_revision.

##### persona_*

- [persona_get](https://docs.pr-733.adcrunch.dev/mcp/tools/persona-get): Fetch one of a brand's personas — who it is talking to, in their own words — so an agent can write for someone in particular.
- [persona_create](https://docs.pr-733.adcrunch.dev/mcp/tools/persona-create): Add an audience archetype to a brand — who it is talking to — with as much or as little written up front as you have.
- [persona_update](https://docs.pr-733.adcrunch.dev/mcp/tools/persona-update): Edit a persona's sections, age range or handle, guarded against overwriting someone else's concurrent change.
- [persona_delete](https://docs.pr-733.adcrunch.dev/mcp/tools/persona-delete): Remove a persona from a brand, guarded against deleting something someone else has since edited.

##### document_*

- [document_create_upload](https://docs.pr-733.adcrunch.dev/mcp/tools/document-create-upload): Reserve a file against a brand and get a short-lived URL to upload the bytes to.
- [document_finalize](https://docs.pr-733.adcrunch.dev/mcp/tools/document-finalize): Complete a document upload once the bytes have landed — size and type are read from the stored file, not from what you declared.
- [document_get](https://docs.pr-733.adcrunch.dev/mcp/tools/document-get): Fetch one brand document — images come back as an image the assistant can actually look at.
- [document_list](https://docs.pr-733.adcrunch.dev/mcp/tools/document-list): List the files attached to a brand, each with a URL you can fetch.
- [document_delete](https://docs.pr-733.adcrunch.dev/mcp/tools/document-delete): Delete a file attached to a brand, along with its stored bytes.

#### Bring your own creative

- [Bring your own creative](https://docs.pr-733.adcrunch.dev/mcp/tools/bring-your-own-creative): Upload an image or a video that you own, and register it into the provider library of one advertiser, so that an ad there can use it. All from your AI client.
- [asset_list](https://docs.pr-733.adcrunch.dev/mcp/tools/asset-list): List the images and videos that your organization owns as Assets, each with its Registrations.
- [asset_get](https://docs.pr-733.adcrunch.dev/mcp/tools/asset-get): Fetch one Asset with its Registrations, and the state of each one. The agent polls a running Registration with this tool.
- [asset_create_upload](https://docs.pr-733.adcrunch.dev/mcp/tools/asset-create-upload): Reserve an Asset and get a short-lived URL to upload the file to. Step one of bringing your own creative in.
- [asset_finalize](https://docs.pr-733.adcrunch.dev/mcp/tools/asset-finalize): Complete an upload after the file arrives. AdCrunch checks the file and makes it a ready Asset, and it can start a Registration in the same call.
- [asset_register](https://docs.pr-733.adcrunch.dev/mcp/tools/asset-register): Register an Asset into the provider library of one advertiser, so that an ad of that advertiser can use it. The call returns at once, and asset_get gives the state.

#### Reuse a playbook

- [skill_list](https://docs.pr-733.adcrunch.dev/mcp/tools/skill-list): List your organization's ad-ops playbooks (Skills) by slug, name, and description.
- [skill_get](https://docs.pr-733.adcrunch.dev/mcp/tools/skill-get): Fetch one ad-ops playbook (Skill) by slug, including its full instructions and current revision.
- [skill_create](https://docs.pr-733.adcrunch.dev/mcp/tools/skill-create): Create a new ad-ops playbook (Skill) in your organization from an agent session.
- [skill_update](https://docs.pr-733.adcrunch.dev/mcp/tools/skill-update): Update an ad-ops playbook (Skill), guarded by base_revision so concurrent edits aren't clobbered.
- [skill_delete](https://docs.pr-733.adcrunch.dev/mcp/tools/skill-delete): Delete an ad-ops playbook (Skill), guarded by base_revision.

## AdCrunch API

- [AdCrunch API](https://docs.pr-733.adcrunch.dev/api)

### Start here

- [Introduction](https://docs.pr-733.adcrunch.dev/api/introduction): What the AdCrunch REST API does, when to use it instead of MCP, and how to make your first request with an API key.
- [Authentication](https://docs.pr-733.adcrunch.dev/api/authentication): Send an API key as a bearer token, learn which organization and which permissions it carries, and see which permission each AdCrunch API needs.
- [Errors](https://docs.pr-733.adcrunch.dev/api/errors): The one shape of an AdCrunch failure, the field to branch on, the order of the checks, and the codes that more than one operation sends.
- [Conventions](https://docs.pr-733.adcrunch.dev/api/conventions): The rules that cross the AdCrunch APIs — ids, provider values, money, time, casing, paths, and pagination — including the places where the APIs do not agree yet.

### Workflows

- [Make a change](https://docs.pr-733.adcrunch.dev/api/make-a-change): Change what runs on an advertiser with the Mutations API — start a Mutation, poll it until it ends, and read the history of each change.
- [Upload a file](https://docs.pr-733.adcrunch.dev/api/upload-a-file): Upload an image or a video as an Asset, or a file as a Brand Document, in three steps. Then register an Asset in the library of an advertiser.
- [Edit without overwriting](https://docs.pr-733.adcrunch.dev/api/edit-without-overwriting): Change a Skill, a Brand, a Persona, a Campaign Plan, or a Line Item without overwriting an edit that somebody else made after you read it.

### Insights

- [Stored read: List insights](https://docs.pr-733.adcrunch.dev/api/insights/list-insights)

### Campaigns

- [Live read: Get one campaign](https://docs.pr-733.adcrunch.dev/api/campaigns/get-campaign)
- [Live read: List an advertiser’s campaigns](https://docs.pr-733.adcrunch.dev/api/campaigns/list-advertiser-campaigns)
- [Stored read: List campaigns](https://docs.pr-733.adcrunch.dev/api/campaigns/list-campaigns)

### Ad groups

- [Live read: Get one ad group](https://docs.pr-733.adcrunch.dev/api/ad-groups/get-ad-group)
- [Live read: List an advertiser’s ad groups](https://docs.pr-733.adcrunch.dev/api/ad-groups/list-advertiser-ad-groups)
- [Stored read: List ad groups](https://docs.pr-733.adcrunch.dev/api/ad-groups/list-ad-groups)

### Ads

- [Live read: Get one ad](https://docs.pr-733.adcrunch.dev/api/ads/get-ad)
- [Live read: List an advertiser’s ads](https://docs.pr-733.adcrunch.dev/api/ads/list-advertiser-ads)
- [Stored read: List ads](https://docs.pr-733.adcrunch.dev/api/ads/list-ads)

### Creatives

- [Live read: Get one creative](https://docs.pr-733.adcrunch.dev/api/creatives/get-creative)
- [Live read: List an advertiser’s creatives](https://docs.pr-733.adcrunch.dev/api/creatives/list-advertiser-creatives)
- [Stored read: List creatives](https://docs.pr-733.adcrunch.dev/api/creatives/list-creatives)

### Asset groups

- [Live read: Get one asset group](https://docs.pr-733.adcrunch.dev/api/asset-groups/get-asset-group)
- [Live read: List an advertiser’s asset groups](https://docs.pr-733.adcrunch.dev/api/asset-groups/list-advertiser-asset-groups)
- [Stored read: List asset groups](https://docs.pr-733.adcrunch.dev/api/asset-groups/list-asset-groups)

### Mutations

- [List mutations](https://docs.pr-733.adcrunch.dev/api/mutations/list-mutations)
- [Read a mutation](https://docs.pr-733.adcrunch.dev/api/mutations/get-mutation-status)
- [Start a mutation](https://docs.pr-733.adcrunch.dev/api/mutations/start-mutation)

### Skills

- [Create a Skill](https://docs.pr-733.adcrunch.dev/api/skills/create-skill)
- [Delete a Skill](https://docs.pr-733.adcrunch.dev/api/skills/delete-skill)
- [Get a Skill by slug](https://docs.pr-733.adcrunch.dev/api/skills/get-skill)
- [List the Skills](https://docs.pr-733.adcrunch.dev/api/skills/list-skills)
- [Update a Skill](https://docs.pr-733.adcrunch.dev/api/skills/update-skill)

### Brands

- [Attach an advertiser](https://docs.pr-733.adcrunch.dev/api/brands/attach-brand-advertiser)
- [Create a Brand](https://docs.pr-733.adcrunch.dev/api/brands/create-brand)
- [Delete a Brand](https://docs.pr-733.adcrunch.dev/api/brands/delete-brand)
- [Detach an advertiser](https://docs.pr-733.adcrunch.dev/api/brands/detach-brand-advertiser)
- [Get a Brand by slug](https://docs.pr-733.adcrunch.dev/api/brands/get-brand)
- [List a Brand's advertisers](https://docs.pr-733.adcrunch.dev/api/brands/list-brand-advertisers)
- [List the Brands](https://docs.pr-733.adcrunch.dev/api/brands/list-brands)
- [Update a Brand](https://docs.pr-733.adcrunch.dev/api/brands/update-brand)

### Personas

- [Create a Persona](https://docs.pr-733.adcrunch.dev/api/personas/create-persona)
- [Delete a Persona](https://docs.pr-733.adcrunch.dev/api/personas/delete-persona)
- [Get a Persona](https://docs.pr-733.adcrunch.dev/api/personas/get-persona)
- [List a Brand's Personas](https://docs.pr-733.adcrunch.dev/api/personas/list-personas)
- [Update a Persona](https://docs.pr-733.adcrunch.dev/api/personas/update-persona)

### Documents

- [Delete a document](https://docs.pr-733.adcrunch.dev/api/documents/delete-brand-document)
- [Finalize a document upload](https://docs.pr-733.adcrunch.dev/api/documents/finalize-brand-document)
- [Get a document](https://docs.pr-733.adcrunch.dev/api/documents/get-brand-document)
- [List a Brand's documents](https://docs.pr-733.adcrunch.dev/api/documents/list-brand-documents)
- [Start a document upload](https://docs.pr-733.adcrunch.dev/api/documents/create-brand-document-upload)

### Campaign Plans

- [Approve a Campaign Plan](https://docs.pr-733.adcrunch.dev/api/campaign-plans/approve-campaign-plan)
- [Create a Campaign Plan](https://docs.pr-733.adcrunch.dev/api/campaign-plans/create-campaign-plan)
- [Delete a Campaign Plan](https://docs.pr-733.adcrunch.dev/api/campaign-plans/delete-campaign-plan)
- [Get a Campaign Plan](https://docs.pr-733.adcrunch.dev/api/campaign-plans/get-campaign-plan)
- [List the Campaign Plans](https://docs.pr-733.adcrunch.dev/api/campaign-plans/list-campaign-plans)
- [Update a Campaign Plan](https://docs.pr-733.adcrunch.dev/api/campaign-plans/update-campaign-plan)

### Line Items

- [Add a Line Item](https://docs.pr-733.adcrunch.dev/api/line-items/create-line-item)
- [Check a Line Item’s execution readiness](https://docs.pr-733.adcrunch.dev/api/line-items/get-line-item-execution-readiness)
- [Delete a Line Item](https://docs.pr-733.adcrunch.dev/api/line-items/delete-line-item)
- [Record what a Line Item spawned](https://docs.pr-733.adcrunch.dev/api/line-items/record-line-item-execution)
- [Update a Line Item](https://docs.pr-733.adcrunch.dev/api/line-items/update-line-item)
- [Validate a Line Item](https://docs.pr-733.adcrunch.dev/api/line-items/validate-line-item)

### Assets

- [Delete an Asset](https://docs.pr-733.adcrunch.dev/api/assets/delete-asset)
- [Finalize an uploaded Asset](https://docs.pr-733.adcrunch.dev/api/assets/finalize-asset)
- [Get one Asset](https://docs.pr-733.adcrunch.dev/api/assets/get-asset)
- [List the organization Assets](https://docs.pr-733.adcrunch.dev/api/assets/list-assets)
- [Register an Asset to an advertiser](https://docs.pr-733.adcrunch.dev/api/assets/register-asset)
- [Rename an Asset](https://docs.pr-733.adcrunch.dev/api/assets/rename-asset)
- [Reserve an Asset and mint an upload URL](https://docs.pr-733.adcrunch.dev/api/assets/create-asset-upload)

## Agent resources

- [llms-full.txt](https://docs.pr-733.adcrunch.dev/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://docs.pr-733.adcrunch.dev/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [API catalog](https://docs.pr-733.adcrunch.dev/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [agent-readability.json](https://docs.pr-733.adcrunch.dev/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://docs.pr-733.adcrunch.dev/sitemap.xml): Every indexable page URL with its last-modified date.