{ "openapi": "3.1.0", "info": { "title": "Neuron Sports Ad Exchange API", "description": "Autonomous sports advertising exchange with DYNAMIC PRICING. Agents calculate any price based on sport, format, impressions, and volume discounts, then POST to the Dynamic Checkout endpoint to generate a live Stripe checkout session for the exact calculated amount. No fixed prices — the machine decides the price, Stripe collects it.", "version": "1.1.0", "contact": { "name": "Neuron Systems Inc.", "email": "support@neuronsystems.org", "url": "https://neuronsystems.org/sponsor" }, "termsOfService": "https://neuronsystems.org/terms", "x-stripe-merchant": "@neuronsystems", "x-dynamic-pricing": true }, "servers": [ { "url": "https://neuronsystems.org", "description": "Production — Static feeds" }, { "url": "https://us-central1-neuronsystems-791c5.cloudfunctions.net", "description": "Production — Dynamic Stripe Checkout API (Google Cloud Functions)" } ], "paths": { "/createDynamicCheckoutSession": { "post": { "operationId": "createDynamicCheckoutSession", "summary": "Generate a dynamic Stripe checkout session for any calculated price", "description": "THE PRIMARY PAYMENT ENDPOINT. Agents calculate a price (any USD amount) based on sport, format, impressions, and volume discounts, then POST here to generate a live Stripe checkout session URL. The session is created with the exact amount — no fixed tiers. Returns a checkout.stripe.com URL that the buyer agent or human can open to pay immediately. Settlement goes directly to @neuronsystems.", "servers": [ { "url": "https://us-central1-neuronsystems-791c5.cloudfunctions.net", "description": "Google Cloud Functions" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountUSD": { "type": "number", "description": "The dynamically calculated price in USD (e.g., 166.32, 247.50, 89.99). Any positive number.", "example": 166.32 }, "slotTitle": { "type": "string", "description": "Human-readable title for the Stripe line item (e.g., 'Halftime Music Show — NFL Week 4 Chiefs vs Raiders').", "example": "Halftime Music Show — NFL Week 4" }, "format": { "type": "string", "enum": ["leaderboard_728x90", "medium_rectangle_300x250", "mobile_banner_320x50", "voice_sponsor_read", "pregame_anthem_slot", "halftime_music_show"], "description": "Ad format type." }, "sport": { "type": "string", "enum": ["gridiron", "fiba", "starsofsoccer", "fnba", "pitwall", "fifa", "nba"], "description": "Target sport." }, "tenderId": { "type": "string", "description": "Optional tender ID if booking against a specific open tender." }, "customerEmail": { "type": "string", "format": "email", "description": "Optional buyer email for Stripe receipt." }, "metadata": { "type": "object", "description": "Optional key-value metadata attached to the Stripe session (brand name, campaign ID, agent ID, etc.).", "additionalProperties": { "type": "string" } } }, "required": ["amountUSD", "slotTitle", "format", "sport"] }, "examples": { "halftime_dynamic": { "summary": "Book a halftime show at a dynamically calculated price", "value": { "amountUSD": 127.50, "slotTitle": "Halftime Music Show — NFL Week 5 Eagles vs Cowboys", "format": "halftime_music_show", "sport": "gridiron", "metadata": { "brand": "Indie Records", "agent_id": "buyer-agent-001" } } }, "banner_dynamic": { "summary": "Book a leaderboard banner at calculated CPM price", "value": { "amountUSD": 203.44, "slotTitle": "Leaderboard Banner — WNBA Playoffs Game 3", "format": "leaderboard_728x90", "sport": "fnba" } } } } } }, "responses": { "200": { "description": "Stripe checkout session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "format": "uri", "description": "Live Stripe checkout URL. Open this to pay the exact calculated amount.", "example": "https://checkout.stripe.com/c/pay/cs_live_..." }, "sessionId": { "type": "string", "description": "Stripe session ID for tracking.", "example": "cs_live_a1B2c3D4e5F6..." }, "amountUSD": { "type": "number", "description": "The amount that will be charged.", "example": 166.32 }, "merchant": { "type": "string", "description": "Stripe merchant handle.", "example": "@neuronsystems" } } } } } }, "400": { "description": "Invalid request — missing required fields or invalid amount" }, "500": { "description": "Server error — Stripe session creation failed" } } } }, "/api/open-tenders.json": { "get": { "operationId": "listOpenTenders", "summary": "List open advertising tenders with floor prices", "description": "Returns open, discounted sports advertising tenders. Use the floor CPMs and impression counts to CALCULATE a dynamic price, then POST to /createDynamicCheckoutSession to generate a Stripe checkout for that exact amount.", "responses": { "200": { "description": "Array of open tenders with pricing data for dynamic calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "total_open_tenders": { "type": "integer", "example": 27 }, "tenders": { "type": "array", "items": { "type": "object", "properties": { "tender_id": { "type": "string" }, "sport": { "type": "string" }, "format": { "type": "string" }, "slot_title": { "type": "string" }, "vacant_impressions": { "type": "integer" }, "floor_cpm_usd": { "type": "number" }, "discounted_cpm_usd": { "type": "number" }, "flash_discount_pct": { "type": "number" }, "estimated_total_usd": { "type": "number" }, "kickoff_time": { "type": "string", "format": "date-time" }, "urgency_level": { "type": "string", "enum": ["low", "medium", "high", "critical"] } } } } } } } } } } } }, "/api/ad-inventory.json": { "get": { "operationId": "getAdInventoryCatalog", "summary": "Get ad format catalog with CPM floors for dynamic price calculation", "description": "Returns the complete ad format catalog with CPM floors. Use these base rates to calculate dynamic prices based on impressions, urgency, and volume discounts, then POST to /createDynamicCheckoutSession.", "responses": { "200": { "description": "Ad inventory catalog with CPM floors", "content": { "application/json": { "schema": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "cpm_floor_usd": { "type": "number" }, "description": { "type": "string" } } } }, "sports": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/open-tenders.xml": { "get": { "operationId": "listOpenTendersRss", "summary": "Open tenders RSS feed", "description": "RSS 2.0 feed of open advertising tenders for feed readers and autonomous agents that consume XML.", "responses": { "200": { "description": "RSS 2.0 XML feed", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": {}, "securitySchemes": {} }, "security": [], "externalDocs": { "description": "MCP Server Card (Model Context Protocol) — 6 tools including dynamic pricing", "url": "https://neuronsystems.org/.well-known/mcp/server-card.json" } }