# Admux — instructions for AI agents
# LOCAL BUILD: every external service (payments, ad providers, policy screening, email) is a local stub. No real ads run.

Admux lets advertisers buy ad placements in ChatGPT, Google Search (including eligible AI placements) and the Gravity network
from one prepaid USD balance. Advertisers supply all creative; Admux screens it per provider, submits it, and settles spend.

API base:   https://api.admux.ai/v1
OpenAPI:    https://api.admux.ai/openapi.json
MCP:        https://api.admux.ai/mcp  (Streamable HTTP, same Bearer key)   ·  stdio: `ADMUX_API_KEY=... npm run mcp` in the app directory
Scopes:     https://api.admux.ai/v1/scopes

## Authentication
Send `Authorization: Bearer $ADMUX_API_KEY`. Keys are created by a workspace owner or campaign manager in the web app and shown once.
Never put the key in prompts, logs or public files. Expired or revoked keys are rejected for every request (including pause/cancel);
work you already got accepted (e.g. an automatic launch) continues under its recorded authorization.

## Money
All amounts are integer USD cents unless the field name says micros. Advertiser charge = provider media cost × (1 + channel markup),
rounded once per campaign leg (half-even). A budget is RESERVED in full when you submit; rejection does not release it. Only cancellation,
completion or an authorized budget decrease releases funds, and only after provider settlement evidence proves them unused.
Key spending limits cap NEW budget authorizations per UTC day/week/month/lifetime; they do not pace delivery.

## Workflow
1. GET /channels — creative rules, targeting support, minimums, current markup, pacing disclosure.
2. POST /assets/images (base64) or /assets/copy — supply your own creative. Admux never generates ad content.
3. POST /campaigns {name, draft} → PATCH /campaigns/{id}/draft (send expectedDraftVersion) → POST /campaigns/{id}/validate.
4. POST /campaigns/{id}/offers → a price offer valid 15 minutes (server clock). Issuing it reserves nothing.
5. POST /campaigns/{id}/submit {offerId, expectedDraftVersion, launchMode} with an Idempotency-Key header.
   launchMode "review" (default): approved legs wait for an explicit launch. "auto" (Launch as approved) needs campaigns:launch.
   Returns 202 with an operation; poll GET /operations/{id}. Acceptance ≠ approval ≠ serving.
6. GET /campaigns/{id} — per leg: admuxReview, providerReview, desired vs observed delivery, settlement, held/charged/released cents.
7. POST /campaigns/{id}/launch {legIds} — launch approved legs (campaigns:launch).
8. Live changes: PATCH draft, then POST /campaigns/{id}/change-offers and /apply-change. Accepting a delivery change reprices ALL remaining
   delivery at current rates; increases reserve only the delta (also need campaigns:reserve).
9. POST /campaigns/{id}/pause|resume|remove-legs|cancel — requests, not confirmations; poll until observed delivery stops.
10. GET /reports (and /reports.csv; includes a previous-period comparison), GET /balance.
11. Human policy review: if a leg is under review, POST /campaigns/{id}/legs/{legId}/review-note {text} sends context
    to the reviewer (it never clears review by itself). POST /campaigns/{id}/duplicate and /archive manage drafts.

MCP tools mirror these operations with the same scopes (channels_list, asset_upload_image, asset_save_copy,
campaign_create_draft, campaign_update_draft, campaign_validate, offer_create, offer_get, campaign_submit,
campaign_launch, campaign_pause, campaign_resume, campaign_remove_legs, campaign_cancel, change_preview,
change_offer, change_apply, campaign_duplicate, campaign_update_metadata, campaign_archive, campaign_review_note,
operation_get, balance_get, report_get, readiness_get, ...). Tools you lack scopes for are not listed.

Pacing: The provider controls daily pacing. If approval arrives late, your remaining budget may be spent over fewer days.
Your total budget and end date stay unchanged.

## Retries and errors
Mutations that move money or change delivery require an Idempotency-Key. Same key + same body returns the original result; a different body is 409.
Errors: {"error":{"code","message","details"}} with codes such as OFFER_EXPIRED, VERSION_CONFLICT, INSUFFICIENT_FUNDS,
KEY_ALLOWANCE_EXCEEDED, AUTHORITY_DENIED, REVIEW_REQUIRED, PROVIDER_NOT_READY, TARGETING_UNSUPPORTED, HOLD_ACTIVE, MODE_LOCKED.
Lists use cursor pagination (nextCursor). There are no general request-rate quotas in v0.

## Not available to keys
Payments/top-ups, refunds, billing documents, membership, key administration and staff operations are human-only.
Reading these docs grants nothing: the key's scopes and limits are enforced by Admux.