{ "openapi": "3.1.0", "info": { "title": "AdPrompt X402 V2", "version": "1.1.0", "description": "Public x402 API for the full AdPrompt engine and bundle catalog. Paid endpoints return an x402 v2 402 challenge until a valid payment is supplied.", "contact": { "email": "support@adprompt.io" }, "x-guidance": "Use the product/bundle examples as valid probe bodies. Every paid route settles the x402 payment immediately and returns 202 with status: \"queued\", a report_url, and result_url (/results); engine work continues in the background. Use /v1/jobs/{job_id} to poll the asynchronous video product. Fetch report_url once the background work completes for the full result." }, "servers": [ { "url": "https://x402.adprompt.io", "description": "Hosted x402 gateway" } ], "tags": [ { "name": "System", "description": "Health, catalog, and launch metadata." }, { "name": "Profiles", "description": "Wallet-linked business profile resolution." }, { "name": "Products", "description": "Individually paid AdPrompt engines." }, { "name": "Bundles", "description": "Packaged multi-engine workflows at a fixed price." }, { "name": "Jobs", "description": "Asynchronous job polling." } ], "paths": { "/health": { "get": { "tags": [ "System" ], "summary": "Health check", "responses": { "200": { "description": "Gateway health", "content": { "application/json": { "examples": { "healthy": { "value": { "ok": true, "service": "adprompt-x402-gateway", "environment": "production", "payments_enforced": true, "network": "eip155:8453", "engine_base_url_configured": true, "store": "mongo" } } } } } } } } }, "/v1/catalog": { "get": { "tags": [ "System" ], "summary": "Get live catalog", "description": "Returns public product and bundle pricing. Internal execution details are not included.", "responses": { "200": { "description": "Public catalog", "content": { "application/json": { "examples": { "catalog": { "value": { "ok": true, "currency": "USD", "savedProfileReusePriceUsd": 0, "products": [ { "id": "brand_scan", "route": "/v1/brand-scan", "label": "Brand Scan", "basePriceUsd": 0.25, "requiresBusinessContext": false, "executionMode": "sync" } ], "bundles": [ { "id": "brand-intelligence", "route": "/v1/bundles/brand-intelligence", "label": "Brand Foundation", "priceUsd": 1 } ] } } } } } } } } }, "/x402scan.json": { "get": { "tags": [ "System" ], "summary": "Get x402scan launch metadata", "responses": { "200": { "description": "x402scan launch metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/x402scan.json": { "get": { "tags": [ "System" ], "summary": "Get well-known x402scan launch metadata", "responses": { "200": { "description": "x402scan launch metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/profiles/resolve": { "post": { "tags": [ "Profiles" ], "summary": "Resolve wallet business profile", "description": "Resolves a wallet-owned profile, asks the caller to select from multiple profiles, or asks for website/manual business context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResolveRequest" }, "examples": { "walletOnly": { "summary": "Wallet lookup", "value": { "wallet_address": "0x1111111111111111111111111111111111111111" } }, "explicitProfile": { "summary": "Specific saved profile", "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000" } } } } } }, "responses": { "200": { "description": "Resolved profile", "content": { "application/json": { "examples": { "resolved": { "value": { "ok": true, "status": "resolved", "profile": { "profile_id": "bp_01JZ0000000000000000000000", "name": "Example Business", "website": "https://example-business.com" }, "pricing": { "saved_profile_reuse_usd": 0 } } } } } } }, "409": { "description": "Business context is needed before execution", "content": { "application/json": { "examples": { "needsBusinessSelection": { "value": { "ok": false, "status": "needs_business_selection", "profiles": [ { "profile_id": "bp_01JZ0000000000000000000000", "name": "Example Business", "website": "https://example-business.com" } ] } }, "needsContext": { "value": { "ok": false, "status": "needs_context", "message": "Provide a website or manual business profile." } } } } } } } } }, "/v1/brand-scan": { "post": { "tags": [ "Products" ], "summary": "Brand Scan", "description": "Scans a website (or accepts manual details) and returns a reusable business profile, brand kit, and professional brand audit score.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandScanRequest" }, "examples": { "websiteScan": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "website": "https://example-business.com", "save_profile": true } } } } } }, "responses": { "202": { "description": "Payment settled; the scan is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "brand_scan", "label": "Brand Scan", "receipt_id": "rcpt_01JZ0000000000000000000000", "request_id": "req_01JZ0000000000000000000000", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000000/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/competitive-analysis": { "post": { "tags": [ "Products" ], "summary": "Competitive Analysis", "description": "Returns competitor positioning, differentiation opportunities, and recommended market actions.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessContextRequest" }, "examples": { "savedProfile": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000" } }, "manualProfile": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "manual_business_profile": { "name": "Example Business", "website": "https://example-business.com", "industry": "Retail" } } } } } } }, "responses": { "202": { "description": "Payment settled; the analysis is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "competitive_analysis", "label": "Competitive Analysis", "receipt_id": "rcpt_01JZ0000000000000000000001", "request_id": "req_01JZ0000000000000000000001", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000001/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/ad-strategy": { "post": { "tags": [ "Products" ], "summary": "Ad Strategy + Budget", "description": "Builds channel strategy, audience targeting, creative angles, and budget allocation guidance.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.5" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdStrategyRequest" }, "examples": { "savedProfile": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000", "monthly_budget_usd": 2500, "goal": "Generate qualified local leads" } } } } } }, "responses": { "202": { "description": "Payment settled; the strategy is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "ad_strategy_budget", "label": "Ad Strategy + Budget", "receipt_id": "rcpt_01JZ0000000000000000000002", "request_id": "req_01JZ0000000000000000000002", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000002/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/images/generate": { "post": { "tags": [ "Products" ], "summary": "Image Generation", "description": "Generates one branded campaign image from a prompt and business context. $0.50 flat.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.5" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" }, "examples": { "singleImage": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000", "prompt": "Create a clean square launch ad for a neighborhood coffee shop." } } } } } }, "responses": { "202": { "description": "Payment settled; image generation is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "image_generation", "label": "Image Generator", "receipt_id": "rcpt_01JZ0000000000000000000003", "request_id": "req_01JZ0000000000000000000003", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000003/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/videos/generate": { "post": { "tags": [ "Products" ], "summary": "Video Generation", "description": "Creates an 8-second campaign video. The endpoint returns an asynchronous job id.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "2" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Recommended for safe retries. Reusing the same key and body returns the original job." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoGenerationRequest" }, "examples": { "standardVideo": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000", "prompt": "Create an 8 second launch teaser for a seasonal coffee menu.", "duration_seconds": 8 } } } } } }, "responses": { "202": { "description": "Paid video job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAcceptedResponse" }, "examples": { "accepted": { "value": { "ok": true, "product_id": "video_generation_8s", "receipt_id": "rcpt_01JZ0000000000000000000004", "price_usd": 2, "job_id": "job_01JZ0000000000000000000000", "polling_url": "/v1/jobs/job_01JZ0000000000000000000000", "metadata": { "request_id": "req_01JZ0000000000000000000004", "payments_enforced": true, "x402_version": 2, "creative": { "duration_seconds": 8, "tier": "standard" } } } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "description": "Idempotency key conflict", "content": { "application/json": { "examples": { "conflict": { "value": { "ok": false, "error": "idempotency_key_conflict", "message": "This Idempotency-Key was already used with a different request body.", "job_id": "job_01JZ0000000000000000000000" } } } } } } } } }, "/v1/jobs/{job_id}": { "get": { "tags": [ "Jobs" ], "summary": "Poll job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status and result when available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" }, "examples": { "succeeded": { "value": { "ok": true, "job": { "job_id": "job_01JZ0000000000000000000000", "status": "succeeded", "product_id": "video_generation_8s", "receipt_id": "rcpt_01JZ0000000000000000000004", "result": { "video": { "url": "https://cdn.example.com/generated/video.mp4", "duration_seconds": 8 } }, "timestamps": { "created_at": "2026-08-04T00:00:00.000Z", "completed_at": "2026-08-04T00:01:00.000Z" } } } } } } } }, "404": { "description": "Job not found" } } } }, "/v1/social-presence-plan": { "post": { "tags": [ "Products" ], "summary": "Social Presence Plan", "description": "Explains where the business should show up socially and lays out a concrete posting and engagement plan.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialPresencePlanRequest" }, "examples": { "savedProfile": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000" } } } } } }, "responses": { "202": { "description": "Payment settled; the plan is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "social_presence_full_plan", "label": "Social Presence Full Plan", "receipt_id": "rcpt_01JZ0000000000000000000005", "request_id": "req_01JZ0000000000000000000005", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000005/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/logos/generate": { "post": { "tags": [ "Products" ], "summary": "Logo Generation", "description": "Generates a batch of 3 logo concepts. $1.00 flat.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoGenerationRequest" }, "examples": { "defaultBatch": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000" } } } } } }, "responses": { "202": { "description": "Payment settled; logo generation is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "logo_generation", "label": "Logo Generation", "receipt_id": "rcpt_01JZ0000000000000000000006", "request_id": "req_01JZ0000000000000000000006", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000006/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/content/suggest": { "post": { "tags": [ "Products" ], "summary": "Content Ideas", "description": "Generates a batch of 3+ content ideas. $0.50 flat.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.5" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentSuggestorRequest" }, "examples": { "defaultBatch": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000" } } } } } }, "responses": { "202": { "description": "Payment settled; content ideas are queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "content_suggestor", "label": "Content Suggestor", "receipt_id": "rcpt_01JZ0000000000000000000007", "request_id": "req_01JZ0000000000000000000007", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000007/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/colors/generate": { "post": { "tags": [ "Products" ], "summary": "Brand Color Palettes", "description": "Generates a batch of 3 brand color palettes. $0.25 flat.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.25" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ColorPaletteRequest" }, "examples": { "defaultBatch": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000" } } } } } }, "responses": { "202": { "description": "Payment settled; palette generation is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedProductResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "product_id": "color_palette_generator", "label": "Color Palette Generator", "receipt_id": "rcpt_01JZ0000000000000000000008", "request_id": "req_01JZ0000000000000000000008", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000008/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bundles/brand-intelligence": { "post": { "tags": [ "Bundles" ], "summary": "Brand Foundation", "description": "Fresh Brand Scan, Competitive Analysis, Social Presence Plan, and Color Palettes at a fixed package price.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRequest" }, "examples": { "websiteScan": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "website": "https://example-business.com" } } } } } }, "responses": { "202": { "description": "Payment settled; every step in the bundle is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedBundleResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "bundle_id": "brand-intelligence", "label": "Brand Foundation", "receipt_id": "rcpt_01JZ0000000000000000000009", "request_id": "req_01JZ0000000000000000000009", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ0000000000000000000009/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bundles/brand-starter": { "post": { "tags": [ "Bundles" ], "summary": "Brand Starter", "description": "Fresh Brand Scan, Logo Generation, Color Palettes, Competitive Analysis, and Content Ideas at a fixed package price.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "2" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRequest" }, "examples": { "websiteScan": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "website": "https://example-business.com" } } } } } }, "responses": { "202": { "description": "Payment settled; every step in the bundle is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedBundleResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "bundle_id": "brand-starter", "label": "Brand Starter", "receipt_id": "rcpt_01JZ000000000000000000000A", "request_id": "req_01JZ000000000000000000000A", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ000000000000000000000A/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bundles/social-image-pack": { "post": { "tags": [ "Bundles" ], "summary": "Social Media Image", "description": "One platform-sized campaign image plus a written caption and hashtags, at a fixed package price. Business context optional.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "1" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRequest" }, "examples": { "noBusinessContext": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "prompt": "A cozy neighborhood coffee shop announcing a new seasonal menu.", "social_platform": "instagram" } } } } } }, "responses": { "202": { "description": "Payment settled; every step in the bundle is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedBundleResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "bundle_id": "social-image-pack", "label": "Social Media Image", "receipt_id": "rcpt_01JZ000000000000000000000B", "request_id": "req_01JZ000000000000000000000B", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ000000000000000000000B/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bundles/social-video-pack": { "post": { "tags": [ "Bundles" ], "summary": "Social Media Video", "description": "One platform-sized 8-second campaign video plus a written caption and hashtags, at a fixed package price. Business context optional.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "2.5" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRequest" }, "examples": { "noBusinessContext": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "prompt": "A cozy neighborhood coffee shop announcing a new seasonal menu.", "social_platform": "youtube" } } } } } }, "responses": { "202": { "description": "Payment settled; every step in the bundle is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedBundleResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "bundle_id": "social-video-pack", "label": "Social Media Video", "receipt_id": "rcpt_01JZ000000000000000000000C", "request_id": "req_01JZ000000000000000000000C", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ000000000000000000000C/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bundles/campaign-strategy-image": { "post": { "tags": [ "Bundles" ], "summary": "Ad Campaign Planning", "description": "Channel strategy and budget allocation plus one ad image per recommended platform, at a fixed package price.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "2" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRequest" }, "examples": { "savedProfile": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "profile_id": "bp_01JZ0000000000000000000000", "monthly_budget_usd": 2500, "goal": "Generate qualified local leads" } } } } } }, "responses": { "202": { "description": "Payment settled; every step in the bundle is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedBundleResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "bundle_id": "campaign-strategy-image", "label": "Ad Campaign Planning", "receipt_id": "rcpt_01JZ000000000000000000000D", "request_id": "req_01JZ000000000000000000000D", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ000000000000000000000D/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bundles/campaign-strategy-video": { "post": { "tags": [ "Bundles" ], "summary": "Advanced Ad Campaign Planning", "description": "Fresh Brand Scan, channel strategy and budget allocation, platform ad images, and two 8-second videos (landscape and portrait), at a fixed package price.", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "5" }, "protocols": [ { "x402": {} } ] }, "security": [ { "x402Payment": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRequest" }, "examples": { "websiteScan": { "value": { "wallet_address": "0x1111111111111111111111111111111111111111", "website": "https://example-business.com", "monthly_budget_usd": 2500, "goal": "Generate qualified local leads" } } } } } }, "responses": { "202": { "description": "Payment settled; every step in the bundle is queued and running in the background", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedBundleResponse" }, "examples": { "queued": { "value": { "ok": true, "status": "queued", "bundle_id": "campaign-strategy-video", "label": "Advanced Ad Campaign Planning", "receipt_id": "rcpt_01JZ000000000000000000000E", "request_id": "req_01JZ000000000000000000000E", "result_url": "/results", "report_url": "/v1/wallet/results/req_01JZ000000000000000000000E/report?wallet_address=0x1111111111111111111111111111111111111111" } } } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/wallet/results": { "get": { "tags": [ "Wallet Results" ], "summary": "List wallet-owned results", "description": "Returns saved business profiles, paid request results, pending jobs, failed calls, receipts, and report links for the connected wallet address.", "parameters": [ { "name": "wallet_address", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet dashboard data" }, "400": { "description": "Missing wallet address" } } } }, "/v1/wallet/profiles/{profile_id}": { "patch": { "tags": [ "Wallet Results" ], "summary": "Update wallet-owned business profile", "description": "Updates the saved business profile fields used as engine context. The profile_id must belong to the wallet address.", "parameters": [ { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "wallet_address": "0x1111111111111111111111111111111111111111", "manual_business_profile": { "name": "Example Business", "website": "https://example.com", "phone": "+1 555 0100", "address": "100 Main St", "industry": "Marketing AI", "category": "SaaS / Marketing", "summary": "Updated business context." } } } } }, "responses": { "200": { "description": "Updated profile" }, "404": { "description": "Profile not owned by wallet" } } } }, "/v1/wallet/results/{result_id}/report": { "get": { "tags": [ "Wallet Results" ], "summary": "Printable AdPrompt result report", "description": "Returns an AdPrompt-branded printable HTML report for a wallet-owned result. Browser print can be used to save as PDF.", "parameters": [ { "name": "result_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "wallet_address", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Printable report HTML" }, "404": { "description": "Result not found for wallet" } } } } }, "components": { "securitySchemes": { "x402Payment": { "type": "apiKey", "in": "header", "name": "X-PAYMENT", "description": "x402 payment payload supplied by a compatible client after reading the 402 Payment Required challenge." } }, "responses": { "PaymentRequired": { "description": "x402 v2 payment challenge. The PAYMENT-REQUIRED header contains the machine-readable x402 accept terms.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 v2 payment challenge.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequiredBody" }, "examples": { "brandScan": { "value": { "ok": false, "error": "payment_required", "message": "Payment is required before this product can be executed.", "x402Version": 2, "route": "/v1/brand-scan", "product_id": "brand_scan", "label": "Brand Scan", "price_usd": 0.25, "quote": { "type": "product", "id": "brand_scan", "route": "/v1/brand-scan", "label": "Brand Scan", "priceUsd": 0.25, "executionMode": "sync", "requiresBusinessContext": false, "lineItems": [ { "id": "brand_scan", "label": "Brand Scan", "quantity": 1, "priceUsd": 0.25 } ] } } } } } } } }, "schemas": { "ProfileResolveRequest": { "type": "object", "properties": { "wallet_address": { "type": "string", "description": "Caller wallet address." }, "profile_id": { "type": "string", "description": "Optional saved profile id to verify against wallet ownership." }, "website": { "type": "string", "format": "uri", "description": "Website to scan when creating or refreshing profile context." }, "manual_business_profile": { "type": "object", "description": "Caller-supplied business context." }, "save_profile": { "type": "boolean", "description": "Whether to save manual context after resolution." }, "create_new_profile": { "type": "boolean", "description": "Explicitly create a new business profile even if wallet profiles already exist." } } }, "BrandScanRequest": { "type": "object", "properties": { "wallet_address": { "type": "string" }, "website": { "type": "string", "format": "uri", "description": "Business website for ProfileFromUrls. Optional when manual_business_profile or profile_id is provided." }, "manual_business_profile": { "type": "object", "description": "Manual business details for ProfileFromInputs when no website is available." }, "save_profile": { "type": "boolean", "default": true, "description": "Deprecated for Brand Scan. Successful Brand Scan results always upsert the wallet profile." }, "profile_id": { "type": "string", "description": "Optional existing profile id to refresh after payment." } }, "anyOf": [ { "required": ["website"] }, { "required": ["manual_business_profile"] }, { "required": ["profile_id"] } ] }, "BusinessContextRequest": { "type": "object", "properties": { "wallet_address": { "type": "string" }, "profile_id": { "type": "string" }, "website": { "type": "string", "format": "uri", "description": "If no profile is available, this adds a required paid Brand Scan." }, "manual_business_profile": { "type": "object" }, "save_profile": { "type": "boolean" } }, "anyOf": [ { "required": [ "profile_id" ] }, { "required": [ "website" ] }, { "required": [ "manual_business_profile" ] } ] }, "AdStrategyRequest": { "allOf": [ { "$ref": "#/components/schemas/BusinessContextRequest" }, { "type": "object", "properties": { "goal": { "type": "string" }, "monthly_budget_usd": { "type": "number", "minimum": 0 } } } ] }, "ImageGenerationRequest": { "allOf": [ { "$ref": "#/components/schemas/BusinessContextRequest" }, { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1 } } } ] }, "VideoGenerationRequest": { "allOf": [ { "$ref": "#/components/schemas/BusinessContextRequest" }, { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "minLength": 1 }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 8, "default": 8 } } } ] }, "SocialPresencePlanRequest": { "$ref": "#/components/schemas/BusinessContextRequest" }, "LogoGenerationRequest": { "allOf": [ { "$ref": "#/components/schemas/BusinessContextRequest" }, { "type": "object", "properties": { "logo_style": { "type": "string" } } } ] }, "ContentSuggestorRequest": { "allOf": [ { "$ref": "#/components/schemas/BusinessContextRequest" }, { "type": "object", "properties": { "objective": { "type": "string" } } } ] }, "ColorPaletteRequest": { "$ref": "#/components/schemas/BusinessContextRequest" }, "BundleRequest": { "allOf": [ { "$ref": "#/components/schemas/BusinessContextRequest" }, { "type": "object", "properties": { "prompt": { "type": "string", "description": "Creative brief for bundles that include image or video generation." }, "social_platform": { "type": "string", "description": "Used by the social image/video packs to size and frame the creative." }, "goal": { "type": "string" }, "monthly_budget_usd": { "type": "number", "minimum": 0 } } } ] }, "PaymentRequiredBody": { "type": "object", "required": [ "ok", "error", "x402Version", "price_usd", "quote" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "const": "payment_required" }, "message": { "type": "string" }, "x402Version": { "type": "integer", "const": 2 }, "route": { "type": "string" }, "product_id": { "type": "string" }, "label": { "type": "string" }, "price_usd": { "type": "number" }, "quote": { "$ref": "#/components/schemas/Quote" } } }, "Quote": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "route": { "type": "string" }, "label": { "type": "string" }, "priceUsd": { "type": "number" }, "executionMode": { "type": "string", "enum": [ "sync", "async" ] }, "requiresBusinessContext": { "type": "boolean" }, "requiresBrandScan": { "type": "boolean" }, "lineItems": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": true }, "PaidProductResponse": { "type": "object", "required": [ "ok", "product_id", "receipt_id", "price_usd", "metadata", "result" ], "properties": { "ok": { "type": "boolean", "const": true }, "product_id": { "type": "string" }, "receipt_id": { "type": "string" }, "price_usd": { "type": "number" }, "quote": { "$ref": "#/components/schemas/Quote" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" }, "saved_profile": { "$ref": "#/components/schemas/PublicProfile" }, "result": { "type": "object" } } }, "QueuedProductResponse": { "type": "object", "required": [ "ok", "status", "product_id", "receipt_id", "request_id", "result_url", "report_url" ], "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "const": "queued" }, "product_id": { "type": "string" }, "label": { "type": "string" }, "receipt_id": { "type": "string" }, "request_id": { "type": "string" }, "job_id": { "type": "string", "description": "Present only for the asynchronous video product." }, "polling_url": { "type": "string", "description": "Present only for the asynchronous video product." }, "result_url": { "type": "string", "const": "/results" }, "report_url": { "type": "string", "description": "Fetch this once background processing completes for the full AdPrompt-branded report." }, "adprompt_signature": { "type": "object" }, "business_context": { "type": "object" }, "saved_profile": { "$ref": "#/components/schemas/PublicProfile" } } }, "QueuedBundleResponse": { "type": "object", "required": [ "ok", "status", "bundle_id", "receipt_id", "request_id", "result_url", "report_url" ], "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "string", "const": "queued" }, "bundle_id": { "type": "string" }, "label": { "type": "string" }, "receipt_id": { "type": "string" }, "request_id": { "type": "string" }, "result_url": { "type": "string", "const": "/results" }, "report_url": { "type": "string", "description": "Fetch this once every step in the bundle has finished running for the compiled report." }, "adprompt_signature": { "type": "object" } } }, "AsyncJobAcceptedResponse": { "type": "object", "required": [ "ok", "product_id", "receipt_id", "price_usd", "job_id", "polling_url", "metadata" ], "properties": { "ok": { "type": "boolean", "const": true }, "product_id": { "type": "string" }, "receipt_id": { "type": "string" }, "price_usd": { "type": "number" }, "job_id": { "type": "string" }, "polling_url": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/ResponseMetadata" } } }, "JobStatusResponse": { "type": "object", "required": [ "ok", "job" ], "properties": { "ok": { "type": "boolean", "const": true }, "job": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "product_id": { "type": "string" }, "receipt_id": { "type": "string" }, "result": { "type": "object" }, "error": { "type": "object" }, "timestamps": { "type": "object" } } } } }, "ResponseMetadata": { "type": "object", "properties": { "request_id": { "type": "string" }, "payments_enforced": { "type": "boolean" }, "x402_version": { "type": "integer" }, "business_context": { "type": "object" }, "creative": { "type": "object" } }, "additionalProperties": true }, "PublicProfile": { "type": "object", "properties": { "profile_id": { "type": "string" }, "name": { "type": "string" }, "website": { "type": "string", "format": "uri" } }, "additionalProperties": true } } } }