{ "openapi": "3.1.0", "info": { "title": "Pickleball API", "version": "2.0.0", "description": "REST API for MLP fixtures, lineups, standings, live observations, and (Pro-plan) prediction markets. Authenticate with Authorization: Bearer pbl_live_… Every response envelope carries `request_id`; source freshness and completeness metadata is present when meaningful for the resource." }, "externalDocs": { "description": "Human-readable documentation and compatibility policy", "url": "https://pickleball-api.com/docs" }, "servers": [ { "url": "https://pickleball-api.com/v1" } ], "paths": { "/competitions": { "get": { "summary": "List competitions", "responses": { "200": { "description": "Competitions" } }, "security": [ { "ApiKey": [] } ] } }, "/competitions/{id}": { "get": { "summary": "Get competition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Competition" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/seasons": { "get": { "summary": "List seasons", "parameters": [ { "name": "competition_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Seasons" } }, "security": [ { "ApiKey": [] } ] } }, "/events": { "get": { "summary": "List events", "parameters": [ { "name": "season_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "active_only", "in": "query", "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 200 } } ], "responses": { "200": { "description": "Events" } }, "security": [ { "ApiKey": [] } ] } }, "/events/{id}": { "get": { "summary": "Get event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event", "content": { "application/json": { "schema": { "$ref": "#/definitions/EventEnvelope", "definitions": { "EventEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "season_id": { "anyOf": [ { "$ref": "#/definitions/EventEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "venue_id": { "anyOf": [ { "$ref": "#/definitions/EventEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "name": { "type": "string" }, "starts_on": { "type": [ "string", "null" ] }, "ends_on": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } }, "required": [ "id", "season_id", "venue_id", "name", "starts_on", "ends_on", "timezone", "active" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/EventEnvelope/properties/meta/properties/generated_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/events/{id}/teams": { "get": { "summary": "Teams competing at an event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event teams", "content": { "application/json": { "schema": { "$ref": "#/definitions/EventTeamsEnvelope", "definitions": { "EventTeamsEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "abbreviation": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "abbreviation" ], "additionalProperties": false }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "team", "seed" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/EventTeamsEnvelope/properties/meta/properties/generated_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/events/{id}/standings/latest": { "get": { "summary": "Latest standings for an event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Standings snapshot", "content": { "application/json": { "schema": { "$ref": "#/definitions/StandingsEnvelope", "definitions": { "StandingsEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "anyOf": [ { "$ref": "#/definitions/StandingsEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "season_id": { "anyOf": [ { "$ref": "#/definitions/StandingsEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "captured_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "standings": { "type": "array", "items": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "$ref": "#/definitions/StandingsEnvelope/properties/data/properties/id" }, "name": { "type": "string" }, "abbreviation": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "abbreviation" ], "additionalProperties": false }, "rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "points": { "type": [ "number", "null" ] }, "wins": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "losses": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "team", "rank", "points", "wins", "losses" ], "additionalProperties": false } } }, "required": [ "id", "event_id", "season_id", "captured_at", "standings" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "$ref": "#/definitions/StandingsEnvelope/properties/data/properties/captured_at" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/StandingsEnvelope/properties/data/properties/captured_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/events/{id}/standings/history": { "get": { "summary": "Standings snapshot history for an event", "description": "Newest snapshots first.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "RFC 3339 captured_at value from the previous page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Standings snapshots" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/seasons/{id}/standings/latest": { "get": { "summary": "Latest standings for a season", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Standings snapshot" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/seasons/{id}/standings/history": { "get": { "summary": "Standings snapshot history for a season", "description": "Newest snapshots first.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "RFC 3339 captured_at value from the previous page.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Standings snapshots" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/venues/{id}": { "get": { "summary": "Get venue", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Venue" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/teams": { "get": { "summary": "List teams", "responses": { "200": { "description": "Teams" } }, "security": [ { "ApiKey": [] } ] } }, "/teams/{id}": { "get": { "summary": "Get team", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Team" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/teams/{id}/roster": { "get": { "summary": "Team roster for an event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "event_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Roster", "content": { "application/json": { "schema": { "$ref": "#/definitions/RosterEnvelope", "definitions": { "RosterEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "player": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "dupr_id": { "type": [ "string", "null" ] }, "dupr_rating_singles": { "type": [ "number", "null" ] }, "dupr_rating_doubles": { "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "country_code", "dupr_id", "dupr_rating_singles", "dupr_rating_doubles" ], "additionalProperties": false }, "role": { "type": [ "string", "null" ] }, "starts_on": { "type": [ "string", "null" ] }, "ends_on": { "type": [ "string", "null" ] } }, "required": [ "player", "role", "starts_on", "ends_on" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/RosterEnvelope/properties/meta/properties/generated_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/teams/{id}/fixtures": { "get": { "summary": "Recent fixtures involving a team", "description": "Up to 200 fixtures, ordered by scheduled_at descending.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fixtures" } }, "security": [ { "ApiKey": [] } ] } }, "/teams/{id}/matches": { "get": { "summary": "Recent lineup matches involving a team", "description": "Up to 200 matches, ordered by creation time descending.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Matches" } }, "security": [ { "ApiKey": [] } ] } }, "/players": { "get": { "summary": "List players", "responses": { "200": { "description": "Players", "content": { "application/json": { "schema": { "$ref": "#/definitions/PlayersEnvelope", "definitions": { "PlayersEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "dupr_id": { "type": [ "string", "null" ] }, "dupr_rating_singles": { "type": [ "number", "null" ] }, "dupr_rating_doubles": { "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "country_code", "dupr_id", "dupr_rating_singles", "dupr_rating_doubles" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/PlayersEnvelope/properties/meta/properties/generated_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/players/{id}": { "get": { "summary": "Get player", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Player", "content": { "application/json": { "schema": { "$ref": "#/definitions/PlayerEnvelope", "definitions": { "PlayerEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "dupr_id": { "type": [ "string", "null" ] }, "dupr_rating_singles": { "type": [ "number", "null" ] }, "dupr_rating_doubles": { "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "country_code", "dupr_id", "dupr_rating_singles", "dupr_rating_doubles" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/PlayerEnvelope/properties/meta/properties/generated_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/fixtures": { "get": { "summary": "List fixtures", "parameters": [ { "name": "event_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Fixtures" } }, "security": [ { "ApiKey": [] } ] } }, "/fixtures/{id}": { "get": { "summary": "Get fixture", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fixture", "content": { "application/json": { "schema": { "$ref": "#/definitions/FixtureEnvelope", "definitions": { "FixtureEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "anyOf": [ { "$ref": "#/definitions/FixtureEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "scheduled_at": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, { "type": "null" } ] }, "court": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] }, "is_provisional": { "type": "boolean" }, "sides": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "number", "enum": [ 0, 1 ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "$ref": "#/definitions/FixtureEnvelope/properties/data/properties/id" }, "name": { "type": "string" }, "abbreviation": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "abbreviation" ], "additionalProperties": false }, { "type": "null" } ] }, "label": { "type": [ "string", "null" ] }, "matches_won": { "type": "integer", "minimum": 0 } }, "required": [ "side", "team", "label", "matches_won" ], "additionalProperties": false } } }, "required": [ "id", "event_id", "status", "scheduled_at", "court", "stage", "is_provisional", "sides" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "$ref": "#/definitions/FixtureEnvelope/properties/data/properties/scheduled_at/anyOf/0" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/FixtureEnvelope/properties/data/properties/scheduled_at/anyOf/0" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/fixtures/{id}/matches": { "get": { "summary": "Matches within a fixture", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Matches" } }, "security": [ { "ApiKey": [] } ] } }, "/fixtures/{id}/live": { "get": { "summary": "Latest observation per match in the fixture", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Live entries", "content": { "application/json": { "schema": { "$ref": "#/definitions/FixtureLiveEnvelope", "definitions": { "FixtureLiveEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "match": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fixture_id": { "anyOf": [ { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/id" }, { "type": "null" } ] }, "category": { "type": [ "string", "null" ] }, "lineup_slot": { "type": [ "string", "null" ] }, "lineup_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "winner_team_id": { "anyOf": [ { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/id" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, { "type": "null" } ] }, "participants": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "number", "enum": [ 0, 1 ] }, "player": { "type": "object", "properties": { "id": { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/id" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "dupr_id": { "type": [ "string", "null" ] }, "dupr_rating_singles": { "type": [ "number", "null" ] }, "dupr_rating_doubles": { "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "country_code", "dupr_id", "dupr_rating_singles", "dupr_rating_doubles" ], "additionalProperties": false } }, "required": [ "side", "player" ], "additionalProperties": false } } }, "required": [ "id", "fixture_id", "category", "lineup_slot", "lineup_sequence", "status", "winner_team_id", "completed_at" ], "additionalProperties": false }, "observation": { "anyOf": [ { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 0 }, "observed_at": { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/completed_at/anyOf/0" }, "lifecycle": { "type": [ "string", "null" ] }, "current_game": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "serving_side": { "anyOf": [ { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/participants/items/properties/side" }, { "type": "null" } ] }, "server_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "side_0_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "side_1_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "side_0_games_won": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "side_1_games_won": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "winner_side": { "anyOf": [ { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/participants/items/properties/side" }, { "type": "null" } ] } }, "required": [ "sequence", "observed_at", "lifecycle", "current_game", "serving_side", "server_number", "side_0_points", "side_1_points", "side_0_games_won", "side_1_games_won", "winner_side" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "match", "observation" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/completed_at/anyOf/0" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/FixtureLiveEnvelope/properties/data/items/properties/match/properties/completed_at/anyOf/0" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "security": [ { "ApiKey": [] } ] } }, "/fixtures/{id}/markets": { "get": { "summary": "Verified prediction markets for a fixture (Pro plan / markets entitlement)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Markets" }, "403": { "description": "Markets entitlement required" } }, "security": [ { "ApiKey": [] } ] } }, "/fixtures/{id}/market-context": { "get": { "summary": "Fixture + verified markets with independent freshness clocks (Pro plan / markets entitlement)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Market context", "content": { "application/json": { "schema": { "$ref": "#/definitions/MarketContextEnvelope", "definitions": { "MarketContextEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "fixture": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "anyOf": [ { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/id" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "scheduled_at": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, { "type": "null" } ] }, "court": { "type": [ "string", "null" ] }, "stage": { "type": [ "string", "null" ] }, "is_provisional": { "type": "boolean" }, "sides": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "number", "enum": [ 0, 1 ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/id" }, "name": { "type": "string" }, "abbreviation": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "abbreviation" ], "additionalProperties": false }, { "type": "null" } ] }, "label": { "type": [ "string", "null" ] }, "matches_won": { "type": "integer", "minimum": 0 } }, "required": [ "side", "team", "label", "matches_won" ], "additionalProperties": false } } }, "required": [ "id", "event_id", "status", "scheduled_at", "court", "stage", "is_provisional", "sides" ], "additionalProperties": false }, "markets": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/id" }, "question": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "resolved", "closed" ] }, "resolved_outcome_id": { "anyOf": [ { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/id" }, { "type": "null" } ] }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "id": { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/id" }, "name": { "type": "string" }, "latest_price": { "type": [ "number", "null" ] }, "price_observed_at": { "anyOf": [ { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/scheduled_at/anyOf/0" }, { "type": "null" } ] }, "best_bid": { "type": [ "number", "null" ] }, "best_ask": { "type": [ "number", "null" ] }, "spread": { "type": [ "number", "null" ] }, "book_observed_at": { "anyOf": [ { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/scheduled_at/anyOf/0" }, { "type": "null" } ] } }, "required": [ "id", "name", "latest_price", "price_observed_at", "best_bid", "best_ask", "spread", "book_observed_at" ], "additionalProperties": false } } }, "required": [ "id", "question", "status", "resolved_outcome_id", "outcomes" ], "additionalProperties": false } }, "sports_freshness_seconds": { "type": [ "number", "null" ] }, "market_freshness_seconds": { "type": [ "number", "null" ] } }, "required": [ "fixture", "markets", "sports_freshness_seconds", "market_freshness_seconds" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/scheduled_at/anyOf/0" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/MarketContextEnvelope/properties/data/properties/fixture/properties/scheduled_at/anyOf/0" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "403": { "description": "Markets entitlement required" } }, "security": [ { "ApiKey": [] } ] } }, "/matches/{id}": { "get": { "summary": "Get match (includes participants lineup)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Match", "content": { "application/json": { "schema": { "$ref": "#/definitions/MatchEnvelope", "definitions": { "MatchEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fixture_id": { "anyOf": [ { "$ref": "#/definitions/MatchEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "category": { "type": [ "string", "null" ] }, "lineup_slot": { "type": [ "string", "null" ] }, "lineup_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "winner_team_id": { "anyOf": [ { "$ref": "#/definitions/MatchEnvelope/properties/data/properties/id" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, { "type": "null" } ] }, "participants": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "number", "enum": [ 0, 1 ] }, "player": { "type": "object", "properties": { "id": { "$ref": "#/definitions/MatchEnvelope/properties/data/properties/id" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "dupr_id": { "type": [ "string", "null" ] }, "dupr_rating_singles": { "type": [ "number", "null" ] }, "dupr_rating_doubles": { "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "country_code", "dupr_id", "dupr_rating_singles", "dupr_rating_doubles" ], "additionalProperties": false } }, "required": [ "side", "player" ], "additionalProperties": false } } }, "required": [ "id", "fixture_id", "category", "lineup_slot", "lineup_sequence", "status", "winner_team_id", "completed_at" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "$ref": "#/definitions/MatchEnvelope/properties/data/properties/completed_at/anyOf/0" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/MatchEnvelope/properties/data/properties/completed_at/anyOf/0" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/matches/{id}/participants": { "get": { "summary": "Match lineup participants", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Participants", "content": { "application/json": { "schema": { "$ref": "#/definitions/MatchParticipantsEnvelope", "definitions": { "MatchParticipantsEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "number", "enum": [ 0, 1 ] }, "player": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "country_code": { "type": [ "string", "null" ] }, "dupr_id": { "type": [ "string", "null" ] }, "dupr_rating_singles": { "type": [ "number", "null" ] }, "dupr_rating_doubles": { "type": [ "number", "null" ] } }, "required": [ "id", "display_name", "country_code", "dupr_id", "dupr_rating_singles", "dupr_rating_doubles" ], "additionalProperties": false } }, "required": [ "side", "player" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/MatchParticipantsEnvelope/properties/meta/properties/generated_at" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/matches/{id}/games": { "get": { "summary": "Per-game scores for a match", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Games" } }, "security": [ { "ApiKey": [] } ] } }, "/matches/{id}/observations": { "get": { "summary": "Observation time series for a match (cursor = sequence)", "description": "Oldest observations first. Sequence is monotonic within this match.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "Last seen sequence; results are returned in ascending sequence order.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Observations" } }, "security": [ { "ApiKey": [] } ] } }, "/matches/{id}/events": { "get": { "summary": "Domain-event history for a match (cursor = sequence)", "description": "Oldest events first. Sequence is monotonic within this match channel.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "Last seen sequence; results are returned in ascending sequence order.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Domain events" }, "404": { "description": "Not found" } }, "security": [ { "ApiKey": [] } ] } }, "/realtime/tickets": { "post": { "summary": "Mint single-use WebSocket ticket", "responses": { "200": { "description": "Ticket" } }, "security": [ { "ApiKey": [] } ] } }, "/usage": { "get": { "summary": "Current quota usage", "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "$ref": "#/definitions/UsageEnvelope", "definitions": { "UsageEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "trial", "basic", "pro", "enterprise", "none" ] }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$" }, "period_end": { "$ref": "#/definitions/UsageEnvelope/properties/data/properties/period_start" }, "rest_calls_used": { "type": "integer", "minimum": 0 }, "rest_calls_limit": { "type": "integer", "minimum": 0 }, "outbound_messages_used": { "type": "integer", "minimum": 0 }, "outbound_messages_limit": { "type": "integer", "minimum": 0 }, "sockets_active": { "type": "integer", "minimum": 0 }, "sockets_limit": { "type": "integer", "minimum": 0 }, "markets_entitled": { "type": "boolean" } }, "required": [ "plan", "period_start", "period_end", "rest_calls_used", "rest_calls_limit", "outbound_messages_used", "outbound_messages_limit", "sockets_active", "sockets_limit", "markets_entitled" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "generated_at": { "$ref": "#/definitions/UsageEnvelope/properties/data/properties/period_start" }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "observed_at": { "anyOf": [ { "$ref": "#/definitions/UsageEnvelope/properties/data/properties/period_start" }, { "type": "null" } ] }, "freshness_seconds": { "type": [ "number", "null" ] }, "completeness": { "type": "string", "enum": [ "full", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "request_id", "generated_at" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } }, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pbl_live_" } }, "schemas": { "ProblemDetails": { "type": "object", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" } } } } } }