{"openapi":"3.1.0","info":{"title":"Clean Sports Partner API","version":"1.4.0","description":"Server-to-server catalog, scanning and authorized playback. Both API key and secret are required. Secrets must never be shipped to a browser. Source lists distinguish verified, pending and failed source health without exposing upstream URLs."},"security":[{"ApiKey":[],"ApiSecret":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"},"ApiSecret":{"type":"apiKey","in":"header","name":"X-API-Secret"}},"schemas":{"Source":{"type":"object","properties":{"id":{"type":"string","description":"Opaque source identifier. Use as returned; never infer supplier IDs."},"number":{"type":"integer","description":"Original numeric source label. Preserve it when sorting sources; do not renumber by array position."},"label":{"type":"string","description":"Numeric display label: 1, 2, 3, and so on."},"language":{"type":"string","description":"Language metadata supplied by the provider, for example en (English) or ru (Russian); empty when unknown. This is not audio language detection."},"playbackType":{"enum":["youtube","twitch","kick","hls"],"description":"Playback adapter. youtube, twitch and kick use their official players inside our authorized iframe; hls uses our protected media player. Always obtain embedUrl through POST /api/v1/playback."},"isYouTube":{"type":"boolean","description":"True exactly when playbackType is youtube. Safe metadata for a YouTube badge; not a video URL or identifier."},"supported":{"type":"boolean"},"playable":{"type":"boolean","description":"True only for a source currently admitted by its type-specific health check. Pending sources remain playable=false; a partner explicitly opted in to unverified playback may still request them and receives unverified=true in the playback response."},"verification":{"enum":["verified","pending"],"description":"Source lifecycle status. verified means playback admission is currently allowed; pending means the source is known but not yet verified. By default pending sources are rejected by playback; explicitly opted-in partners may try them at their own risk. This is different from health.verification, which names the probe method."},"health":{"type":"object","properties":{"state":{"enum":["ready","unknown","checking"]},"verification":{"enum":["youtube_metadata","official_embed","iframe_embed","media_bytes",null],"description":"Probe method, not the source lifecycle status. Use the parent source.verification and source.playable to decide whether playback is verified."},"checkedAt":{"type":["integer","null"]},"expiresAt":{"type":["integer","null"],"description":"Freshness deadline only, never a deletion deadline."},"stale":{"type":"boolean"},"rechecking":{"type":"boolean"},"lastSuccessAt":{"type":["integer","null"]},"lastAttemptAt":{"type":["integer","null"]},"nextCheckAt":{"type":["integer","null"]},"reason":{"type":["string","null"]}}},"unsupportedReason":{"type":["string","null"]},"eventId":{"type":"string"},"playbackEndpoint":{"type":"string"}}},"Event":{"type":"object","properties":{"id":{"type":"string","description":"Stable local event ID. Use this ID for scans and playback; external metadata identifiers do not replace it."},"path":{"type":"string","description":"Local event reference, equal to the event ID. Not an upstream URL."},"title":{"type":"string"},"homeTeam":{"type":["string","null"]},"awayTeam":{"type":["string","null"]},"teamNamesSource":{"enum":["provider","betsapi","title",null],"description":"provider or betsapi means explicit participant roles. title means first/second displayed participant, not verified venue."},"eventType":{"enum":["match","tournament","event"]},"bet365Id":{"type":["string","null"],"description":"Verified Bet365 FI identifier; a separate namespace from betsapiEventId. Null without a verified mapping. Never use this in playback or scan requests."},"betsapiEventId":{"type":["string","null"],"description":"Verified BetsAPI Events identifier. Null when unavailable, even if bet365Id is known. Never infer either identifier from the local event.id."},"metadataSource":{"enum":["betsapi",null],"description":"Present for events matched to the metadata provider by participants, sport and time. A match does not create a video source."},"metadataCheckedAt":{"type":["integer","null"],"description":"Last metadata verification, Unix milliseconds UTC."},"officialStatus":{"enum":["scheduled","live","finished","postponed","cancelled","interrupted","suspended","unknown",null]},"timeStatus":{"type":["string","null"],"description":"Original BetsAPI time_status code as a string. Use officialStatus for normalized meaning."},"sportId":{"type":"string"},"sportName":{"type":"string"},"competition":{"type":"string"},"startsAt":{"type":["integer","null"],"description":"Unix milliseconds UTC"},"live":{"type":"boolean"},"statusCheckedAt":{"type":"integer","description":"Last match-status verification in UTC milliseconds. After 120 seconds do not claim confirmed live. broadcastContinuity=true keeps verified broadcast links visible with status updating."},"scheduleStale":{"type":"boolean","description":"The future fixture time could not be verified recently."},"status":{"enum":["live","soon","upcoming","unconfirmed"]},"sources":{"type":"array","description":"Sources may include metadata-only pending entries. Use only sources with playable=true and verification=verified for playback; preserve IDs and original numeric labels.","items":{"$ref":"#/components/schemas/Source"}},"sourceHealthPolicy":{"enum":["verified-with-pending-and-continuity"]},"sourceDiscoveryStatus":{"enum":["unscanned","pending","verified","no_source","unavailable"],"description":"unscanned means no source scan exists; pending means discovery or verification is still in progress; verified means at least one source is playable; no_source means a completed authoritative scan found no source; unavailable means discovered sources currently failed health checks."},"sourceContinuity":{"type":["object","null"]},"broadcastContinuity":{"type":"boolean","description":"Previously verified broadcast retained while fixture status/discovery is unavailable. Keep its sources visible."},"liveStatusUnconfirmed":{"type":"boolean","description":"Show status updating instead of claiming confirmed live. Does not remove verified broadcast links."},"sourcesState":{"enum":["unscanned","cached","stale"]},"sourcesCheckedAt":{"type":["integer","null"]}}},"MetadataSync":{"type":"object","description":"Metadata synchronization is separate from broadcast/source coverage. Live metadata is checked every 60 seconds; upcoming pages are refreshed incrementally and can take several cycles.","properties":{"configured":{"type":"boolean"},"status":{"enum":["pending","ok","partial","error","rate_limited","disabled"]},"mode":{"enum":["bet365","events",null]},"lastRun":{"type":["integer","null"],"description":"Last attempted metadata sync, Unix milliseconds UTC."},"lastSuccess":{"type":["integer","null"],"description":"Last successful metadata fetch, Unix milliseconds UTC."},"checkedAt":{"type":["integer","null"]},"stale":{"type":"boolean"},"matchedEvents":{"type":"integer","description":"Local catalog events with a verified metadata mapping; not all fixtures returned by BetsAPI."},"ambiguousEvents":{"type":"integer","description":"Events with ambiguous candidates, left without a new mapping."},"availableFixtures":{"type":"integer","description":"Metadata fixtures available in the shared cache. This is not the number of broadcasts."},"requestsLastRun":{"type":"integer"},"quota":{"type":["object","null"],"description":"Provider account quota observed on the last response; shared with other applications using the same account.","properties":{"limit":{"type":["integer","null"]},"remaining":{"type":["integer","null"]},"resetAt":{"type":["integer","null"],"description":"Unix milliseconds UTC."}}},"error":{"type":["string","null"],"description":"Safe diagnostic code only; never contains credentials or upstream request URLs."}}},"Catalog":{"type":"object","properties":{"schemaVersion":{"type":"string"},"sports":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"coverage":{"enum":["current","stale","unavailable"]}}}},"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"updatedAt":{"type":"integer"},"revision":{"type":"integer"},"partialSports":{"type":"array","items":{"type":"string"}},"stale":{"type":"boolean"},"sync":{"type":"object","properties":{"checkedAt":{"type":"integer"},"maxLiveAgeSeconds":{"type":"integer"},"suppressedEvents":{"type":"integer"},"unconfirmedLiveEvents":{"type":"integer","description":"Live fixtures hidden because their status evidence expired. If zero live games remain while this is positive, show status updating rather than a confirmed zero."},"partial":{"type":"boolean"},"stale":{"type":"boolean"}}},"scanner":{"type":["object","null"]},"metadataSync":{"$ref":"#/components/schemas/MetadataSync"},"sourceCoverage":{"type":["object","null"],"description":"Counts for live events and fixtures within 60 minutes: eligibleEvents, scannedEvents, freshEvents, eventsWithSupportedSources, retryingEvents, pendingEvents, checkedAt. stale=true after 120 seconds; freshEvents is then null. Supported is not proof of continuous playback."},"refreshSeconds":{"type":"integer"}}},"Job":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["catalog","sources"]},"status":{"enum":["queued","running","completed","partial","failed"]},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"},"eventId":{"type":["string","null"]},"eventIds":{"type":"array","items":{"type":"string"}},"result":{"type":"object","additionalProperties":true},"error":{"type":"string"}}}}},"paths":{"/api/v1/catalog":{"get":{"summary":"All games, sports, fields and recently verified video sources in one response","description":"Requires catalog:read. Timestamps are Unix milliseconds (UTC).","responses":{"200":{"description":"Complete snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}},"headers":{"ETag":{"schema":{"type":"string"}}}},"304":{"description":"Unchanged; keep your cached catalog"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}]}},"/api/v1/events":{"get":{"summary":"Filter and paginate events","description":"Requires catalog:read. Timestamps are Unix milliseconds (UTC).","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"sport","in":"query","required":false,"schema":{"type":"string"}},{"name":"eventType","in":"query","required":false,"schema":{"enum":["match","tournament","event"]}},{"name":"status","in":"query","required":false,"schema":{"enum":["live","soon","upcoming"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}]}},"/api/v1/events/{id}":{"get":{"summary":"One event with recently verified video sources","description":"Requires catalog:read. Timestamps are Unix milliseconds (UTC).","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/events/{id}/sources":{"get":{"summary":"Verified sources plus pending sources marked verification=pending; confirmed-failed sources are omitted","description":"Requires catalog:read. Timestamps are Unix milliseconds (UTC).","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/status":{"get":{"summary":"Catalog freshness, background scans and separate metadataSync health","description":"Requires catalog:read. Timestamps are Unix milliseconds (UTC).","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/changes":{"get":{"summary":"Snapshot updates since a revision; replace the whole local catalog when changed","description":"This is replacement sync, not a delta. Replace your local catalog when changed=true, including deleting events absent from the new snapshot. Time-based status may advance between snapshots; prefer /catalog with ETag for status polling.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"integer"}}]}},"/api/v1/scans":{"post":{"summary":"Queue a catalog or event source refresh","description":"Requires scans:write. Timestamps are Unix milliseconds (UTC).","responses":{"202":{"description":"Queued or coalesced. Source batches return per-event results; terminal status is completed, partial or failed. Ten new scan jobs/minute/partner, max20 active jobs and200 pending events. Three attempts with30/60-second backoff;10-minute deadline.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Location":{"schema":{"type":"string"}},"Retry-After":{"schema":{"type":"integer"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"enum":["catalog","sources"],"default":"catalog"},"eventId":{"type":"string","description":"One event for a sources scan; use either eventId or eventIds"},"eventIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"},"description":"Batch of up to 50 events. Do not also send eventId."}},"required":["type"],"additionalProperties":false}}}}}},"/api/v1/scans/{id}":{"get":{"summary":"Read your scan job status","description":"Requires scans:write. Timestamps are Unix milliseconds (UTC).","responses":{"200":{"description":"Scan status","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Unknown job or belongs to another partner","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/playback":{"post":{"summary":"Issue one viewer our embed URL for an authorized origin, for HLS or YouTube","description":"Requires streams:read. Timestamps are Unix milliseconds (UTC).","responses":{"201":{"description":"Embed URL valid for 10 minutes; active session lasts at most 4 hours","content":{"application/json":{"schema":{"type":"object","properties":{"embedUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"integer"},"sessionSeconds":{"type":"integer"}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"string"},"sourceId":{"type":"string"},"origin":{"type":"string","format":"uri","description":"Exact allowed HTTPS origin, e.g. https://your-site.example"},"viewerIp":{"type":"string","description":"Optional end-user IP. Otherwise bound to the first viewer IP opening the iframe."}},"required":["eventId","sourceId","origin"],"additionalProperties":false}}}}}},"/api/v1/openapi.json":{"get":{"summary":"Download this OpenAPI specification","description":"Public documentation. No credentials are required. Catalog, scan and playback operations still require the configured API key and secret.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[]}},"/api/v1/integration.md":{"get":{"summary":"Complete integration instructions for developers and AI coding agents","description":"Public documentation. No credentials are required. Catalog, scan and playback operations still require the configured API key and secret.","responses":{"200":{"description":"Personalized integration brief","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[]}},"/api/v1/llms.txt":{"get":{"summary":"Machine-readable index of integration resources","description":"Public documentation. No credentials are required. Catalog, scan and playback operations still require the configured API key and secret.","responses":{"200":{"description":"Integration resource index","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid or missing credentials","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Scope, origin, IP, or permission denied","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"429":{"description":"Rate exceeded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"503":{"description":"Scanner has no initial snapshot","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"security":[]}}},"servers":[{"url":"https://clean-sports-player.tectoris148.workers.dev"}]}