{
  "openapi": "3.1.0",
  "info": {
    "title": "eventsfeed API",
    "version": "1.0.0",
    "description": "Live soccer data: events, scores, odds, stats, timeline, pitch and player stats. REST for snapshots, WebSocket for deltas. See the guides at https://docs.eventsfeed.dev."
  },
  "servers": [
    {
      "url": "https://api.eventsfeed.dev"
    }
  ],
  "tags": [
    {
      "name": "Events"
    },
    {
      "name": "Embed"
    },
    {
      "name": "Account"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key: `Authorization: Bearer efk_…`. `X-Api-Key` header or `?key=` also work."
      }
    },
    "schemas": {
      "Competition": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^cp_[0-9a-z]{10}$",
            "example": "cp_3nfp8e2kx1"
          },
          "name": {
            "type": "string",
            "example": "England Premier League"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "Team": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^tm_[0-9a-z]{10}$",
            "example": "tm_7d1qv0wz3e"
          },
          "name": {
            "type": "string",
            "example": "Arsenal"
          },
          "colors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Kit colors as CSS hex, when known (from the pitch feed).",
            "example": [
              "#EF0107",
              "#FFFFFF"
            ]
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "Phase": {
        "type": "string",
        "enum": [
          "NS",
          "1H",
          "HT",
          "2H",
          "PAUSED",
          "FT"
        ],
        "description": "NS not started · 1H first half · HT half-time · 2H second half · PAUSED interrupted · FT finished"
      },
      "Clock": {
        "type": "object",
        "properties": {
          "seconds": {
            "type": "integer",
            "minimum": 0,
            "description": "Elapsed match time at `meta.ts`/frame time.",
            "example": 2220
          },
          "running": {
            "type": "boolean"
          },
          "display": {
            "type": "string",
            "example": "37'"
          }
        },
        "required": [
          "seconds",
          "running",
          "display"
        ]
      },
      "ScorePair": {
        "type": "object",
        "properties": {
          "home": {
            "type": "integer"
          },
          "away": {
            "type": "integer"
          }
        },
        "required": [
          "home",
          "away"
        ]
      },
      "Score": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ScorePair"
          },
          {
            "type": "object",
            "properties": {
              "ht": {
                "$ref": "#/components/schemas/ScorePair"
              }
            }
          }
        ]
      },
      "Channel": {
        "type": "string",
        "enum": [
          "core",
          "odds",
          "stats",
          "timeline",
          "pitch",
          "players"
        ],
        "description": "Independent slices of an event. Each one has its own revision and can be fetched or subscribed separately."
      },
      "MarketKey": {
        "type": "string",
        "enum": [
          "match_result",
          "double_chance",
          "both_teams_score",
          "total_goals",
          "odd_even",
          "correct_score"
        ]
      },
      "Market": {
        "type": "object",
        "properties": {
          "key": {
            "$ref": "#/components/schemas/MarketKey"
          },
          "period": {
            "type": "string",
            "enum": [
              "FT",
              "1H"
            ],
            "description": "FT = full time (90 min), 1H = first half."
          },
          "line": {
            "type": "number",
            "description": "Goal line, for total_goals.",
            "example": 2.5
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "suspended"
            ]
          },
          "suspendReason": {
            "type": "string",
            "enum": [
              "goal",
              "line_settled",
              "unavailable"
            ]
          },
          "selections": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "exclusiveMinimum": 1
            },
            "description": "Selection key -> decimal price. Keys are stable per market, see the market catalog.",
            "example": {
              "home": 1.85,
              "draw": 3.4,
              "away": 4.2
            }
          }
        },
        "required": [
          "key",
          "period",
          "status",
          "selections"
        ]
      },
      "Odds": {
        "type": "object",
        "properties": {
          "markets": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/Market"
            },
            "description": "Market id -> market. Ids are `<key>.<period>` plus `@<line>` when the market has a line, e.g. `match_result.ft`, `total_goals.ft@2.5`, `match_result.1h`. A market that disappears was withdrawn."
          }
        },
        "required": [
          "markets"
        ]
      },
      "TeamStats": {
        "type": "object",
        "properties": {
          "corners": {
            "type": "integer"
          },
          "yellowCards": {
            "type": "integer"
          },
          "redCards": {
            "type": "integer"
          },
          "shotsOnTarget": {
            "type": "integer"
          },
          "shotsOffTarget": {
            "type": "integer"
          },
          "attacks": {
            "type": "integer"
          },
          "dangerousAttacks": {
            "type": "integer"
          },
          "possession": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Ball possession, %."
          }
        }
      },
      "Stats": {
        "type": "object",
        "properties": {
          "home": {
            "$ref": "#/components/schemas/TeamStats"
          },
          "away": {
            "$ref": "#/components/schemas/TeamStats"
          }
        },
        "required": [
          "home",
          "away"
        ]
      },
      "Side": {
        "type": "string",
        "enum": [
          "home",
          "away"
        ]
      },
      "TimelineItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "goal",
              "corner",
              "card.yellow",
              "card.red"
            ]
          },
          "side": {
            "$ref": "#/components/schemas/Side"
          },
          "minute": {
            "type": "integer"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type"
        ]
      },
      "Timeline": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TimelineItem"
            },
            "description": "Newest first."
          },
          "goals": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "side": {
                  "$ref": "#/components/schemas/Side"
                },
                "minute": {
                  "type": "string"
                },
                "shot": {
                  "type": "object",
                  "properties": {
                    "x": {
                      "type": "number"
                    },
                    "y": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "x",
                    "y"
                  ],
                  "description": "Where the shot was taken from, 0..1 (x=0 is the home goal)."
                }
              },
              "required": [
                "minute"
              ]
            }
          }
        },
        "required": [
          "items"
        ]
      },
      "PitchAction": {
        "type": "string",
        "enum": [
          "dangerous_attack",
          "attack",
          "possession",
          "corner",
          "goal_kick",
          "free_kick",
          "dangerous_free_kick",
          "shot_on_target",
          "shot_off_target",
          "throw_in",
          "goal",
          "yellow_card",
          "red_card",
          "penalty",
          "substitution",
          "offside",
          "unknown"
        ]
      },
      "Pitch": {
        "type": "object",
        "properties": {
          "ball": {
            "type": "object",
            "properties": {
              "x": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "y": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "x",
              "y"
            ],
            "description": "Ball position, 0..1. x=0 is the home goal, home attacks to the right."
          },
          "action": {
            "type": "object",
            "properties": {
              "type": {
                "$ref": "#/components/schemas/PitchAction"
              },
              "side": {
                "$ref": "#/components/schemas/Side"
              }
            },
            "required": [
              "type"
            ]
          },
          "clock": {
            "$ref": "#/components/schemas/Clock"
          }
        }
      },
      "Player": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^pl_[0-9a-z]{10}$",
            "example": "pl_x0b4mt9a2c"
          },
          "name": {
            "type": "string"
          },
          "firstName": {
            "type": "string"
          },
          "shirt": {
            "type": "integer"
          },
          "starter": {
            "type": "boolean"
          },
          "goals": {
            "type": "integer"
          },
          "assists": {
            "type": "integer"
          },
          "shots": {
            "type": "integer"
          },
          "shotsOnTarget": {
            "type": "integer"
          },
          "passes": {
            "type": "integer"
          },
          "tackles": {
            "type": "integer"
          },
          "foulsCommitted": {
            "type": "integer"
          },
          "foulsSuffered": {
            "type": "integer"
          },
          "xg": {
            "type": "number"
          },
          "yellowCards": {
            "type": "integer"
          },
          "redCards": {
            "type": "integer"
          },
          "firstGoal": {
            "type": "boolean"
          },
          "lastGoal": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "starter"
        ]
      },
      "Players": {
        "type": "object",
        "properties": {
          "availability": {
            "type": "string",
            "enum": [
              "post_match"
            ]
          },
          "home": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Player"
            }
          },
          "away": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Player"
            }
          }
        },
        "required": [
          "availability",
          "home",
          "away"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ev_[0-9a-z]{10}$",
            "example": "ev_k2m9x4q8zt"
          },
          "sport": {
            "type": "string",
            "enum": [
              "soccer"
            ]
          },
          "competition": {
            "$ref": "#/components/schemas/Competition"
          },
          "home": {
            "$ref": "#/components/schemas/Team"
          },
          "away": {
            "$ref": "#/components/schemas/Team"
          },
          "startsAt": {
            "type": "string",
            "format": "date-time"
          },
          "state": {
            "type": "string",
            "enum": [
              "live",
              "finished"
            ]
          },
          "phase": {
            "$ref": "#/components/schemas/Phase"
          },
          "clock": {
            "$ref": "#/components/schemas/Clock"
          },
          "score": {
            "$ref": "#/components/schemas/Score"
          },
          "channels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Channel"
            },
            "description": "Channels that currently have data for this event."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "sport",
          "competition",
          "home",
          "away",
          "state",
          "phase",
          "score",
          "channels",
          "updatedAt"
        ]
      },
      "EventWithChannels": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Event"
          },
          {
            "type": "object",
            "properties": {
              "odds": {
                "$ref": "#/components/schemas/Odds"
              },
              "stats": {
                "$ref": "#/components/schemas/Stats"
              },
              "timeline": {
                "$ref": "#/components/schemas/Timeline"
              },
              "pitch": {
                "$ref": "#/components/schemas/Pitch"
              },
              "players": {
                "$ref": "#/components/schemas/Players"
              }
            }
          }
        ]
      },
      "Meta": {
        "type": "object",
        "properties": {
          "ts": {
            "type": "string",
            "format": "date-time"
          },
          "requestId": {
            "type": "string"
          },
          "rev": {
            "type": "integer",
            "description": "Revision of the returned channel. Use it as `since` on the WebSocket to resume without gaps."
          }
        },
        "required": [
          "ts",
          "requestId"
        ]
      },
      "EventList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventWithChannels"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "rate_limited",
                  "bad_request",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "error",
          "meta"
        ]
      },
      "EventResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/EventWithChannels"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "OddsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Odds"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "StatsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Stats"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "TimelineResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Timeline"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "PitchResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Pitch"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "PlayersResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Players"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "CompetitionList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Competition"
                },
                {
                  "type": "object",
                  "properties": {
                    "live": {
                      "type": "integer"
                    },
                    "finished": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "live",
                    "finished"
                  ]
                }
              ]
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "EmbedToken": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "iframeUrl": {
            "type": "string",
            "format": "uri"
          },
          "html": {
            "type": "string",
            "description": "Ready-to-paste iframe snippet."
          }
        },
        "required": [
          "token",
          "expiresAt",
          "iframeUrl",
          "html"
        ]
      },
      "EmbedTokenResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/EmbedToken"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      },
      "EmbedTokenRequest": {
        "type": "object",
        "properties": {
          "eventId": {
            "type": "string",
            "pattern": "^ev_[0-9a-z]{10}$",
            "example": "ev_k2m9x4q8zt"
          },
          "ttl": {
            "type": "integer",
            "minimum": 60,
            "maximum": 86400,
            "default": 3600,
            "description": "Seconds until the token expires."
          },
          "origins": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1,
            "maxItems": 10,
            "description": "Origins allowed to frame the widget (Content-Security-Policy frame-ancestors).",
            "example": [
              "https://www.example.com"
            ]
          }
        },
        "required": [
          "eventId",
          "origins"
        ]
      },
      "Usage": {
        "type": "object",
        "properties": {
          "key": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "requests": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "used": {
                "type": "integer"
              },
              "remaining": {
                "type": "integer"
              },
              "resetsInSeconds": {
                "type": "integer"
              }
            },
            "required": [
              "limit",
              "used",
              "remaining",
              "resetsInSeconds"
            ]
          },
          "websockets": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "open": {
                "type": "integer"
              }
            },
            "required": [
              "limit",
              "open"
            ]
          }
        },
        "required": [
          "key",
          "requests",
          "websockets"
        ]
      },
      "UsageResponse": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/Usage"
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        },
        "required": [
          "data",
          "meta"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/v1/events": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "List events",
        "description": "Live events (default) or events finished in the last 48h. Use `include` to inline channels and save requests.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "enum": [
                "live",
                "finished"
              ],
              "default": "live"
            },
            "required": false,
            "name": "state",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^cp_[0-9a-z]{10}$",
              "example": "cp_3nfp8e2kx1"
            },
            "required": false,
            "name": "competition",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma separated channels to inline: odds,stats,timeline,pitch,players",
              "example": "odds,stats"
            },
            "required": false,
            "name": "include",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Events. For `state=live`, `meta.rev` is the revision of the `live` stream topic.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get one event",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^ev_[0-9a-z]{10}$",
              "example": "ev_k2m9x4q8zt"
            },
            "required": true,
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "example": "odds,stats,timeline"
            },
            "required": false,
            "name": "include",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "The event (core channel) plus included channels. `meta.rev` is the core revision.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown event, or finished more than 48h ago.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}/odds": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get odds",
        "description": "Live odds. Prices are decimal. Suspended markets keep their last prices and say why.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^ev_[0-9a-z]{10}$",
              "example": "ev_k2m9x4q8zt"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "odds channel; `meta.rev` is its revision.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OddsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Event unknown or no data for this channel yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}/stats": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get stats",
        "description": "Team statistics.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^ev_[0-9a-z]{10}$",
              "example": "ev_k2m9x4q8zt"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "stats channel; `meta.rev` is its revision.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Event unknown or no data for this channel yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}/timeline": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get timeline",
        "description": "Goals, cards and corners (newest first). Produced on demand: the first request starts it, retry after a few seconds on 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^ev_[0-9a-z]{10}$",
              "example": "ev_k2m9x4q8zt"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "timeline channel; `meta.rev` is its revision.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimelineResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Event unknown or no data for this channel yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}/pitch": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get pitch",
        "description": "Live pitch: ball position and current action. Produced on demand like timeline.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^ev_[0-9a-z]{10}$",
              "example": "ev_k2m9x4q8zt"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "pitch channel; `meta.rev` is its revision.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PitchResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Event unknown or no data for this channel yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}/players": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Get players",
        "description": "Player statistics. Published after the match ends (usually 2–4h after kick-off) and kept 48h.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^ev_[0-9a-z]{10}$",
              "example": "ev_k2m9x4q8zt"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "players channel; `meta.rev` is its revision.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayersResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Event unknown or no data for this channel yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/competitions": {
      "get": {
        "tags": [
          "Events"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "List competitions with live or recently finished events",
        "responses": {
          "200": {
            "description": "Competitions.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompetitionList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/embed/tokens": {
      "post": {
        "tags": [
          "Embed"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Create a pitch iframe token",
        "description": "Call this from your server, never from the browser. The token is bound to one event and to the origins allowed to frame it.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbedTokenRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token and ready-to-use iframe.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbedTokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "security": [
          {
            "apiKey": []
          }
        ],
        "summary": "Your current usage (free, not counted)",
        "responses": {
          "200": {
            "description": "Usage of the calling key.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Hourly request limit reached. Wait `Retry-After` seconds.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Requests allowed per hour for this key.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests left in the current sliding hour.",
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current hourly bucket rolls over.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}