{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "MarketingRouter API", "version": "2026-10-01", "summary": "Agent-first managed Meta advertising, with explicit owner spending control.", "description": "Meta (Facebook and Instagram) through MarketingRouter's managed Whop account. Sandbox mode never buys ads. Live operations require advertiser assignment, owner consent, owned creative, provider/pixel readiness, verified funding, operator allowance and exact owner approval. Read capabilities and advertiser readiness before acting. Provider preparation and checkout are explicit mutations; do not assume a request timeout means no mutation occurred. Money is integer USD cents. Success responses use data/meta; errors use error with stable code and request_id. JSON bodies are limited to 16 KiB. MarketingRouter does not generate creative, crawl sites, guarantee acquisition costs, auto-optimize budgets, auto-refund or offer other channels. Agents should keep owner credentials separate and give approval_url/checkout_url to the owner." }, "servers": [ { "url": "/", "description": "Use the origin serving this specification. Paths already contain their API prefix." } ], "tags": [ { "name": "Discovery" }, { "name": "Quotes" }, { "name": "Advertiser" }, { "name": "Assets" }, { "name": "Campaigns" }, { "name": "Approvals" }, { "name": "Results" }, { "name": "Events" }, { "name": "Activity" }, { "name": "Funding" }, { "name": "Keys" }, { "name": "Owner session" }, { "name": "Operator" } ], "paths": { "/api/v1/capabilities": { "get": { "operationId": "getCapabilities", "tags": [ "Discovery" ], "summary": "Discover service capabilities", "description": "Public and side-effect free. Flags describe deployment configuration; they are not a claim that an advertiser is ready or a campaign can immediately spend.", "security": [], "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/api/v1/quotes": { "post": { "operationId": "createQuote", "tags": [ "Quotes" ], "summary": "Estimate a sandbox or live media budget", "description": "Public and side-effect free. Does not crawl, generate creatives, call providers, reserve budgets or collect payment. Live platform fee is zero in beta; sandbox fee is illustrative.", "security": [], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "sandbox": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "url": "https://example.com", "objective": "traffic", "budget_cents": 10000, "geo": [ "US" ], "mode": "sandbox" } }, "live": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "url": "https://example.com", "objective": "traffic", "budget_cents": 10000, "geo": [ "US" ], "mode": "live" } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/api/v1/advertiser": { "get": { "operationId": "getAdvertiserReadiness", "tags": [ "Advertiser" ], "summary": "Read your managed Meta readiness", "description": "Returns only the current owner's assigned identity, destination, consent, creatives and allowance. Sandbox keys are rejected. Operator setup is currently required before self-service campaign preparation.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertiserResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns": { "get": { "operationId": "listCampaigns", "tags": [ "Campaigns" ], "summary": "List workspace campaigns", "description": "UUID descending, not chronological order. Follow next_cursor until null.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Use data.next_cursor from the preceding page." } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignListResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createCampaign", "tags": [ "Campaigns" ], "summary": "Create a reviewable campaign plan", "description": "Both modes start awaiting_approval. Live creation checks owner assignment and media readiness but never creates an ad or charges. POST prepare is a separate explicit provider operation. Retry the same normalized request with the same key.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Persist for this operation. Reuse for the same payload after a timeout; changed content returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRequest" }, "examples": { "sandbox": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "name": "Example campaign", "url": "https://example.com", "objective": "traffic", "budget_cents": 10000, "currency": "USD", "geo": [ "US" ], "mode": "sandbox" } }, "liveMeta": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "name": "Example Meta campaign", "url": "https://example.com", "objective": "traffic", "budget_cents": 10000, "currency": "USD", "geo": [ "US" ], "mode": "live", "meta": { "starts_at": "2030-01-01T12:00:00Z", "ends_at": "2030-01-03T12:00:00Z", "headline": "Find your next useful tool", "primary_text": "See what our product can do for you.", "creative_file_id": "file_ownedcreative", "facebook_social_account_id": "sacc_assignedpage" } } } } } } }, "responses": { "200": { "description": "Existing resource from an idempotent replay.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns/{id}": { "get": { "operationId": "getCampaign", "tags": [ "Campaigns" ], "summary": "Read a campaign and its exact plan", "description": "Read the current plan_hash before presenting the approval URL to the owner. Resource access is owner-scoped.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns/{id}/prepare": { "post": { "operationId": "prepareCampaign", "tags": [ "Campaigns" ], "summary": "Create a non-delivering Meta draft", "description": "Live mode only, from awaiting_approval/preparing. Creates a provider draft, not paid delivery. Provider operation keys are persisted internally. On uncertainty retry this same campaign operation; after 23 hours request operator reconciliation rather than creating another draft.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:write" ], "x-agent-key-mode": "live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns/{id}/approve": { "post": { "operationId": "approveCampaign", "tags": [ "Approvals" ], "summary": "Approve the exact plan and activate delivery", "description": "Owner only. Sandbox approval changes local state. Live approval (draft/launching) performs fresh payment and provider-plan verification, validates pixel and conversion, reserves the lifetime budget, and requests provider activation. Provider review may delay delivery. Agent keys are always rejected. No resume operation is offered.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequest" }, "examples": { "sandbox": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "approved_budget_cents": 10000, "acknowledge_sandbox": true } }, "live": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "approved_budget_cents": 10000, "approved_plan_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "acknowledge_live_spend": true } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns/{id}/pause": { "post": { "operationId": "pauseCampaign", "tags": [ "Campaigns" ], "summary": "Pause campaign delivery", "description": "Sandbox active → paused locally. Live active/launching/pausing/attention_required campaigns with prior owner approval request a provider pause; paused retries reconcile. A timeout is not proof of pause. Reservations remain; spend and charges may arrive late.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns/{id}/reconcile": { "post": { "operationId": "reconcileCampaign", "tags": [ "Campaigns" ], "summary": "Refresh provider status and metrics", "description": "Requires a live key or owner and an existing provider campaign ID. Reads Whop and updates the local snapshot; never initiates launch or increases budget. Use after uncertain activation or pause.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/campaigns/{id}/results": { "get": { "operationId": "getCampaignResults", "tags": [ "Results" ], "summary": "Read submitted events and cached provider metrics", "description": "Does not make a provider request. POST reconcile to refresh the snapshot. A null spent_cents is unknown, not zero. Keep submitted conversion revenue separate from provider-attributed results.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/assets": { "get": { "operationId": "listAssets", "tags": [ "Assets" ], "summary": "List owned creative images", "description": "Returns up to 100 owned assets, newest first. No pagination is provided because the upload quota is 100.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createAssetUpload", "tags": [ "Assets" ], "summary": "Create a direct creative upload", "description": "Explicit provider write. Send filename and Idempotency-Key, PUT raw image bytes to upload_url using upload_headers, then POST complete_url. URLs are signed and should not be logged. Maximum 10 MiB; public PNG, JPEG or WebP images only. Retries always return 201, including an existing upload.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:write" ], "x-agent-key-mode": "live", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Persist for this operation. Reuse for the same payload after a timeout; changed content returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRequest" }, "examples": { "image": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "filename": "product-ad.png" } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetUploadResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/assets/{id}/complete": { "post": { "operationId": "completeAssetUpload", "tags": [ "Assets" ], "summary": "Verify creative upload readiness", "description": "Reads the owned provider file and validates type, size, HTTPS URL and ready state. A 409 upload_pending means wait and retry this endpoint; upload_failed needs correction. No request body is needed.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:write" ], "x-agent-key-mode": "live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^file_[A-Za-z0-9]+$" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/events": { "post": { "operationId": "recordConversionEvent", "tags": [ "Events" ], "summary": "Record and forward a conversion event", "description": "Sandbox events require an active sandbox campaign and never contact Whop. Owner-approved live campaigns forward events to Whop with captured anonymous_id and exact source origin. Deduplication uses event_id, not an Idempotency-Key header. Same event content returns 200; changed content with the same ID returns 409. Retry an uncertain forwarding result with the same event_id and payload.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventRequest" }, "examples": { "sandbox": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "campaign_id": "76eeb0bc-cfcb-4d68-9e19-4f09e3862068", "event_id": "visit-001", "type": "page_view" } }, "livePurchase": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "campaign_id": "76eeb0bc-cfcb-4d68-9e19-4f09e3862068", "event_id": "purchase-001", "type": "purchase", "value_cents": 4900, "currency": "USD", "source_url": "https://example.com/thanks", "anonymous_id": "captured-whop-anonymous-id" } } } } } }, "responses": { "200": { "description": "Existing resource from an idempotent replay.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReceiptResponse" } } } }, "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReceiptResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/activity": { "get": { "operationId": "listActivity", "tags": [ "Activity" ], "summary": "Read the immutable activity history", "description": "Ordered by created_at then UUID descending. Cursor must belong to this owner. Audit metadata never contains raw keys or provider payment secrets.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Use data.next_cursor from the preceding page." } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityListResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/balance": { "get": { "operationId": "getBalance", "tags": [ "Funding" ], "summary": "Read reusable advertising balance", "description": "Live key with campaigns:read, or owner session. Returns available credit, reserved lifetime budgets, funding hold and recent ledger entries. No provider mutation.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/balance/topups": { "get": { "operationId": "listBalanceTopups", "tags": [ "Funding" ], "summary": "List advertising top-ups", "description": "Up to 50 per page in descending UUID order. Use next_cursor until null. Only the authenticated owner's balance orders are returned.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Use data.next_cursor from the preceding page." } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupListResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createBalanceTopup", "tags": [ "Funding" ], "summary": "Request a Whop balance top-up", "description": "Live key with campaigns:write, or owner session. Requires paid delivery gates, configured reconciliation, ready advertiser consent and remaining funding allowance. USD $50–$1,000; at most ten unresolved requests. The beta platform fee is zero. Preserve the Idempotency-Key and exact amount on retries. This creates a hosted link for the owner to pay; it neither charges a card nor launches an ad.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:write" ], "x-agent-key-mode": "live", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Persist for this operation. Reuse for the same payload after a timeout; changed content returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupRequest" }, "examples": { "deposit": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "amount_cents": 10000, "currency": "USD" } } } } } }, "responses": { "200": { "description": "Existing resource from an idempotent replay.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupResponse" } } } }, "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/balance/topups/{id}": { "get": { "operationId": "getBalanceTopup", "tags": [ "Funding" ], "summary": "Read a top-up's verified status", "description": "Live key with campaigns:read, or owner session. Poll with bounded backoff. Only funded means credit has been verified; review_required requires operator resolution.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/balance/topups/{id}/reconcile": { "post": { "operationId": "reconcileBalanceTopup", "tags": [ "Funding" ], "summary": "Refresh a top-up from Whop", "description": "Live key with campaigns:read, or owner session. No request body. Reads provider receipts and applies idempotent ledger updates. Does not create charges or refunds. Webhooks normally update state automatically.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/funding": { "get": { "operationId": "listFundingOrders", "tags": [ "Funding" ], "summary": "List campaign funding orders", "description": "Up to 50 per page, UUID descending. Funded receipt credit, operator allowance, and Whop's actual ad balance are distinct.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [ { "name": "campaign_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Use data.next_cursor from the preceding page." } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingListResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createFundingCheckout", "tags": [ "Funding" ], "summary": "Create an owner-authorized hosted checkout", "description": "Owner only; billing and live service gates, production provider, approved advertiser consent and sufficient operator allocation are required. Creates a single-use one-time hosted checkout for exact saved campaign terms. Does not launch advertising or directly debit a card. Retain the idempotency key; never recreate an uncertain order to bypass review. Taxes/buyer fees may be shown at checkout.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Persist for this operation. Reuse for the same payload after a timeout; changed content returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]{8,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingRequest" }, "examples": { "campaign": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "campaign_id": "76eeb0bc-cfcb-4d68-9e19-4f09e3862068" } } } } } }, "responses": { "200": { "description": "Existing resource from an idempotent replay.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingOrderResponse" } } } }, "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingOrderResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/funding/{id}": { "get": { "operationId": "getFundingOrder", "tags": [ "Funding" ], "summary": "Read funding state", "description": "Only funded represents server-verified media credit. The browser returning from checkout does not verify payment.", "security": [ { "AgentKey": [] }, { "OwnerAccessToken": [] } ], "x-required-agent-scopes": [ "campaigns:read" ], "x-agent-key-mode": "live", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingOrderResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/v1/funding/{id}/reconcile": { "post": { "operationId": "reconcileFundingOrder", "tags": [ "Funding" ], "summary": "Verify the hosted payment with Whop", "description": "Owner only; no request body. Reads provider receipts, verifies exact campaign correlation and amount, and atomically reconciles credit. Duplicate calls never double-credit. Refunds/disputes may revoke credit and hold further launches. Does not charge, refund or start ads. Signed Whop webhooks and a scheduled recovery job reconcile payments. Refunds and disputes place credit on hold and request affected campaign pauses; provider delays can still accrue charges.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingOrderResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/integrations": { "get": { "operationId": "getOwnerIntegrations", "tags": [ "Advertiser" ], "summary": "Read console integration readiness", "description": "Owner-only console view. Agents should use GET /api/v1/advertiser.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationsResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/integrations/whop": { "post": { "operationId": "authorizeManagedAdvertising", "tags": [ "Advertiser" ], "summary": "Record owner advertising consent", "description": "Requires an existing operator-assigned advertiser. Consent permits preparation; it never approves a campaign budget or starts delivery.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRequest" }, "examples": { "authorize": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "consent": true } } } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertiserResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } }, "delete": { "operationId": "revokeManagedAdvertisingConsent", "tags": [ "Advertiser" ], "summary": "Revoke managed advertising consent", "description": "Owner only. Pause and reconcile launching/active/pausing/attention_required campaigns first; otherwise returns 409. Clears consent and disables the assignment.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRevokedResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/settings/keys": { "get": { "operationId": "listAgentKeys", "tags": [ "Keys" ], "summary": "List agent key metadata", "description": "Owner only. Raw keys are never returned by reads.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createAgentKey", "tags": [ "Keys" ], "summary": "Create a scoped sandbox or live agent key", "description": "Owner only. Copy the raw key from this response exactly once. Keep live and sandbox credentials separate; neither grants campaign approval or direct payment authority. Live write keys can request balance payment links.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRequest" }, "examples": { "live": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "name": "Growth agent", "mode": "live", "scopes": [ "campaigns:read", "campaigns:write", "events:write" ] } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/settings/keys/{id}": { "delete": { "operationId": "revokeAgentKey", "tags": [ "Keys" ], "summary": "Revoke an agent key", "description": "Owner only. Requests using the revoked key are rejected immediately.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRevokedResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/auth/session": { "get": { "operationId": "getOwnerSession", "tags": [ "Owner session" ], "summary": "Inspect the console session", "description": "Returns user:null for an unauthenticated visitor. The mode field describes the default experience, not a spending permission. Owner session cookies are managed by the hosted sign-in flow; never copy them into an agent.", "security": [], "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerSessionResponse" } } } }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/integrations/whop/advertisers": { "post": { "operationId": "assignManagedAdvertiser", "tags": [ "Operator" ], "summary": "Assign an advertiser to an owner", "description": "Operator-only owner session allowlisted by OPERATOR_OWNER_IDS. Creates one verified page/destination assignment with an allocation limit; this is not a cash credit. Existing assignments require operator reconciliation instead of replacement. Customers and agents cannot call this operation.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "x-operator-only": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertiserAssignmentRequest" }, "examples": { "assignment": { "summary": "Illustrative request. Replace identifiers and schedule with values from your workspace.", "value": { "owner_id": "76eeb0bc-cfcb-4d68-9e19-4f09e3862068", "facebook_social_account_id": "sacc_assignedpage", "destination_origin": "https://example.com", "allocation_limit_cents": 10000, "enabled": false } } } } } }, "responses": { "201": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertiserAssignmentResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateAdvertiserAllowance", "tags": [ "Operator" ], "summary": "Update advertiser approval or allowance", "description": "Operator only. Page identity and origin cannot change through this operation. Allowance cannot drop below reserved budgets. Turning enabled off blocks new launches; it does not pause existing campaigns, issue refunds, or credit funding.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "x-operator-only": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertiserUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertiserUpdatedResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/integrations/whop/operator": { "get": { "operationId": "getOperatorMetaReadiness", "tags": [ "Operator" ], "summary": "Read the operator's managed Meta setup", "description": "Operator-only owner session, allowlisted by OPERATOR_OWNER_IDS. Exposes connected Facebook identities and assigned workspaces solely for operator setup. Does not create connections or ad campaigns.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "x-operator-only": true, "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/api/integrations/whop/connect": { "post": { "operationId": "connectOperatorMetaBusiness", "tags": [ "Operator" ], "summary": "Connect Meta to the managed provider account", "description": "Operator-only owner session allowlisted by OPERATOR_OWNER_IDS. Returns a provider OAuth authorization URL. An explicit operator action connects its managed Meta business. No body required; customers and agent keys cannot call this operation.", "security": [ { "OwnerAccessToken": [] } ], "x-owner-only": true, "x-operator-only": true, "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "X-API-Version": { "schema": { "type": "string", "const": "2026-10-01" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeUrlResponse" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "$ref": "#/components/responses/Error502" }, "503": { "$ref": "#/components/responses/Error503" } } } } }, "components": { "securitySchemes": { "AgentKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mr_test_<64 hex> or mr_live_<64 hex>", "description": "Agent keys are owner-scoped, mode-bound, revocable and scoped. x-required-agent-scopes and x-agent-key-mode describe each operation. Owner-only operations always reject agent keys." }, "OwnerAccessToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Supabase JWT", "description": "Verified owner access token; the hosted console also uses its managed signed-in cookie session. Cookie mutations require same-origin requests. Keep owner sessions out of agent runtimes." } }, "responses": { "Error400": { "description": "Invalid JSON or missing/invalid Idempotency-Key.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Authentication missing, invalid, expired or revoked.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Owner-only operation, insufficient scope, sandbox key on a live operation, invalid origin or resource assignment mismatch.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Resource not found in this owner's workspace.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "State, idempotency, consent, provider readiness, funding, allocation or exact-plan conflict. Inspect error.code; reconcile uncertain provider operations before retrying.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "JSON body exceeds 16384 bytes.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error415": { "description": "Use Content-Type: application/json for operations with a JSON body.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error422": { "description": "Invalid fields, cursor, media, conversion identity or schedule. Validation details identify individual fields.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Provider throttling or upload quota reached. Retry with backoff; retain the original idempotency key.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error500": { "description": "Unexpected server error. Retain request_id; retry only with the original idempotency key.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error502": { "description": "Provider failed, rejected or returned an uncertain/malformed result. Do not create a new operation to bypass uncertainty.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Database, authentication, operator configuration or provider temporarily unavailable.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Meta": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "pattern": "^req_" }, "api_version": { "type": "string", "const": "2026-10-01" } }, "required": [ "request_id", "api_version" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Stable machine-readable error code; use this rather than matching the message." }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ] }, "MetaPlan": { "type": "object", "properties": { "starts_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "ends_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "headline": { "type": "string", "minLength": 1, "maxLength": 255 }, "primary_text": { "type": "string", "minLength": 1, "maxLength": 2200 }, "creative_file_id": { "type": "string", "pattern": "^file_[A-Za-z0-9]+$" }, "facebook_social_account_id": { "type": "string", "pattern": "^sacc_[A-Za-z0-9]+$" } }, "required": [ "starts_at", "ends_at", "headline", "primary_text", "creative_file_id", "facebook_social_account_id" ], "additionalProperties": false, "description": "An immutable single-image Meta plan. Start at least five minutes after creation. Duration must be 24 hours–30 days. Preparation/approval also reject elapsed starts. Facebook identity, image, destination, copy, schedule, countries and lifetime budget are verified against the provider before launch." }, "QuoteRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https://[^/@?#]+\\.[^/@?#]+(?:[/?#].*)?$", "description": "Public HTTPS destination with a dotted host and no embedded credentials. A live URL must match the workspace's exact assigned origin." }, "objective": { "type": "string", "enum": [ "purchase", "signup", "traffic" ] }, "budget_cents": { "type": "integer", "minimum": 100, "maximum": 10000000 }, "currency": { "default": "USD", "type": "string", "const": "USD" }, "geo": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "target_cac_cents": { "type": "integer", "minimum": 1, "maximum": 10000000, "description": "Planning target only. Not an enforced CAC ceiling, guarantee, or automatic optimization rule." }, "conversion_event": { "type": "string", "enum": [ "purchase", "signup", "page_view" ] }, "mode": { "default": "sandbox", "type": "string", "enum": [ "sandbox", "live" ] } }, "required": [ "url", "objective", "budget_cents", "geo" ], "additionalProperties": false }, "CampaignRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https://[^/@?#]+\\.[^/@?#]+(?:[/?#].*)?$", "description": "Public HTTPS destination with a dotted host and no embedded credentials. A live URL must match the workspace's exact assigned origin." }, "objective": { "type": "string", "enum": [ "purchase", "signup", "traffic" ] }, "budget_cents": { "type": "integer", "minimum": 100, "maximum": 10000000 }, "currency": { "default": "USD", "type": "string", "const": "USD" }, "geo": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "target_cac_cents": { "type": "integer", "minimum": 1, "maximum": 10000000, "description": "Planning target only. Not an enforced CAC ceiling, guarantee, or automatic optimization rule." }, "conversion_event": { "type": "string", "enum": [ "purchase", "signup", "page_view" ] }, "mode": { "default": "sandbox", "type": "string", "enum": [ "sandbox", "live" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "meta": { "$ref": "#/components/schemas/MetaPlan" } }, "required": [ "url", "objective", "budget_cents", "geo", "name" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "mode": { "const": "live" } }, "required": [ "mode" ] }, "then": { "required": [ "meta" ] } }, { "if": { "properties": { "objective": { "const": "purchase" } }, "required": [ "objective" ] }, "then": { "properties": { "conversion_event": { "const": "purchase" } } } }, { "if": { "properties": { "objective": { "const": "signup" } }, "required": [ "objective" ] }, "then": { "properties": { "conversion_event": { "const": "signup" } } } }, { "if": { "properties": { "objective": { "const": "traffic" } }, "required": [ "objective" ] }, "then": { "properties": { "conversion_event": { "const": "page_view" } } } } ], "description": "Creates a local reviewable plan, never a provider ad or charge. Live plans require a live key or owner, assigned advertiser, owner consent, enabled assignment, ready owned creative, exact assigned Facebook identity and destination. Omitted mode defaults to sandbox." }, "ApprovalRequest": { "anyOf": [ { "type": "object", "properties": { "approved_budget_cents": { "type": "integer", "minimum": 100, "maximum": 10000000 }, "acknowledge_sandbox": { "type": "boolean", "const": true } }, "required": [ "approved_budget_cents", "acknowledge_sandbox" ], "additionalProperties": false }, { "type": "object", "properties": { "approved_budget_cents": { "type": "integer", "minimum": 100, "maximum": 10000000 }, "approved_plan_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "acknowledge_live_spend": { "type": "boolean", "const": true } }, "required": [ "approved_budget_cents", "approved_plan_hash", "acknowledge_live_spend" ], "additionalProperties": false } ], "description": "Owner only. Use the branch matching the saved campaign mode. Live approval must match the current exact lifetime budget and plan_hash; it verifies funding, provider draft, pixel, schedule, consent and allocation before activating. Never give an agent the owner's token." }, "EventRequest": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "event_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9_.:-]+$" }, "type": { "type": "string", "enum": [ "page_view", "signup", "purchase" ] }, "value_cents": { "default": 0, "type": "integer", "minimum": 0, "maximum": 100000000 }, "currency": { "default": "USD", "type": "string", "const": "USD" }, "occurred_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "source_url": { "type": "string", "maxLength": 2048, "format": "uri" }, "anonymous_id": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "campaign_id", "event_id", "type" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "enum": [ "page_view", "signup" ] } }, "required": [ "type" ] }, "then": { "properties": { "value_cents": { "const": 0 } } } } ], "description": "event_id is idempotent within an owner. Live events require an approved campaign, live key, anonymous_id captured by Whop Pixel, source_url on the campaign origin, and positive value_cents for purchases. occurred_at must be within the last seven days and at most five minutes in the future. Submitted events do not establish ad attribution." }, "KeyRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "default": "sandbox", "type": "string", "enum": [ "sandbox", "live" ] }, "scopes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "campaigns:read", "campaigns:write", "events:write" ] } } }, "required": [ "name", "scopes" ], "additionalProperties": false, "description": "Owner only. Sandbox keys cannot perform live provider operations. A live key still cannot approve campaigns, approve payments, manage keys, or change advertiser consent." }, "BalanceTopupRequest": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 5000, "maximum": 100000 }, "currency": { "default": "USD", "type": "string", "const": "USD" } }, "required": [ "amount_cents" ], "additionalProperties": false }, "FundingRequest": { "type": "object", "additionalProperties": false, "properties": { "campaign_id": { "type": "string", "format": "uuid" } }, "required": [ "campaign_id" ] }, "AssetRequest": { "type": "object", "additionalProperties": false, "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_. -]*\\.([pP][nN][gG]|[jJ][pP][eE]?[gG]|[wW][eE][bB][pP])$" } }, "required": [ "filename" ] }, "Quote": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "currency": { "type": "string", "const": "USD" }, "media_budget_cents": { "type": "integer", "minimum": 100, "maximum": 10000000 }, "service_fee_cents": { "type": "integer", "minimum": 0 }, "total_cents": { "type": "integer", "minimum": 0 }, "fee_basis_points": { "type": "integer", "minimum": 0 }, "charge_cents": { "type": "number", "const": 0 }, "live_available": { "type": "boolean" }, "approval_required": { "type": "boolean", "const": true }, "route": { "type": "object", "additionalProperties": false, "properties": { "channel": { "type": "string", "const": "meta" }, "provider": { "type": "string", "const": "whop" }, "status": { "type": "string" } }, "required": [ "channel", "provider", "status" ] }, "performance_estimates": { "type": "null" }, "billing": { "type": "string", "enum": [ "managed_advertising_allocation", "none" ] }, "note": { "type": "string" } }, "required": [ "mode", "currency", "media_budget_cents", "service_fee_cents", "total_cents", "fee_basis_points", "charge_cents", "live_available", "approval_required", "route", "performance_estimates", "billing", "note" ], "description": "A side-effect-free estimate. live_available reports service configuration, not this owner's eligibility. Sandbox uses a 10% illustrative fee; live beta platform fee is zero. Quotes never collect funds, reserve inventory, or predict results." }, "Campaign": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "objective": { "type": "string", "enum": [ "purchase", "signup", "traffic" ] }, "budget_cents": { "type": "integer", "minimum": 100, "maximum": 10000000 }, "currency": { "type": "string", "const": "USD" }, "geo": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "target_cac_cents": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "conversion_event": { "type": "string", "enum": [ "purchase", "signup", "page_view" ] }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "status": { "type": "string", "enum": [ "awaiting_approval", "preparing", "draft", "launching", "active", "pausing", "paused", "attention_required", "completed" ] }, "channel": { "type": "string", "const": "meta" }, "provider": { "type": "string", "const": "whop" }, "delivery_status": { "type": "string", "description": "Last observed provider delivery status; active does not promise that an ad is approved or currently delivering." }, "live_spend_enabled": { "type": "boolean" }, "approval_url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Current deployment URL. HTTPS in production; localhost development may use HTTP." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "approved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/MetaPlan" }, { "type": "null" } ] }, "plan_hash": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "provider_campaign_id": { "anyOf": [ { "type": "string", "pattern": "^adcamp_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "provider_ad_group_id": { "anyOf": [ { "type": "string", "pattern": "^adgrp_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "provider_ad_id": { "anyOf": [ { "type": "string", "pattern": "^ad_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "provider_synced_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "provider_error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget_reserved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "url", "objective", "budget_cents", "currency", "geo", "target_cac_cents", "conversion_event", "mode", "status", "channel", "provider", "delivery_status", "live_spend_enabled", "approval_url", "created_at", "updated_at", "approved_at", "meta", "plan_hash", "provider_campaign_id", "provider_ad_group_id", "provider_ad_id", "provider_synced_at", "provider_error_code", "budget_reserved_at" ] }, "CampaignList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "next_cursor": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "items", "next_cursor" ] }, "Asset": { "type": "object", "additionalProperties": false, "properties": { "file_id": { "type": "string", "pattern": "^file_[A-Za-z0-9]+$" }, "label": { "type": "string" }, "preview_url": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https://" }, { "type": "null" } ] }, "upload_status": { "type": "string", "enum": [ "pending", "processing", "ready", "failed" ] } }, "required": [ "file_id", "label", "preview_url", "upload_status" ] }, "AssetList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "required": [ "items" ] }, "AssetUpload": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^file_[A-Za-z0-9]+$" }, "file_id": { "type": "string", "pattern": "^file_[A-Za-z0-9]+$" }, "label": { "type": "string" }, "upload_status": { "type": "string", "enum": [ "pending", "processing", "ready", "failed" ] }, "upload_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "upload_headers": { "type": "object", "additionalProperties": { "type": "string" } }, "max_bytes": { "type": "number", "const": 10485760 }, "complete_url": { "type": "string" } }, "required": [ "id", "file_id", "label", "upload_status", "upload_url", "upload_headers", "max_bytes", "complete_url" ], "description": "PUT the raw image bytes to upload_url with exactly upload_headers. This URL is short-lived and should be treated as sensitive. Then call complete_url. Uploads are public advertising media. Only PNG/JPEG/WebP up to 10 MiB can complete; maximum 100 upload requests per owner." }, "Advertiser": { "type": "object", "additionalProperties": false, "properties": { "provider": { "type": "string", "const": "whop" }, "channel": { "type": "string", "const": "meta" }, "account_scope": { "type": "string", "const": "managed_advertiser" }, "api_version": { "type": "string", "const": "2026-09-29" }, "configured": { "type": "boolean" }, "live_enabled": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "consent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "destination_origin": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https://" }, { "type": "null" } ] }, "allocation": { "type": "object", "additionalProperties": false, "properties": { "funded_cents": { "type": "integer", "minimum": 0 }, "funding_hold": { "type": "boolean" }, "limit_cents": { "type": "integer", "minimum": 0 }, "reserved_cents": { "type": "integer", "minimum": 0 }, "available_cents": { "type": "integer", "minimum": 0 } }, "required": [ "funded_cents", "funding_hold", "limit_cents", "reserved_cents", "available_cents" ], "description": "available_cents is remaining operator spending authority, not cash or available Whop ad balance. funded_cents is verified receipt credit; reservations are retained after pause." }, "social_accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^sacc_[A-Za-z0-9]+$" }, "name": { "type": "string" }, "platform": { "type": "string", "const": "facebook" } }, "required": [ "id", "name", "platform" ] } }, "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "checks": { "type": "object", "additionalProperties": false, "properties": { "credentials": { "type": "boolean" }, "social_accounts": { "type": "boolean" }, "campaign_read": { "type": "boolean" } }, "required": [ "credentials", "social_accounts", "campaign_read" ] }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "provider", "channel", "account_scope", "api_version", "configured", "live_enabled", "environment", "consent_at", "destination_origin", "allocation", "social_accounts", "creatives", "checks", "status", "message" ], "description": "Only this owner's assigned advertiser resources are returned. Managed setup requires operator assignment; end users never provide Whop credentials. A live-enabled service still requires consent, funding, allowance and per-campaign approval." }, "Integrations": { "type": "object", "additionalProperties": false, "properties": { "supabase": { "type": "object", "additionalProperties": false, "properties": { "configured": { "type": "boolean" }, "purpose": { "type": "string" } }, "required": [ "configured", "purpose" ] }, "whop": { "$ref": "#/components/schemas/Advertiser" }, "channels": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "const": "meta" }, "provider": { "type": "string", "const": "whop" }, "status": { "type": "string" } }, "required": [ "id", "provider", "status" ] } } }, "required": [ "supabase", "whop", "channels" ] }, "ProviderMetrics": { "type": "object", "additionalProperties": false, "properties": { "impressions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "clicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "attributed_purchases": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "attributed_revenue_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "attributed_signups": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spend_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attribution_model": { "type": "string", "const": "last_touch" }, "window": { "type": "string", "const": "campaign_lifetime" }, "synced_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "attributed_purchases", "attributed_revenue_cents", "attribution_model", "window", "synced_at" ] }, "Results": { "type": "object", "additionalProperties": false, "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "currency": { "type": "string", "const": "USD" }, "spent_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "page_views": { "type": "integer", "minimum": 0 }, "signups": { "type": "integer", "minimum": 0 }, "purchases": { "type": "integer", "minimum": 0 }, "revenue_cents": { "type": "integer", "minimum": 0 }, "cac_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "reported_sandbox_events", "whop_and_reported_events" ] }, "attribution": { "type": "string", "const": "submitted_events_unverified" }, "provider_metrics": { "anyOf": [ { "$ref": "#/components/schemas/ProviderMetrics" }, { "type": "null" } ] }, "delivery_status": { "type": "string" }, "note": { "type": "string" } }, "required": [ "campaign_id", "mode", "currency", "spent_cents", "page_views", "signups", "purchases", "revenue_cents", "cac_cents", "roas", "source", "attribution", "provider_metrics", "delivery_status", "note" ], "description": "Read-only cached snapshot. POST reconcile refreshes provider metrics. A missing spend is null, never assumed zero. Top-level conversion counts/revenue are submitted observations; CAC/ROAS use provider-attributed purchases. Spend may lag delivery and pausing does not undo accrued charges." }, "EventReceipt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string" }, "campaign_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "accepted": { "type": "boolean", "const": true }, "deduplicated": { "type": "boolean" }, "forwarding_status": { "type": "string", "enum": [ "not_requested", "pending", "forwarded", "uncertain" ] }, "attribution": { "type": "string", "const": "unverified" } }, "required": [ "id", "event_id", "campaign_id", "mode", "accepted", "deduplicated", "forwarding_status", "attribution" ] }, "ActivityRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "description": "Append-only action name, including provider states and funding changes. New actions may be added." }, "actor_kind": { "type": "string", "enum": [ "owner", "agent", "system" ] }, "actor_key_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "resource_type": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid" }, "campaign_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": true, "description": "Server-generated audit metadata; excludes provider keys, raw API keys and payment/customer secrets." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "action", "actor_kind", "actor_key_id", "resource_type", "resource_id", "campaign_id", "metadata", "created_at" ] }, "ActivityList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRecord" } }, "next_cursor": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "items", "next_cursor" ] }, "ApiKey": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "campaigns:read", "campaigns:write", "events:write" ] } }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "scopes", "mode", "created_at", "revoked_at" ] }, "ApiKeyCreated": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "campaigns:read", "campaigns:write", "events:write" ] } }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "key": { "type": "string", "pattern": "^mr_(test|live)_[a-f0-9]{64}$", "description": "Shown once. Store as a secret; the server retains only its hash." }, "note": { "type": "string" } }, "required": [ "id", "name", "prefix", "scopes", "mode", "created_at", "revoked_at", "key", "note" ] }, "ApiKeyList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "items" ] }, "ApiKeyRevoked": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "revoked_at": { "type": "string", "format": "date-time" }, "revoked": { "type": "boolean", "const": true } }, "required": [ "id", "revoked_at", "revoked" ] }, "PaymentSnapshot": { "type": "object", "additionalProperties": false, "properties": { "payment_id": { "type": "string", "pattern": "^pay_[A-Za-z0-9]+$" }, "status": { "type": "string" }, "substatus": { "type": "string" }, "total_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "refunded_cents": { "type": "integer", "minimum": 0 }, "tax_cents": { "type": "integer", "minimum": 0 }, "net_received_cents": { "type": "integer" }, "settlement_time_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active_holds": { "type": "integer", "minimum": 0 } }, "required": [ "payment_id", "status", "substatus", "total_cents", "refunded_cents", "tax_cents", "net_received_cents", "settlement_time_at", "active_holds" ] }, "FundingOrder": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "creating", "checkout_ready", "outcome_unknown", "failed", "payment_pending", "funded", "review_required" ] }, "media_budget_cents": { "type": "integer", "minimum": 0 }, "service_fee_cents": { "type": "integer", "minimum": 0 }, "total_cents": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "const": "USD" }, "checkout_url": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https://" }, { "type": "null" } ] }, "payment_id": { "anyOf": [ { "type": "string", "pattern": "^pay_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "credited_media_cents": { "type": "integer", "minimum": 0 }, "payment_snapshot": { "anyOf": [ { "$ref": "#/components/schemas/PaymentSnapshot" }, { "type": "null" } ] }, "verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "billing_enabled": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "id", "campaign_id", "status", "media_budget_cents", "service_fee_cents", "total_cents", "currency", "checkout_url", "payment_id", "credited_media_cents", "payment_snapshot", "verified_at", "created_at", "updated_at", "billing_enabled", "note" ], "description": "Only funded reflects verified media credit. A checkout redirect is not payment verification. Taxes/buyer fees may be added at hosted checkout. Verified funding, operator allowance and Whop's actual available ad balance are distinct. Refunds/disputes can remove credits and hold new launches; no automatic refund is provided." }, "FundingList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FundingOrder" } }, "next_cursor": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "billing_enabled": { "type": "boolean" } }, "required": [ "items", "next_cursor", "billing_enabled" ] }, "BalanceEntry": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "funding_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "campaign_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "entry_type": { "type": "string", "enum": [ "credit", "reversal", "reservation" ] }, "amount_cents": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "funding_id", "campaign_id", "entry_type", "amount_cents", "created_at" ] }, "Balance": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "const": "USD" }, "funded_cents": { "type": "integer", "minimum": 0 }, "reserved_cents": { "type": "integer", "minimum": 0 }, "available_cents": { "type": "integer", "minimum": 0 }, "shortfall_cents": { "type": "integer", "minimum": 0 }, "on_hold": { "type": "boolean" }, "topups_enabled": { "type": "boolean" }, "min_topup_cents": { "type": "number", "const": 5000 }, "max_topup_cents": { "type": "number", "const": 100000 }, "recent_entries": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceEntry" } }, "note": { "type": "string" } }, "required": [ "currency", "funded_cents", "reserved_cents", "available_cents", "shortfall_cents", "on_hold", "topups_enabled", "min_topup_cents", "max_topup_cents", "recent_entries", "note" ], "description": "Reusable advertising credit only. Campaign-specific payments are excluded. Reserved lifetime budgets are retained after pause. Available is zero during a funding hold; topups_enabled is a preliminary readiness signal, not a guarantee that checkout will pass provider checks." }, "BalanceTopup": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "creating", "checkout_ready", "outcome_unknown", "failed", "payment_pending", "funded", "review_required" ] }, "currency": { "type": "string", "const": "USD" }, "amount_cents": { "type": "integer", "minimum": 5000, "maximum": 100000 }, "service_fee_cents": { "type": "integer", "minimum": 0 }, "subtotal_cents": { "type": "integer", "minimum": 0 }, "charged_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "tax_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "payment_cost_cents": { "type": "null", "description": "Not quoted by this API. Review final provider costs at hosted checkout; null does not mean zero." }, "checkout_url": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https://" }, { "type": "null" } ] }, "credited_cents": { "type": "integer", "minimum": 0 }, "payment_id": { "anyOf": [ { "type": "string", "pattern": "^pay_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "verified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "next_action": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "owner_checkout" }, "url": { "type": "string", "format": "uri", "pattern": "^https://" } }, "required": [ "type", "url" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "id", "status", "currency", "amount_cents", "service_fee_cents", "subtotal_cents", "charged_cents", "tax_cents", "payment_cost_cents", "checkout_url", "credited_cents", "payment_id", "verified_at", "created_at", "next_action", "note" ], "description": "Creating a top-up returns a hosted Whop payment link; it never charges a stored card. Give next_action.url to the owner. Poll this resource until funded, or explicitly reconcile. Do not infer payment from a checkout redirect. The actual charge may include provider costs or tax. No automatic top-up or recurring mandate exists." }, "BalanceTopupList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceTopup" } }, "next_cursor": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "items", "next_cursor" ] }, "OwnerSession": { "type": "object", "additionalProperties": false, "properties": { "configured": { "type": "boolean" }, "user": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" } }, "required": [ "id" ] }, { "type": "null" } ] }, "mode": { "type": "string", "const": "sandbox" } }, "required": [ "configured", "user", "mode" ] }, "ConsentRequest": { "type": "object", "additionalProperties": false, "properties": { "consent": { "type": "boolean", "const": true } }, "required": [ "consent" ] }, "ConsentRevoked": { "type": "object", "additionalProperties": false, "properties": { "consent_revoked": { "type": "boolean", "const": true } }, "required": [ "consent_revoked" ] }, "AdvertiserAssignmentRequest": { "type": "object", "additionalProperties": false, "properties": { "owner_id": { "type": "string", "format": "uuid" }, "facebook_social_account_id": { "type": "string", "pattern": "^sacc_[A-Za-z0-9]+$" }, "destination_origin": { "type": "string", "format": "uri", "pattern": "^https://", "description": "HTTPS origin only, no path, query, fragment or credentials. Trailing slash is accepted and normalized." }, "allocation_limit_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "enabled": { "type": "boolean", "default": false } }, "required": [ "owner_id", "facebook_social_account_id", "destination_origin", "allocation_limit_cents" ] }, "AdvertiserAssignment": { "type": "object", "additionalProperties": false, "properties": { "owner_id": { "type": "string", "format": "uuid" }, "destination_origin": { "type": "string", "format": "uri", "pattern": "^https://" }, "allocation_limit_cents": { "type": "integer", "minimum": 0 }, "enabled": { "type": "boolean" } }, "required": [ "owner_id", "destination_origin", "allocation_limit_cents", "enabled" ] }, "AdvertiserUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "owner_id": { "type": "string", "format": "uuid" }, "allocation_limit_cents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "enabled": { "type": "boolean" } }, "required": [ "owner_id" ], "anyOf": [ { "required": [ "allocation_limit_cents" ] }, { "required": [ "enabled" ] } ] }, "AdvertiserUpdated": { "type": "object", "additionalProperties": false, "properties": { "owner_id": { "type": "string", "format": "uuid" }, "destination_origin": { "type": "string", "format": "uri", "pattern": "^https://" }, "allocation_limit_cents": { "type": "integer", "minimum": 0 }, "enabled": { "type": "boolean" }, "reserved_cents": { "type": "integer", "minimum": 0 } }, "required": [ "owner_id", "destination_origin", "allocation_limit_cents", "enabled", "reserved_cents" ] }, "OperatorAdvertiser": { "type": "object", "additionalProperties": false, "properties": { "owner_id": { "type": "string", "format": "uuid" }, "facebook_social_account_id": { "type": "string", "pattern": "^sacc_[A-Za-z0-9]+$" }, "destination_origin": { "type": "string", "format": "uri", "pattern": "^https://" }, "allocation_limit_cents": { "type": "integer", "minimum": 0 }, "reserved_cents": { "type": "integer", "minimum": 0 }, "funded_cents": { "type": "integer", "minimum": 0 }, "funding_hold": { "type": "boolean" }, "enabled": { "type": "boolean" }, "consent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "owner_id", "facebook_social_account_id", "destination_origin", "allocation_limit_cents", "reserved_cents", "funded_cents", "funding_hold", "enabled", "consent_at" ] }, "OperatorStatus": { "type": "object", "additionalProperties": false, "properties": { "is_operator": { "type": "boolean", "const": true }, "owner_id": { "type": "string", "format": "uuid" }, "configured": { "type": "boolean" }, "account_id": { "anyOf": [ { "type": "string", "pattern": "^biz_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "environment": { "anyOf": [ { "type": "string", "enum": [ "production", "sandbox" ] }, { "type": "null" } ] }, "live_enabled": { "type": "boolean" }, "billing_enabled": { "type": "boolean" }, "checks": { "type": "object", "additionalProperties": false, "properties": { "social_accounts": { "type": "boolean" }, "campaign_read": { "type": "boolean" } }, "required": [ "social_accounts", "campaign_read" ] }, "social_accounts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^sacc_[A-Za-z0-9]+$" }, "name": { "type": "string" }, "can_advertise": { "type": "boolean" }, "needs_attention": { "type": "boolean" } }, "required": [ "id", "name", "can_advertise", "needs_attention" ] } }, "advertisers": { "type": "array", "items": { "$ref": "#/components/schemas/OperatorAdvertiser" } }, "truncated": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "is_operator", "owner_id", "configured", "account_id", "environment", "live_enabled", "billing_enabled", "checks", "social_accounts", "advertisers", "truncated", "status", "message" ], "description": "Operator-only inventory, never exposed to customer agents. Returns the latest 100 advertiser assignments and at most 1,000 Facebook identities; truncated identifies an incomplete social list." }, "AuthorizeUrl": { "type": "object", "additionalProperties": false, "properties": { "authorize_url": { "type": "string", "format": "uri", "pattern": "^https://" } }, "required": [ "authorize_url" ] }, "Capabilities": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "const": "MarketingRouter" }, "api_version": { "type": "string", "const": "2026-10-01" }, "mode": { "type": "string", "const": "sandbox" }, "supported_modes": { "type": "array", "items": { "type": "string", "enum": [ "sandbox", "live" ] } }, "base_url": { "type": "string", "format": "uri", "pattern": "^https?://", "description": "Current deployment URL. HTTPS in production; localhost development may use HTTP." }, "status": { "type": "string", "enum": [ "available", "setup_required" ] }, "live_spend_enabled": { "type": "boolean" }, "billing_enabled": { "type": "boolean" }, "objectives": { "type": "array", "items": { "type": "string", "enum": [ "purchase", "signup", "traffic" ] } }, "currencies": { "type": "array", "items": { "type": "string", "const": "USD" } }, "channels": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "const": "meta" }, "provider": { "type": "string", "const": "whop" }, "status": { "type": "string" }, "live_available": { "type": "boolean" } }, "required": [ "id", "provider", "status", "live_available" ] } }, "authentication": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "const": "bearer" }, "prefixes": { "type": "object", "additionalProperties": false, "properties": { "sandbox": { "type": "string", "const": "mr_test_" }, "live": { "type": "string", "const": "mr_live_" } }, "required": [ "sandbox", "live" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "campaigns:read", "campaigns:write", "events:write" ] } }, "owner_approval": { "type": "string", "const": "supabase_session" } }, "required": [ "type", "prefixes", "scopes", "owner_approval" ] }, "limits": { "type": "object", "additionalProperties": false, "properties": { "min_budget_cents": { "type": "integer", "minimum": 0 }, "max_budget_cents": { "type": "integer", "minimum": 0 }, "max_body_bytes": { "type": "integer", "minimum": 0 }, "max_creative_bytes": { "type": "integer", "minimum": 0 }, "min_schedule_hours": { "type": "integer", "minimum": 0 }, "max_schedule_days": { "type": "integer", "minimum": 0 } }, "required": [ "min_budget_cents", "max_budget_cents", "max_body_bytes", "max_creative_bytes", "min_schedule_hours", "max_schedule_days" ] }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } }, "discovery": { "type": "object", "additionalProperties": false, "properties": { "openapi": { "type": "string" }, "llms": { "type": "string" }, "docs": { "type": "string" }, "agent_manifest": { "type": "string" } }, "required": [ "openapi", "llms", "docs", "agent_manifest" ] }, "approval_required": { "type": "boolean", "const": true }, "live_requirements": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" } }, "required": [ "name", "api_version", "mode", "supported_modes", "base_url", "status", "live_spend_enabled", "billing_enabled", "objectives", "currencies", "channels", "authentication", "limits", "endpoints", "discovery", "approval_required", "live_requirements", "description" ] }, "QuoteResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Quote" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "CampaignResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Campaign" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "CampaignListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CampaignList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AssetResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Asset" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AssetListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AssetList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AssetUploadResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AssetUpload" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AdvertiserResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Advertiser" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "IntegrationsResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Integrations" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ResultsResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Results" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "EventReceiptResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/EventReceipt" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ActivityRecordResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ActivityRecord" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ActivityListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ActivityList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ApiKeyResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ApiKey" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ApiKeyCreatedResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ApiKeyCreated" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ApiKeyListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ApiKeyList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ApiKeyRevokedResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ApiKeyRevoked" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "FundingOrderResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FundingOrder" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "FundingListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/FundingList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BalanceEntryResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BalanceEntry" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BalanceResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Balance" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BalanceTopupResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BalanceTopup" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "BalanceTopupListResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/BalanceTopupList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "OwnerSessionResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OwnerSession" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "ConsentRevokedResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ConsentRevoked" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AdvertiserAssignmentResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AdvertiserAssignment" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AdvertiserUpdatedResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AdvertiserUpdated" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "OperatorAdvertiserResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OperatorAdvertiser" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "OperatorStatusResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/OperatorStatus" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "AuthorizeUrlResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/AuthorizeUrl" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "CapabilitiesResponse": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/Capabilities" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } } } }