# 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-701.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-701.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-701.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-701.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-701.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-701.adcrunch.dev/console/advertisers): An advertiser is one ad account on one provider. Stable ID prefix acc_.
- [Performance](https://docs.pr-701.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-701.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-701.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-701.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-701.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-701.adcrunch.dev/mcp/overview): How the Model Context Protocol lets AI agents query AdCrunch in natural language.
- [Bring your own creative](https://docs.pr-701.adcrunch.dev/mcp/assets): Upload images and video you own, then register them into an advertiser's provider-side library — from your AI agent, over MCP.
- [Plan a campaign](https://docs.pr-701.adcrunch.dev/mcp/campaign-plans): Write down what you intend to run — channels, budgets, targeting, dates — as a structured Campaign Plan your agent can sum, approve, execute and record against.

### Set up your AI client

- [Claude Desktop](https://docs.pr-701.adcrunch.dev/mcp/setup/claude-desktop): Install the AdCrunch MCP server in Claude Desktop and authorize your organization.
- [Claude Code](https://docs.pr-701.adcrunch.dev/mcp/setup/claude-code): Install the AdCrunch MCP server in Claude Code and authorize your organization.
- [Cursor](https://docs.pr-701.adcrunch.dev/mcp/setup/cursor): Install the AdCrunch MCP server in Cursor and authorize your organization.
- [ChatGPT](https://docs.pr-701.adcrunch.dev/mcp/setup/chatgpt): Install AdCrunch as a custom MCP connector in ChatGPT.

### Auth and errors

- [Auth & scopes](https://docs.pr-701.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-701.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

- [list_advertisers](https://docs.pr-701.adcrunch.dev/mcp/tools/list-advertisers): List the advertisers (ad accounts) in your organization, optionally filtered by provider.
- [list_entities](https://docs.pr-701.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-701.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-701.adcrunch.dev/mcp/tools/query-insights): Aggregate spend / impressions / clicks / conversions over a date range, by entity.

#### Change what runs on Meta

- [get_mutation_status](https://docs.pr-701.adcrunch.dev/mcp/tools/get-mutation-status): Poll a change started by a write tool and find out whether it succeeded, failed, or is still running.

##### meta_*

- [meta_list_pages](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-list-pages): List the Facebook Pages a Meta ad account can advertise from.
- [meta_list_pixels](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-list-pixels): List the Meta Pixels installed on a Meta ad account.
- [meta_create_campaign](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-create-campaign): Create a Meta campaign from a conversation. It always arrives PAUSED.
- [meta_create_adset](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-create-adset): Create a Meta ad set under a campaign — budget, audience, and optimization goal.
- [meta_create_creative](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-create-creative): Build a Meta ad creative from media you uploaded to AdCrunch. Image and video both work.
- [meta_create_ad](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-create-ad): Create a Meta ad under an ad set, using a creative that already exists. Always paused.
- [meta_set_status](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-set-status): Pause, resume or archive a Meta campaign, ad set or ad on a live account. Runs asynchronously and returns a workflowId to poll.
- [meta_update_budget](https://docs.pr-701.adcrunch.dev/mcp/tools/meta-update-budget): Change a Meta campaign or ad set's daily or lifetime budget, with a safety cap and a level guardrail.

#### Plan a campaign

##### campaign_plan_*

- [campaign_plan_list](https://docs.pr-701.adcrunch.dev/mcp/tools/campaign-plan-list): List the campaign plans in your organization, with the money figures you would rank them by.
- [campaign_plan_get](https://docs.pr-701.adcrunch.dev/mcp/tools/campaign-plan-get): Fetch one campaign plan with its line items in full, the money figures, and whatever each line has already created.
- [campaign_plan_create](https://docs.pr-701.adcrunch.dev/mcp/tools/campaign-plan-create): Write down what you intend to run — on which channels, for whom, for how much, over what period.
- [campaign_plan_update](https://docs.pr-701.adcrunch.dev/mcp/tools/campaign-plan-update): Edit a campaign plan. Any real change returns an approved plan to draft.
- [campaign_plan_delete](https://docs.pr-701.adcrunch.dev/mcp/tools/campaign-plan-delete): Delete a campaign plan and its line items. What they already created is kept.
- [campaign_plan_approve](https://docs.pr-701.adcrunch.dev/mcp/tools/campaign-plan-approve): Approve a plan, validating every draft line on it and opening the execution gate.

##### line_item_*

- [line_item_create](https://docs.pr-701.adcrunch.dev/mcp/tools/line-item-create): Add a row to a campaign plan: one thing being bought, with the envelope of an intent.
- [line_item_update](https://docs.pr-701.adcrunch.dev/mcp/tools/line-item-update): Edit a line item. Any real change returns it to draft, and only it.
- [line_item_delete](https://docs.pr-701.adcrunch.dev/mcp/tools/line-item-delete): Remove a line item from a plan. What it already created is kept.
- [line_item_validate](https://docs.pr-701.adcrunch.dev/mcp/tools/line-item-validate): Validate one line item, which is what lets it be executed.
- [line_item_record_execution](https://docs.pr-701.adcrunch.dev/mcp/tools/line-item-record-execution): Record one provider object a line item created, so the plan knows what came from where.

#### Describe a brand

##### brand_*

- [brand_list](https://docs.pr-701.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-701.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-701.adcrunch.dev/mcp/tools/brand-resolve): Given an ad account, find which brands' context applies to it.
- [brand_create](https://docs.pr-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.adcrunch.dev/mcp/tools/document-delete): Delete a file attached to a brand, along with its stored bytes.

#### Bring your own creative

- [asset_list](https://docs.pr-701.adcrunch.dev/mcp/tools/asset-list): List the source media (images and video) your organization owns, each with where it has been registered.
- [asset_get](https://docs.pr-701.adcrunch.dev/mcp/tools/asset-get): Fetch one Asset with its Registrations — where it has been placed, and how each placement went. Also how you poll a running registration.
- [asset_create_upload](https://docs.pr-701.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-701.adcrunch.dev/mcp/tools/asset-finalize): Complete an upload after the bytes have been PUT, validate the file, and add the Asset to your library — optionally registering it in the same call.
- [asset_register](https://docs.pr-701.adcrunch.dev/mcp/tools/asset-register): Place an Asset in one advertiser's provider-side library so ads in that account can use it. Returns immediately; poll asset_get for readiness.

#### Reuse a playbook

- [skill_list](https://docs.pr-701.adcrunch.dev/mcp/tools/skill-list): List your organization's ad-ops playbooks (Skills) by slug, name, and description.
- [skill_get](https://docs.pr-701.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-701.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-701.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-701.adcrunch.dev/mcp/tools/skill-delete): Delete an ad-ops playbook (Skill), guarded by base_revision.

## AdCrunch API

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

### Start here

- [Introduction](https://docs.pr-701.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-701.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-701.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-701.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-701.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-701.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-701.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-701.adcrunch.dev/api/insights/list-insights)

### Campaigns

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

### Ad groups

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

### Ads

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

### Creatives

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

### Asset groups

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

### Mutations

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

### Skills

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

### Brands

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

### Personas

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

### Documents

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

### Campaign Plans

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

### Line Items

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

### Assets

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

## Agent resources

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