{"openapi":"3.1.0","info":{"title":"BALLDONTLIE F1 (BYOK) API","version":"0.1.0","description":"BALLDONTLIE F1 (BYOK) lets an AI assistant read your own BALLDONTLIE F1 data through the BALLDONTLIE F1 API with a key you supply (BALLDONTLIE API key). Read-only: 10 tools (list_drivers, list_teams, list_circuits, list_events, list_sessions, list_session_results, get_driver_standings, get_team_standings, list_lap_times, list_pit_stops). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-balldontlie-f1.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-balldontlie-f1/docs"},"termsOfService":"https://connectorbay.com/byok-balldontlie-f1/terms"},"servers":[{"url":"https://byok-balldontlie-f1.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-balldontlie-f1/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_drivers":{"post":{"operationId":"list_drivers","summary":"List Formula 1 drivers, searchable by name or country, with racing number and country. Available on the free plan. Use f","description":"List Formula 1 drivers, searchable by name or country, with racing number and country. Available on the free plan. Use for \"Which Formula 1 drivers come from Great Britain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search drivers by name.","title":"Search"},"country_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by ISO country code.","title":"Country Code"},"driver_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by specific driver IDs. One value.","title":"Driver Id"}},"title":"list_driversArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_teams":{"post":{"operationId":"list_teams","summary":"List Formula 1 teams with display name and team colour. Available on the free plan. Use for \"Which teams compete in Form","description":"List Formula 1 teams with display name and team colour. Available on the free plan. Use for \"Which teams compete in Formula 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search teams by name.","title":"Search"},"team_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by specific team IDs. One value.","title":"Team Id"}},"title":"list_teamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_circuits":{"post":{"operationId":"list_circuits","summary":"List Formula 1 circuits with country, searchable by name. Available on the free plan. Use for \"Which Formula 1 circuits ","description":"List Formula 1 circuits with country, searchable by name. Available on the free plan. Use for \"Which Formula 1 circuits are in Italy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search circuits by name.","title":"Search"},"country_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by ISO country code.","title":"Country Code"},"circuit_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by specific circuit IDs. One value.","title":"Circuit Id"}},"title":"list_circuitsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_events":{"post":{"operationId":"list_events","summary":"List Formula 1 race weekends by season or status with dates, location and circuit. Available on the free plan. Use for \"","description":"List Formula 1 race weekends by season or status with dates, location and circuit. Available on the free plan. Use for \"What are the Formula 1 race weekends of 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"season":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by season year.","title":"Season"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by event status.","title":"Status"},"circuit_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by circuit IDs. One value.","title":"Circuit Id"},"event_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by specific event IDs. One value.","title":"Event Id"}},"title":"list_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sessions":{"post":{"operationId":"list_sessions","summary":"List practice, qualifying, sprint and race sessions of Formula 1 weekends with their dates and status. Needs the PAID pl","description":"List practice, qualifying, sprint and race sessions of Formula 1 weekends with their dates and status. Needs the PAID plan or higher. Use for \"What sessions are held at Formula 1 event 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"event_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by event IDs. One value.","title":"Event Id"},"type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by session type (Practice, Qualifying, Sprint, Race).","title":"Type"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by session status.","title":"Status"}},"title":"list_sessionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_session_results":{"post":{"operationId":"list_session_results","summary":"List the finishing order of Formula 1 sessions with laps completed, pit stops and retirement flag. Needs the PAID plan o","description":"List the finishing order of Formula 1 sessions with laps completed, pit stops and retirement flag. Needs the PAID plan or higher. Use for \"Who won Formula 1 session 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"session_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by session IDs. One value.","title":"Session Id"},"driver_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by driver IDs. One value.","title":"Driver Id"}},"title":"list_session_resultsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_driver_standings":{"post":{"operationId":"get_driver_standings","summary":"Show the Formula 1 drivers' championship table of a season with position and points. Needs the PAID plan or higher. Use ","description":"Show the Formula 1 drivers' championship table of a season with position and points. Needs the PAID plan or higher. Use for \"Who leads the 2026 Formula 1 drivers' championship\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season":{"description":"Season year (required).","title":"Season","type":"integer"},"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"driver_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by driver IDs. One value.","title":"Driver Id"}},"required":["season"],"title":"get_driver_standingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_team_standings":{"post":{"operationId":"get_team_standings","summary":"Show the Formula 1 constructors' championship table of a season with position and points. Needs the PAID plan or higher.","description":"Show the Formula 1 constructors' championship table of a season with position and points. Needs the PAID plan or higher. Use for \"Which team leads the 2026 Formula 1 constructors' championship\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"season":{"description":"Season year (required).","title":"Season","type":"integer"},"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"team_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by team IDs. One value.","title":"Team Id"}},"required":["season"],"title":"get_team_standingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_lap_times":{"post":{"operationId":"list_lap_times","summary":"List lap times of Formula 1 sessions per driver and lap, with pit in and out flags. Use for \"What were the lap times in ","description":"List lap times of Formula 1 sessions per driver and lap, with pit in and out flags. Use for \"What were the lap times in Formula 1 session 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"session_id":{"description":"Filter by session IDs (required). One value.","title":"Session Id","type":"integer"},"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"driver_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by driver IDs. One value.","title":"Driver Id"},"lap_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by specific lap number.","title":"Lap Number"}},"required":["session_id"],"title":"list_lap_timesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_pit_stops":{"post":{"operationId":"list_pit_stops","summary":"List pit stops of Formula 1 sessions with lap, stop number and duration. Use for \"How long were the pit stops in Formula","description":"List pit stops of Formula 1 sessions with lap, stop number and duration. Use for \"How long were the pit stops in Formula 1 session 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cursor":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Pagination cursor: pass the next_cursor value from the previous answer to get the following page.","title":"Cursor"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many results to return per page (1 to 100).","title":"Per Page"},"session_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by session IDs. One value.","title":"Session Id"},"driver_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Filter by driver IDs. One value.","title":"Driver Id"}},"title":"list_pit_stopsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}