{"components":{"schemas":{"AssetRequirement":{"properties":{"height":{"type":"integer"},"key":{"enum":["desktop","mobile"],"type":"string"},"width":{"type":"integer"}},"required":["key","width","height"],"type":"object"},"Campaign":{"properties":{"billing_issue":{"type":"string"},"cancel_at_period_end":{"type":"boolean"},"checkout_enabled":{"type":"boolean"},"clicks":{"minimum":0,"type":"integer"},"desktop_url":{"type":"string"},"display_active":{"type":"boolean"},"email":{"format":"email","type":"string"},"id":{"type":"string"},"impressions":{"minimum":0,"type":"integer"},"mobile_url":{"nullable":true,"type":"string"},"name":{"type":"string"},"next_action":{"$ref":"#/components/schemas/NextAction"},"paid_until":{"description":"Unix seconds, UTC. Zero/null means no paid period.","nullable":true,"type":"number"},"pending_revision":{"allOf":[{"$ref":"#/components/schemas/Creative"}],"nullable":true},"review_note":{"type":"string"},"review_status":{"enum":["pending","approved","rejected"],"type":"string"},"revision_pending":{"type":"boolean"},"slot_id":{"enum":["left","right","bottom"],"type":"string"},"status":{"enum":["pending","approved","rejected","checkout","active","payment_due","ended","suspended"],"type":"string"},"url":{"type":"string"}},"required":["id","slot_id","review_status","status","paid_until","display_active","next_action","checkout_enabled"],"type":"object"},"CampaignResponse":{"properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}},"required":["campaign"],"type":"object"},"Capabilities":{"properties":{"discovery":{"properties":{"agent_guide_url":{"format":"uri","type":"string"},"catalog_url":{"format":"uri","type":"string"},"guide_url":{"format":"uri","type":"string"},"openapi_url":{"format":"uri","type":"string"},"traffic_url":{"format":"uri","type":"string"}},"required":["openapi_url","guide_url","agent_guide_url","catalog_url","traffic_url"],"type":"object"},"payment":{"properties":{"amount_cents":{"type":"integer"},"cancellation":{"type":"string"},"currency":{"type":"string"},"interval":{"type":"string"},"method":{"type":"string"},"owner_authorization_required":{"type":"boolean"},"programmatic_payment":{"type":"boolean"},"renews_automatically":{"type":"boolean"}},"required":["method","programmatic_payment","owner_authorization_required","renews_automatically"],"type":"object"},"poll_interval_seconds":{"minimum":60,"type":"integer"},"review":{"properties":{"before_payment":{"type":"boolean"},"mode":{"type":"string"},"replacements_require_review":{"type":"boolean"},"required":{"type":"boolean"}},"required":["required","mode","before_payment"],"type":"object"},"version":{"type":"string"}},"required":["version","payment","review","discovery","poll_interval_seconds"],"type":"object"},"Catalog":{"properties":{"capabilities":{"$ref":"#/components/schemas/Capabilities"},"checkout_enabled":{"type":"boolean"},"slots":{"items":{"$ref":"#/components/schemas/Slot"},"type":"array"},"traffic":{"$ref":"#/components/schemas/Traffic"}},"required":["slots","checkout_enabled","capabilities","traffic"],"type":"object"},"CheckoutResponse":{"properties":{"expires_at":{"description":"Unix seconds, UTC. Zero/null means no paid period.","nullable":true,"type":"number"},"url":{"type":"string"}},"required":["url"],"type":"object"},"Creative":{"properties":{"desktop_url":{"type":"string"},"id":{"type":"string"},"mobile_url":{"nullable":true,"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"required":["id","name","url","desktop_url"],"type":"object"},"Error":{"properties":{"code":{"type":"string"},"error":{"type":"string"},"retry_after_seconds":{"nullable":true,"type":"integer"}},"required":["error","code"],"type":"object"},"NextAction":{"properties":{"actor":{"enum":["agent","publisher","payer"],"type":"string"},"method":{"enum":["GET","POST",null],"nullable":true,"type":"string"},"poll_after_seconds":{"nullable":true,"type":"integer"},"type":{"enum":["await_review","revise_submission","create_checkout","complete_checkout","await_payment","manage_active_campaign","resolve_payment","contact_support","campaign_ended"],"type":"string"},"url":{"nullable":true,"type":"string"}},"required":["type","actor","url","method","poll_after_seconds"],"type":"object"},"PortalResponse":{"properties":{"url":{"format":"uri","type":"string"}},"required":["url"],"type":"object"},"PublicCampaign":{"properties":{"click_url":{"type":"string"},"desktop_url":{"type":"string"},"id":{"type":"string"},"impression_url":{"type":"string"},"mobile_url":{"nullable":true,"type":"string"},"name":{"type":"string"}},"required":["id","name","click_url","desktop_url","impression_url"],"type":"object"},"Slot":{"properties":{"assets":{"items":{"$ref":"#/components/schemas/AssetRequirement"},"type":"array"},"available_at":{"description":"Current reservation/paid-period end; may renew. Not a guaranteed future availability date.","nullable":true,"type":"number"},"campaign":{"allOf":[{"$ref":"#/components/schemas/PublicCampaign"}],"nullable":true},"currency":{"enum":["usd"],"type":"string"},"height":{"type":"integer"},"id":{"enum":["left","right","bottom"],"type":"string"},"interval":{"enum":["month"],"type":"string"},"name":{"type":"string"},"price_cents":{"enum":[10000],"type":"integer"},"reservation_reason":{"enum":["checkout","renewal",null],"nullable":true,"type":"string"},"status":{"enum":["available","reserved","booked"],"type":"string"},"width":{"type":"integer"}},"required":["id","name","assets","price_cents","currency","interval","status","campaign"],"type":"object"},"SubmissionResponse":{"properties":{"campaign":{"$ref":"#/components/schemas/Campaign"},"manage_url":{"description":"Private owner link containing its token in the URL fragment.","type":"string"},"token":{"description":"Secret campaign bearer token; keep private.","type":"string"}},"required":["campaign","token","manage_url"],"type":"object"},"Traffic":{"properties":{"automatic_refresh":{"description":"False means a manually published snapshot pending automatic refresh setup. Always check status and updated_at.","type":"boolean"},"daily":{"items":{"$ref":"#/components/schemas/TrafficDay"},"type":"array"},"daily_average":{"nullable":true,"properties":{"page_views":{"minimum":0,"type":"number"},"response_bytes":{"minimum":0,"type":"number"}},"required":["page_views","response_bytes"],"type":"object"},"refresh_interval_seconds":{"type":"integer"},"source":{"properties":{"dataset":{"type":"string"},"documentation_url":{"type":"string"},"includes_automated_traffic":{"type":"boolean"},"page_views_definition":{"type":"string"},"provider":{"type":"string"},"response_bytes_definition":{"type":"string"},"scope":{"type":"string"}},"required":["provider","dataset","scope","includes_automated_traffic","page_views_definition","response_bytes_definition","documentation_url"],"type":"object"},"stale_after_seconds":{"type":"integer"},"status":{"enum":["current","stale","unavailable"],"type":"string"},"totals":{"nullable":true,"properties":{"page_views":{"minimum":0,"type":"integer"},"response_bytes":{"minimum":0,"type":"integer"}},"required":["page_views","response_bytes"],"type":"object"},"updated_at":{"format":"date-time","nullable":true,"type":"string"},"window":{"nullable":true,"properties":{"days":{"enum":[30],"type":"integer"},"end":{"description":"Inclusive final completed UTC day.","format":"date","type":"string"},"start":{"format":"date","type":"string"},"timezone":{"enum":["UTC"],"type":"string"}},"required":["start","end","days","timezone"],"type":"object"}},"required":["status","source","updated_at","window","totals","daily_average","daily","automatic_refresh","refresh_interval_seconds","stale_after_seconds"],"type":"object"},"TrafficDay":{"properties":{"date":{"format":"date","type":"string"},"page_views":{"minimum":0,"type":"integer"},"response_bytes":{"minimum":0,"type":"integer"}},"required":["date","page_views","response_bytes"],"type":"object"}},"securitySchemes":{"campaignKey":{"description":"Private token returned on submission. Send only to this origin, never in query strings.","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"Agent purchase and management workflow","url":"https://spacedownloader.io/advertise/agent-guide.txt"},"info":{"description":"Three exclusive reviewed image placements, $100USD each per calendar month. Auto-renews until canceled. Human review before first payment; hosted Stripe Checkout with owner authorization. Payment confirmation automatically publishes approved ads. Agent workflow: discover, submit, poll next_action, checkout, verify display_active, manage. No card/SPT/MPP endpoint.","title":"SpaceDownloader Sponsorship API","version":"1.2.0"},"openapi":"3.0.3","paths":{"/api/sponsors/campaigns":{"post":{"operationId":"submitCampaign","parameters":[{"description":"Private random UUID per submission. Reuse only for identical retries.","in":"header","name":"Idempotency-Key","schema":{"maxLength":200,"minLength":16,"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"desktop":{"description":"Static PNG/JPEG/WebP <=1048576bytes;160x300 rails or728x90 bottom.","format":"binary","type":"string"},"email":{"format":"email","type":"string"},"mobile":{"description":"Required for bottom:320x50 static PNG/JPEG/WebP <=1048576bytes.","format":"binary","type":"string"},"name":{"maxLength":100,"minLength":2,"type":"string"},"slot_id":{"enum":["left","right","bottom"],"type":"string"},"url":{"description":"Public HTTPS destination, subject to human review.","format":"uri","type":"string"}},"required":["name","url","desktop","slot_id","email"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionResponse"}}},"description":"Save the campaign token privately. Follow campaign.next_action."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing/invalid campaign key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cross-origin request rejected"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Campaign or action not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Refresh state; slot or review state changed"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Upload too large"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wait before retrying"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment result uncertain; poll same campaign before retrying"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unavailable"}},"summary":"Upload for human review before payment; no account needed."}},"/api/sponsors/campaigns/{campaign_id}":{"get":{"operationId":"getCampaign","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignResponse"}}},"description":"Campaign state; display_active confirms current publication."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing/invalid campaign key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cross-origin request rejected"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Campaign or action not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Refresh state; slot or review state changed"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Upload too large"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wait before retrying"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment result uncertain; poll same campaign before retrying"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unavailable"}},"security":[{"campaignKey":[]}],"summary":"Poll review/payment/publication state and approximate metrics at most once per minute."}},"/api/sponsors/campaigns/{campaign_id}/cancel":{"post":{"operationId":"cancelCampaign","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignResponse"}}},"description":"Cancel monthly renewal when instructed by the owner; retain the paid period."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing/invalid campaign key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cross-origin request rejected"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Campaign or action not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Refresh state; slot or review state changed"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Upload too large"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wait before retrying"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment result uncertain; poll same campaign before retrying"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unavailable"}},"security":[{"campaignKey":[]}],"summary":"Cancel monthly renewal when instructed by the owner; retain the paid period."}},"/api/sponsors/campaigns/{campaign_id}/checkout":{"post":{"operationId":"checkoutCampaign","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}},"description":"Reserve an approved slot and get hosted Stripe Checkout. Requires owner recurring-payment authorization; no programmatic card/SPT payment."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing/invalid campaign key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cross-origin request rejected"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Campaign or action not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Refresh state; slot or review state changed"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Upload too large"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wait before retrying"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment result uncertain; poll same campaign before retrying"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unavailable"}},"security":[{"campaignKey":[]}],"summary":"Reserve an approved slot and get hosted Stripe Checkout. Requires owner recurring-payment authorization; no programmatic card/SPT payment."}},"/api/sponsors/campaigns/{campaign_id}/portal":{"post":{"operationId":"portalCampaign","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}},"description":"Create a short-lived owner billing portal link."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing/invalid campaign key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cross-origin request rejected"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Campaign or action not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Refresh state; slot or review state changed"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Upload too large"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wait before retrying"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment result uncertain; poll same campaign before retrying"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unavailable"}},"security":[{"campaignKey":[]}],"summary":"Create a short-lived owner billing portal link."}},"/api/sponsors/campaigns/{campaign_id}/revision":{"post":{"operationId":"revisionCampaign","parameters":[{"in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"desktop":{"description":"Static PNG/JPEG/WebP <=1048576bytes;160x300 rails or728x90 bottom.","format":"binary","type":"string"},"mobile":{"description":"Required for bottom:320x50 static PNG/JPEG/WebP <=1048576bytes.","format":"binary","type":"string"},"name":{"maxLength":100,"minLength":2,"type":"string"},"url":{"description":"Public HTTPS destination, subject to human review.","format":"uri","type":"string"}},"required":["name","url","desktop"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignResponse"}}},"description":"Submit complete replacement artwork/destination for review. Current paid approved ad stays displayed."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Invalid input"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing/invalid campaign key"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Cross-origin request rejected"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Campaign or action not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Refresh state; slot or review state changed"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Upload too large"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wait before retrying"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Payment result uncertain; poll same campaign before retrying"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Temporarily unavailable"}},"security":[{"campaignKey":[]}],"summary":"Submit complete replacement artwork/destination for review. Current paid approved ad stays displayed."}},"/api/sponsors/slots":{"get":{"operationId":"listSlots","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}},"description":"Live catalog; no login required."}},"summary":"Read all three $100/month placements, current availability, image dimensions and capability limits."}},"/api/sponsors/traffic":{"get":{"operationId":"getTraffic","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Traffic"}}},"description":"Public traffic report. Unavailable metrics are null, stale metrics retain their original dates."}},"summary":"Read daily Cloudflare page views and response bytes for 30 completed UTC days. Includes bots; not visitors or ad impressions. Check freshness and dates."}}},"servers":[{"url":"https://spacedownloader.io"}]}