# Semicola

> Docs for Semicola: buy media from every seller with one agent, sell through a storefront agent, and build on the v3 MCP endpoint.

Semicola is an ad gateway built on AdCP over MCP. Buyers send one brief to many media sellers; sellers answer through a storefront agent that works inside their own rules. Agents connect to one account-resolved MCP endpoint: https://api.semicola.com/mcp/v3 (OAuth 2.1 with PKCE, or an API key).

Each link below is the markdown version of a documentation page. Call `tools/list` on the MCP endpoint for the live tool contract; the v3 Tool Catalog page documents the same tools.

## Use Semicola

### Start here

- [Introduction](https://docs.semicola.com/index.md): Brief once. Reach every seller. Let agents do the legwork.

### Setup

- [Semi confirmations](https://docs.semicola.com/setup/semi-confirmations.md): How Semi asks for explicit approval before a durable write, and how a client renders, approves or cancels it.

### Buy media

- [One agent. Every seller. Every channel.](https://docs.semicola.com/buy/overview.md): How buying works on Semicola: one brief, many sellers, one confirmed launch.

#### Getting started

- [Buyer onboarding](https://docs.semicola.com/buy/onboarding.md): From a new buyer account to a first sandbox campaign: the steps, and what each one unlocks.
- [Ask Semi](https://docs.semicola.com/buy/ask-semi.md): Use the assistant to plan campaigns, get proposals, manage creatives and read delivery in conversation, with attachments, stopping, usage and your requests.

#### Advertisers

- [Advertiser](https://docs.semicola.com/buy/advertiser.md): The brand you buy for: identity, currency, markets, and the defaults every campaign inherits.
- [Dimensions and labels](https://docs.semicola.com/buy/dimensions-and-labels.md): Organize advertisers and campaigns with buyer-owned dimensions and labels, filter by them, and group delivery by a label.
- [Property lists and audiences](https://docs.semicola.com/buy/property-lists.md): Include and exclude lists of websites, apps and CTV apps, and first-party audiences, for an advertiser

#### Campaigns

- [Campaign](https://docs.semicola.com/buy/campaign.md): The unit of media planning: a brief, a flight, a budget, and the media buys that carry them out.
- [Autonomy and auto-select](https://docs.semicola.com/buy/autonomy-settings.md): Choose per campaign whether you stage products yourself or let Semicola select them, and run auto-select on a draft campaign.
- [Media buys and packages](https://docs.semicola.com/buy/media-buys-and-packages.md): Stage, launch, change and pause the per-seller buys under a campaign, and the packages inside them.
- [Channel groups](https://docs.semicola.com/buy/channel-groups.md): Express composite inventory intent on a campaign, compile it into separate media buys, and report by the same grouping.
- [Targeting](https://docs.semicola.com/buy/targeting.md): Record campaign targeting intent, set campaign constraints, and change a package targeting overlay on a live buy.
- [Update proposals](https://docs.semicola.com/buy/update-proposals.md): Poll and cancel a pending change to a live media buy while its seller decides.

#### Product discovery

- [Product discovery](https://docs.semicola.com/buy/product-discovery.md): Send one brief to every eligible seller, compare their proposals, refine, and stage the ones you want.

#### Creatives

- [Creatives](https://docs.semicola.com/buy/creatives.md): Build creatives in the composer or bring your own, attach them to campaigns, and see how sellers review them.
- [Catalogs](https://docs.semicola.com/buy/catalogs.md): Product, job, store and offer feeds: supported formats, versions, transforms and activation.

#### Reporting & activity

- [Reporting & activity](https://docs.semicola.com/buy/reporting.md): Read delivery by advertiser, campaign, media buy and package, and see who did what.
- [Event sources](https://docs.semicola.com/buy/event-sources.md): Register where an advertiser’s conversions come from, send conversion events server-to-server, and check source health.

#### Connections

- [Connections](https://docs.semicola.com/buy/connections.md): Choose which sellers receive your briefs, activate them per advertiser, and test safely in sandbox.
- [Syndication](https://docs.semicola.com/buy/syndication.md): Share an audience, event source or catalog with chosen ADCP agents ahead of any buy, and check each share.
- [Webhooks](https://docs.semicola.com/buy/webhooks.md): Register a webhook to receive discovery revisions as push events instead of polling.

#### Account & billing

- [How IU billing works](https://docs.semicola.com/buy/billing.md): What an Intelligence Unit pays for, what stays free, the plans, and a calculator for your month.

### Sell media

- [One storefront. Every buyer. Every channel.](https://docs.semicola.com/sell/overview.md): How selling works on Semicola: a storefront, a storefront agent, and rules you write.

#### Getting started

- [Storefront onboarding](https://docs.semicola.com/sell/onboarding.md): From a new seller account to a storefront that can transact: the readiness checklist, step by step.
- [Publisher example pack](https://docs.semicola.com/sell/publisher-example-pack.md): A fictional publisher's merchandising files and test briefs, so you can rehearse storefront setup before you send real material.
- [Complete campaign example](https://docs.semicola.com/sell/complete-campaign-example.md): A fictional campaign traced through discovery, policy, booking, creative, changes and reporting, with an honest verdict on what each stage proves today.
- [What you need for a GAM pilot](https://docs.semicola.com/sell/gam-pilot.md): The short checklist for piloting a publisher storefront connected to Google Ad Manager, and which parts Semicola can run today.

#### Operating your storefront

- [Ask Semi](https://docs.semicola.com/sell/ask-semi.md): Use the assistant to set up, merchandise and operate your storefront in conversation.
- [Listing](https://docs.semicola.com/sell/listing.md): How buyers see your storefront: identity from your brand domain, what you do, the marketplace switch, public distribution, and the destinations your listing reaches.
- [RFP lifecycle](https://docs.semicola.com/sell/rfp-lifecycle.md): Create a seller RFP, poll its turns, revise, grade and endorse responses, render them, and measure RFP performance.
- [Products](https://docs.semicola.com/sell/products.md): What your storefront sells: channels, formats, delivery type and priced options with floors.
- [Playbook](https://docs.semicola.com/sell/playbook.md): Tell your storefront agent how to pitch, package and price, including the floors it may never cross.
- [Operating instructions and policy versions](https://docs.semicola.com/sell/operating-instructions.md): The versioned playbook instructions and acceptance policy your storefront agent applies, and how to read, create and reactivate versions.
- [House discounts and buyer instructions](https://docs.semicola.com/sell/buyer-discounts.md): Give a buyer brand or operator a negotiated discount, notes or country limits that your storefront agent applies when it composes proposals.
- [Library](https://docs.semicola.com/sell/library.md): Teach your storefront agent from media kits, rate cards, decks, past RFPs and notes.
- [AI Business Rules](https://docs.semicola.com/sell/ai-business-rules.md): Write what your storefront accepts, choose when a person reviews, and see how your agent applies both.
- [Signals](https://docs.semicola.com/sell/signals.md): Record the audience, contextual and geographic segments your inventory can deliver against, starting from suggestions drawn from your catalog.
- [Buyers](https://docs.semicola.com/sell/sponsored-buyers.md): See every buyer account that transacts with your storefront, and approve, suspend or reactivate it.

#### Inventory sources

- [Inventory sources](https://docs.semicola.com/sell/inventory-sources.md): Connect the AdCP sales agent or ad server that actually delivers your inventory.
- [Modular sources](https://docs.semicola.com/sell/modular-sources.md): Sell inventory from an avails spreadsheet or export: create a modular source, check its readiness, then preview and commit static-avails-feed:v1 rows that become products.
- [Wholesale avails & pricing](https://docs.semicola.com/sell/wholesale-pricing.md): Fill wholesale pricing and availability gaps by uploading a percentile-CPM feed keyed on your ad-server selectors

#### Approvals & reviews

- [Approvals & reviews](https://docs.semicola.com/sell/approvals.md): Review media buys and creatives before they reach your inventory, with an advisory verdict on each.
- [Creative reviews](https://docs.semicola.com/sell/creative-reviews.md): Review the queue of buyer-submitted creatives and approve or reject the pending ones.
- [Media buys on your storefront](https://docs.semicola.com/sell/media-buys.md): Every buy placed on your storefront, most urgent first, with its timeline, delivery and the way to re-send a failed forward.

#### Analytics & activity

- [Seller analytics](https://docs.semicola.com/sell/analytics.md): How your storefront agent is performing: win rate, grades, response and acceptance rates, and delivery.
- [Demand inbox & proposal pass](https://docs.semicola.com/sell/demand-inbox.md): The ledger of every brief your storefront answered, and the full record of each answer.

### Guides

- [Using the app](https://docs.semicola.com/guides/the-app.md): Find your way around the Semicola app: the account switcher, the chat home, the rail, settings, API keys, advertisers and members.
- [Accounts and organizations](https://docs.semicola.com/guides/accounts.md): Your current account, the accounts under your organization, adding and deleting accounts, the registered domain and domain auto-join.
- [Single sign-on](https://docs.semicola.com/guides/single-sign-on.md): Let your organization's members sign in with your corporate identity provider (Okta, Azure AD, Google Workspace and others).
- [Bring data in](https://docs.semicola.com/guides/bring-data-in.md): Connect conversion events, finished creatives, seller inventory and seller materials to the right Semicola workflow.
- [Build a reporting pipeline](https://docs.semicola.com/guides/reporting-pipeline.md): Read delivery into your application: answer an agent question with get_delivery, refresh a dashboard, or download aggregates as CSV.
- [Tasks](https://docs.semicola.com/guides/tasks.md): Async operation polling: receive a task id, poll it for status, and handle the outcome.
- [Activity and audit logs](https://docs.semicola.com/guides/audit-logs.md): Review API calls and record changes for debugging, compliance and operational visibility.
- [Notifications](https://docs.semicola.com/guides/notifications.md): The in-app and email notifications for campaigns, media buys, creatives, storefronts and asks, and how to choose which ones you get.
- [Release notes](https://docs.semicola.com/guides/release-notes.md): Catch up on changes that matter to your account, explore capabilities you may not use yet, and browse the release feed.
- [Shared rooms](https://docs.semicola.com/guides/shared-rooms.md): Bring teammates into a Semi conversation with a room link, and talk to them without asking Semi.
- [Frequency caps](https://docs.semicola.com/guides/frequency-caps.md): Cap how often a person sees your ads: the AdCP frequency_cap a seller enforces on a package, and buyer-side caps on advertisers and campaigns.
- [Pacing periods](https://docs.semicola.com/guides/pacing-periods.md): Shape a campaign flight into dated periods with weights or budgets; each staged buy splits into one package per period at launch.
- [API keys](https://docs.semicola.com/guides/api-keys.md): Create, list and revoke personal and organization API keys for scripts and service-to-service integrations.
- [Cloud drives](https://docs.semicola.com/guides/cloud-drive-connections.md): Which cloud drives Semicola can take files from, and how to ask for the ones that are not available yet.
- [Diagnosing a stuck media buy](https://docs.semicola.com/guides/diagnosing-stuck-media-buys.md): Why isn't my buy live? The fields that say what a media buy is waiting on, who owns the wait, and what to do.

### Help

- [Glossary](https://docs.semicola.com/help/glossary.md): Every term used across the Semicola docs, in alphabetical order, with a short definition.
- [Changelog](https://docs.semicola.com/help/changelog.md): Product changes in the Semicola app, the storefront agent and the docs.

## Build with Semicola

### v3

#### Start building

- [Build with Semicola](https://docs.semicola.com/v3/overview.md): One account-aware MCP connection for planning, buying, selling and reporting across sellers.
- [Choose your operating loop](https://docs.semicola.com/v3/choose-your-loop.md): Decide whether to work inside Semicola, build your own application, or combine an agent with code that owns progress.
- [Connect in five minutes](https://docs.semicola.com/v3/quickstart.md): Add Semicola to Codex, Claude Code or any MCP client, sign in with OAuth, and verify the account with a read-only call.

#### Build your integration

- [Build an agent](https://docs.semicola.com/v3/build-an-agent.md): Grow a read-only prototype into a buying loop that survives retries, restarts and human approval.
- [Runnable examples](https://docs.semicola.com/v3/examples.md): Copy-and-run starters that call Semicola over MCP and REST with curl, TypeScript and Python.

#### MCP reference

- [v3 Tool Catalog](https://docs.semicola.com/v3/tool-catalog.md): Every tool the Semicola v3 MCP endpoint can list, with its effect, risk, widget and input fields.

#### Shared reference

- [Authentication](https://docs.semicola.com/v3/authentication.md): Authenticate an interactive or headless client to the v3 MCP endpoint with OAuth or an API key.
- [Account access](https://docs.semicola.com/v3/account-access.md): Confirm the active account, understand what it lets you do, and switch only to accounts your credential can reach.
- [Manage buyer agents](https://docs.semicola.com/v2/setup/buyer-agent-credentials.md): Add connected software agents to your buyer organization and manage their access and credentials.
- [MCP client setup](https://docs.semicola.com/v3/client-setup.md): Connect Codex, Claude Code, Claude, ChatGPT or another MCP host to Semicola's account-resolved endpoint.
- [Copilot Studio and Gemini Enterprise](https://docs.semicola.com/v3/enterprise-hosts.md): Add the Semicola MCP server as a tool in a Microsoft Copilot Studio agent or as a Connected App in Gemini Enterprise. Tenant-side steps only; neither vendor reviews it.
- [White-label ChatGPT app](https://docs.semicola.com/v3/white-label-chatgpt-app.md): What Semicola provides today for a customer-branded ChatGPT app: the Listing page ChatGPT destination, the public listing domain and the OpenAI domain-ownership token. The submission itself happens in OpenAI.
- [Errors](https://docs.semicola.com/v3/errors.md): Handle validation, account, revision, upstream and partial-result failures from v3 tools.
- [Limits](https://docs.semicola.com/v3/limits.md): Design v3 clients around bounded tool calls, connection lifetime, payload size and seller latency.
- [Pagination](https://docs.semicola.com/v3/pagination.md): The three paging styles in the REST API and the cursor style on MCP tools, and how to write one client that handles them.
- [Semi API](https://docs.semicola.com/v3/semi-api.md): Chat with Semi over REST: send a turn, stream it, decide confirmations, manage conversations, sharing and language, and inspect seller calls.
- [MCP Apps](https://docs.semicola.com/v3/mcp-apps.md): How widget-bearing tools return interactive pages, and the REST endpoint that serves the same built widget HTML to hosts without a live MCP client.
- [Public URL requirements](https://docs.semicola.com/v3/public-urls.md): Rules for URLs Semicola calls on your behalf: webhook endpoints, sales-agent endpoints, brand domains and task callbacks.
- [Changes and compatibility](https://docs.semicola.com/v3/changelog.md): Changes to the v3 MCP endpoint, what counts as a breaking change, and how to stay compatible.

### Concepts

- [Object model](https://docs.semicola.com/concepts/object-model.md): Every buyer and seller object, what owns it, and where it is documented.
- [The storefront agent](https://docs.semicola.com/concepts/storefront-agent.md): The hosted agent that represents a seller to buyer agents: what it works from, its five jobs, and what it never does.
- [Merchandising](https://docs.semicola.com/concepts/merchandising.md): How the facts a storefront agent sells from are owned, versioned and activated.
- [Media buy lifecycle](https://docs.semicola.com/concepts/media-buy-lifecycle.md): How a media buy moves from draft to delivery, who owns each wait, and how both sides see it.
- [Campaign readiness](https://docs.semicola.com/concepts/campaign-readiness.md): How to tell whether a campaign can launch and whether it is delivering: launch blockers, operational status and per-buy blockers.
- [Sandbox](https://docs.semicola.com/concepts/sandbox.md): Test the whole media buying loop with a sandbox advertiser: no real spend, same tools and endpoints.
- [Asks](https://docs.semicola.com/concepts/asks.md): File and track anything you are waiting on Semicola for.
- [Budgets, fees and currency](https://docs.semicola.com/concepts/budgets-and-currency.md): What a budget number means, how media buys allocate against the campaign budget, and how currencies must line up between a campaign and a seller.
- [Which domain is which](https://docs.semicola.com/concepts/domains.md): Your account's registered domain, your storefront's brand domain, your publisher domains and your public listing domain do different jobs. Only publisher domains are inventory.
- [Identity documents](https://docs.semicola.com/concepts/identity-documents.md): Who publishes adagents.json, brand.json and agent capabilities, where each lives, and how Semicola reads them.
- [Agents](https://docs.semicola.com/concepts/agents.md): Buyer agents your organization connects, and the agents that power a storefront: the hosted sales agent and the sales agents behind inventory sources.
- [How AdCP thinks about video](https://docs.semicola.com/concepts/video-creatives.md): Why a hosted video carries pixel dimensions and a VAST tag doesn't, and where size, duration and container rules live.
- [How Semicola uses AdCP](https://docs.semicola.com/concepts/adcp.md): AdCP defines a task against one seller; Semicola runs it across many. What the buy side sends, what a hosted storefront answers, and how versions are negotiated.

### Agents

- [Semicola for advertising agents](https://docs.semicola.com/agents/for-agents.md): The brief to give an autonomous agent before it connects to Semicola: what it can do, how to connect, and the limits of its authority.

### Skills

- [Agent skills](https://docs.semicola.com/skills/overview.md): Versioned, task-shaped instructions an agent can load before it works in Semicola.
- [Build with Semicola](https://docs.semicola.com/skills/build-with-semicola.md): Use when connecting an agent or app to Semicola for the first time: reach the v3 MCP endpoint, verify access read-only, read the live tool contract and learn the rules every other skill assumes.
- [Get an account ready to buy](https://docs.semicola.com/skills/get-account-ready-to-buy.md): Use when a buyer account cannot place a media buy yet: work through the blockers get_status reports (advertiser, currency, seller connections, terms and billing) until the account is ready.
- [Set up a campaign](https://docs.semicola.com/skills/set-up-a-campaign.md): Use when a buyer wants to turn a brief into a draft campaign, request and compare proposals from sellers, attach creatives and stage the chosen media buys. Stops before launch.
- [Manage a campaign](https://docs.semicola.com/skills/manage-a-campaign.md): Use when a buyer asks about or wants to change a campaign that already exists: read delivery and pacing, launch with approval, pause or resume, change budget or flight, cancel or archive.
- [Buy from a seller](https://docs.semicola.com/skills/buy-from-seller.md): Use when a buyer names one seller: check that seller is available to the advertiser, get its proposal or pick its products, refine, and stage the media buy.
- [Test a sales agent](https://docs.semicola.com/skills/test-sales-agent.md): Use when a seller wants to connect its AdCP sales agent as an inventory source and prove it works: run a discovery test, send a practice brief through the storefront agent, and report the evidence.
- [Set up an event source](https://docs.semicola.com/skills/set-up-an-event-source.md): Use when a buyer campaign needs conversion measurement: find or create the advertiser's event source and confirm events are arriving.
- [Generate campaign creatives](https://docs.semicola.com/skills/generate-campaign-creatives.md): Use when a buyer wants a new creative built for a campaign in the creative composer: pick a format, fill its slots from library assets and drafted copy, and save the finished creative to the library.
- [Inspect a tag sheet](https://docs.semicola.com/skills/inspect-tag-sheet.md): Use when a buyer wants to check how Semicola reads a CSV, XLS or XLSX ad tag sheet before importing it: how many creatives it finds, their sizes, and which rows need a destination.
- [Publish an OpenAI app](https://docs.semicola.com/skills/publish-an-openai-app.md): Use when a seller admin wants their storefront in ChatGPT: check what the Listing's ChatGPT destination has ready, set up the public listing domain and the OpenAI domain-ownership token, and walk the manual OpenAI submission without claiming anything Semicola cannot see.
- [Buyer skill](https://docs.semicola.com/v2/buyer/skill.md): The skill file for agents that buy media through Semicola for an advertiser or agency: how to connect, the rules to follow, and which tool and task skill to use for each job.
- [Storefront skill](https://docs.semicola.com/v2/storefront/skill.md): The skill file for agents that operate a seller's storefront on Semicola: how to connect, the rules to follow, and which tool to use to set up, teach, review and report.

## Machine-readable resources

- [Full documentation](https://docs.semicola.com/llms-full.txt): every page in one file
- [Agent brief](https://semicola.com/for-agents.md): the short brief to hand an agent before it connects
- [Brand identity](https://semicola.com/.well-known/brand.json): AdCP brand.json
- [OpenAPI](https://api.semicola.com/api/v3/openapi.yaml): REST API description
- Support: support@semicola.com