openapi: 3.0.3
info:
  title: Pitstop Data API
  version: 1.2.0
  description: |
    # Pitstop Data — Formula 1 Data API

    Curated, real-time Formula 1 data compiled from independent
    community-driven sources and merged into a single consistent schema.

    ## Authentication

    All endpoints (except `/health`) require a Bearer API key:

    ```
    Authorization: Bearer gp_live_xxxxxxxxxxxx
    ```

    API keys are provisioned per subscriber and scoped to a **tier** that
    controls which endpoints are accessible and how many requests can be made.

    ## Rate limits

    Every response includes rate-limit headers:

    | Header | Description |
    |--------|-------------|
    | `X-RateLimit-Limit-Minute` | Requests allowed per minute |
    | `X-RateLimit-Remaining-Minute` | Remaining requests this minute |
    | `X-RateLimit-Limit-Month` | Requests allowed per month |
    | `X-RateLimit-Remaining-Month` | Remaining requests this month |
    | `X-RateLimit-Reset` | Unix timestamp when the minute window resets |

    When a limit is exceeded the API returns `429 Too Many Requests` with a
    `Retry-After` header.

    ## Tiers

    | Tier | Endpoints |
    |------|-----------|
    | **free** | Drivers, Teams, Circuits, Seasons |
    | **starter** | + Events, Schedule, Standings, Sessions, Session Results |
    | **pro** | + Lap Times, Pit Stops |
    | **ultra** | + Driver History, Car Numbers, Team History, Weather |
    | **research** | + Raw underlying source records and conflict data |

    ## Pagination

    List endpoints accept `limit` (default 30, max 100) and `offset` query
    parameters. The response envelope includes a `pagination` object:

    ```json
    {
      "data": [...],
      "pagination": { "limit": 30, "offset": 0, "total": 120 }
    }
    ```

  contact:
    name: Pitstop Data Support
    url: https://pitstopdata.com
  license:
    name: Proprietary

servers:
  - url: /api/v1
    description: Current server

tags:
  - name: Drivers
    description: Formula 1 drivers — identity, nationality, permanent numbers.
  - name: Teams
    description: Constructors / teams.
  - name: Circuits
    description: Race circuits and track metadata.
  - name: Seasons
    description: Championship seasons.
  - name: Events
    description: Race weekends (grands prix).
  - name: Sessions
    description: Individual sessions within a race weekend (FP1, Qualifying, Race, etc.).
  - name: Results
    description: Per-driver session results.
  - name: Standings
    description: Championship standings — drivers and constructors.
  - name: Lap Times
    description: Per-lap timing data. **Pro tier and above.**
  - name: Pit Stops
    description: Pit stop records. **Pro tier and above.**

security:
  - BearerAuth: []

paths:
  /drivers:
    get:
      operationId: listDrivers
      summary: List drivers
      description: Returns all drivers. Supports filtering by nationality. **Free tier.**
      tags: [Drivers]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: nationality
          in: query
          schema:
            type: string
            example: British
          description: Filter by nationality (exact match).
      responses:
        "200":
          description: Drivers list
          headers:
            $ref: "#/components/headers/RateLimitHeaders"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriverListResponse"
              example:
                data:
                  - id: 1
                    ref_code: hamilton
                    first_name: Lewis
                    last_name: Hamilton
                    abbreviation: HAM
                    permanent_number: 44
                    nationality: British
                    nationality_code: GB
                pagination:
                  limit: 30
                  offset: 0
                  total: 20
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /drivers/{driverID}:
    get:
      operationId: getDriver
      summary: Get driver by ID
      description: Returns a single driver by their numeric ID. **Free tier.**
      tags: [Drivers]
      parameters:
        - $ref: "#/components/parameters/DriverID"
      responses:
        "200":
          description: Driver found
          headers:
            $ref: "#/components/headers/RateLimitHeaders"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriverSingleResponse"
              example:
                data:
                  id: 1
                  ref_code: hamilton
                  first_name: Lewis
                  last_name: Hamilton
                  abbreviation: HAM
                  permanent_number: 44
                  nationality: British
                  nationality_code: GB
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /drivers/ref/{driverRef}:
    get:
      operationId: getDriverByRef
      summary: Get driver by reference code
      description: |
        Returns a driver by their canonical reference code (e.g. `hamilton`, `max_verstappen`).
        Useful when you already have a slug-style identifier and need the matching record.
        **Free tier.**
      tags: [Drivers]
      parameters:
        - name: driverRef
          in: path
          required: true
          description: Canonical reference code (e.g. `hamilton`, `max_verstappen`).
          schema:
            type: string
            maxLength: 64
            example: hamilton
      responses:
        "200":
          description: Driver found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriverSingleResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /drivers/{driverID}/history:
    get:
      operationId: listDriverHistory
      summary: List driver team history
      description: Returns the season-by-season team history for a driver. **Ultra tier.**
      tags: [Drivers]
      parameters:
        - $ref: "#/components/parameters/DriverID"
      responses:
        "200":
          description: Driver team history
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriverTeamHistoryListResponse"
              example:
                data:
                  - season_year: 2024
                    team_id: 3
                    team_name: Mercedes
                    team_nationality: German
                    role: driver
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /drivers/{driverID}/car-numbers:
    get:
      operationId: listDriverCarNumbers
      summary: List driver car number assignments
      description: Returns per-season car number assignments for a driver. **Ultra tier.**
      tags: [Drivers]
      parameters:
        - $ref: "#/components/parameters/DriverID"
      responses:
        "200":
          description: Car number assignments
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DriverCarNumberListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /teams:
    get:
      operationId: listTeams
      summary: List teams
      description: Returns all constructors. Supports filtering by nationality. **Free tier.**
      tags: [Teams]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: nationality
          in: query
          schema:
            type: string
            example: British
          description: Filter by nationality (exact match).
      responses:
        "200":
          description: Teams list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamListResponse"
              example:
                data:
                  - id: 1
                    ref_code: mercedes
                    name: Mercedes
                    nationality: German
                pagination:
                  limit: 30
                  offset: 0
                  total: 10
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /teams/{teamID}:
    get:
      operationId: getTeam
      summary: Get team by ID
      description: Returns a single constructor by numeric ID. **Free tier.**
      tags: [Teams]
      parameters:
        - $ref: "#/components/parameters/TeamID"
      responses:
        "200":
          description: Team found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TeamSingleResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /teams/{teamID}/history:
    get:
      operationId: listTeamHistory
      summary: List team season history
      description: Returns season-by-season history for a constructor. **Ultra tier.**
      tags: [Teams]
      parameters:
        - $ref: "#/components/parameters/TeamID"
      responses:
        "200":
          description: Team history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"

  /teams/{teamID}/seasons:
    get:
      operationId: listTeamSeasons
      summary: List seasons a team competed in
      description: Returns each season the constructor entered. **Ultra tier.**
      tags: [Teams]
      parameters:
        - $ref: "#/components/parameters/TeamID"
      responses:
        "200":
          description: Team seasons
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"

  /circuits:
    get:
      operationId: listCircuits
      summary: List circuits
      description: Returns all circuits. Supports filtering by country. **Free tier.**
      tags: [Circuits]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: country
          in: query
          schema:
            type: string
            example: Italy
          description: Filter by country (exact match).
      responses:
        "200":
          description: Circuits list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CircuitListResponse"
              example:
                data:
                  - id: 1
                    ref_code: monza
                    name: Autodromo Nazionale Monza
                    locality: Monza
                    country: Italy
                    latitude: 45.6156
                    longitude: 9.2811
                    track_length_m: 5793
                    turns: 11
                    drs_zones: 2
                pagination:
                  limit: 30
                  offset: 0
                  total: 25
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /circuits/{circuitID}:
    get:
      operationId: getCircuit
      summary: Get circuit by ID
      description: Returns a single circuit with full track metadata. **Free tier.**
      tags: [Circuits]
      parameters:
        - $ref: "#/components/parameters/CircuitID"
      responses:
        "200":
          description: Circuit found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CircuitSingleResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /seasons:
    get:
      operationId: listSeasons
      summary: List seasons
      description: Returns all championship seasons. **Free tier.**
      tags: [Seasons]
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Seasons list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeasonListResponse"
              example:
                data:
                  - id: 77
                    year: 2024
                    official_name: 2024 FIA Formula One World Championship
                    total_rounds: 24
                    is_complete: true
                pagination:
                  limit: 30
                  offset: 0
                  total: 75
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /seasons/{year}:
    get:
      operationId: getSeason
      summary: Get season by year
      description: Returns a single season by its four-digit year. **Free tier.**
      tags: [Seasons]
      parameters:
        - name: year
          in: path
          required: true
          description: Four-digit year (1950–2100).
          schema:
            type: integer
            minimum: 1950
            maximum: 2100
            example: 2024
      responses:
        "200":
          description: Season found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeasonSingleResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /seasons/{seasonID}/events:
    get:
      operationId: listSeasonEvents
      summary: List events for a season
      description: Returns all race weekends for a season, optionally filtered by status. **Starter tier.**
      tags: [Events]
      parameters:
        - $ref: "#/components/parameters/SeasonID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: status
          in: query
          schema:
            type: string
            enum: [scheduled, completed, cancelled]
            example: completed
          description: Filter by event status.
      responses:
        "200":
          description: Events list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventListResponse"
              example:
                data:
                  - id: 101
                    round: 1
                    official_name: Gulf Air Bahrain Grand Prix
                    event_date: "2024-03-02"
                    is_sprint: false
                    status: completed
                    manual_override: false
                pagination:
                  limit: 30
                  offset: 0
                  total: 24
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /seasons/{seasonID}/schedule:
    get:
      operationId: listSeasonSchedule
      summary: List season schedule
      description: |
        Returns all race weekend events with their nested sessions in one call.
        Useful for building a full season calendar view. **Starter tier.**
      tags: [Events]
      parameters:
        - $ref: "#/components/parameters/SeasonID"
      responses:
        "200":
          description: Full season schedule with sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduleListResponse"
              example:
                data:
                  - id: 101
                    round: 1
                    official_name: Gulf Air Bahrain Grand Prix
                    event_date: "2024-03-02"
                    is_sprint: false
                    status: completed
                    manual_override: false
                    sessions:
                      - id: 501
                        event_id: 101
                        session_type: race
                        scheduled_start: "2024-03-02T15:00:00Z"
                        status: completed
                pagination:
                  limit: 30
                  offset: 0
                  total: 24
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /seasons/{seasonID}/standings/drivers:
    get:
      operationId: listDriverStandings
      summary: List driver championship standings
      description: Returns the driver standings for a season, sorted by position. **Starter tier.**
      tags: [Standings]
      parameters:
        - $ref: "#/components/parameters/SeasonID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Driver standings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandingListResponse"
              example:
                data:
                  - position: 1
                    points: 331
                    wins: 7
                    entity_id: 42
                pagination:
                  limit: 30
                  offset: 0
                  total: 20
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /seasons/{seasonID}/standings/constructors:
    get:
      operationId: listConstructorStandings
      summary: List constructor championship standings
      description: Returns the constructor standings for a season. **Starter tier.**
      tags: [Standings]
      parameters:
        - $ref: "#/components/parameters/SeasonID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Constructor standings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StandingListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /events/{eventID}:
    get:
      operationId: getEvent
      summary: Get event by ID
      description: Returns a single race weekend event. **Starter tier.**
      tags: [Events]
      parameters:
        - $ref: "#/components/parameters/EventID"
      responses:
        "200":
          description: Event found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSingleResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /events/{eventID}/sessions:
    get:
      operationId: listEventSessions
      summary: List sessions for an event
      description: Returns all sessions (FP1, FP2, Qualifying, Race, etc.) for a race weekend. **Starter tier.**
      tags: [Sessions]
      parameters:
        - $ref: "#/components/parameters/EventID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Sessions list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionListResponse"
              example:
                data:
                  - id: 501
                    event_id: 101
                    session_type: race
                    scheduled_start: "2024-03-02T15:00:00Z"
                    status: completed
                pagination:
                  limit: 30
                  offset: 0
                  total: 5
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /sessions/{sessionID}:
    get:
      operationId: getSession
      summary: Get session by ID
      description: Returns a single session. **Starter tier.**
      tags: [Sessions]
      parameters:
        - $ref: "#/components/parameters/SessionID"
      responses:
        "200":
          description: Session found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionSingleResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"

  /sessions/{sessionID}/results:
    get:
      operationId: listSessionResults
      summary: List session results
      description: |
        Returns per-driver classified results for a session, sorted by finish position.
        Includes points, status, lap count, fastest lap flag and gap to leader.
        **Starter tier.**
      tags: [Results]
      parameters:
        - $ref: "#/components/parameters/SessionID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Session results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResultListResponse"
              example:
                data:
                  - driver_id: 1
                    team_id: 3
                    position: 1
                    grid_position: 1
                    points: 25
                    status: Finished
                    laps_completed: 57
                    gap_to_leader: ""
                    fastest_lap: true
                    time_ms: 5583714
                pagination:
                  limit: 30
                  offset: 0
                  total: 20
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /sessions/{sessionID}/laps:
    get:
      operationId: listLapTimes
      summary: List lap times for a session
      description: |
        Returns per-driver per-lap timing data including sector times, tyre compound
        and personal best flag. **Pro tier.**
      tags: [Lap Times]
      parameters:
        - $ref: "#/components/parameters/SessionID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: driver_id
          in: query
          schema:
            type: integer
            format: int64
            example: 1
          description: Filter by driver ID.
      responses:
        "200":
          description: Lap times
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LapTimeListResponse"
              example:
                data:
                  - driver_id: 1
                    lap_number: 1
                    time_ms: 98234
                    sector1_ms: 31100
                    sector2_ms: 35200
                    sector3_ms: 31934
                    is_personal_best: false
                    compound: MEDIUM
                pagination:
                  limit: 30
                  offset: 0
                  total: 1140
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /sessions/{sessionID}/pitstops:
    get:
      operationId: listPitStops
      summary: List pit stops for a session
      description: |
        Returns all pit stop records for a session including lap, stop number,
        duration and tyre compounds. **Pro tier.**
      tags: [Pit Stops]
      parameters:
        - $ref: "#/components/parameters/SessionID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: driver_id
          in: query
          schema:
            type: integer
            format: int64
            example: 1
          description: Filter by driver ID.
      responses:
        "200":
          description: Pit stops
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PitStopListResponse"
              example:
                data:
                  - driver_id: 1
                    stop_number: 1
                    lap: 22
                    duration_ms: 2340
                    compound_from: MEDIUM
                    compound_to: HARD
                pagination:
                  limit: 30
                  offset: 0
                  total: 40
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /sessions/{sessionID}/weather:
    get:
      operationId: getSessionWeather
      summary: Get session weather
      description: Returns weather conditions recorded during a session. **Ultra tier.**
      tags: [Sessions]
      parameters:
        - $ref: "#/components/parameters/SessionID"
      responses:
        "200":
          description: Weather data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key issued per subscriber. Pass it as a Bearer token:
        ```
        Authorization: Bearer gp_live_xxxxxxxxxxxx
        ```

  headers:
    RateLimitHeaders:
      X-RateLimit-Limit-Minute:
        description: Requests allowed per minute for this tier.
        schema:
          type: integer
      X-RateLimit-Remaining-Minute:
        description: Requests remaining in the current minute window.
        schema:
          type: integer
      X-RateLimit-Limit-Month:
        description: Requests allowed per month for this tier.
        schema:
          type: integer
      X-RateLimit-Remaining-Month:
        description: Requests remaining in the current month.
        schema:
          type: integer
      X-RateLimit-Reset:
        description: Unix timestamp when the minute window resets.
        schema:
          type: integer
          format: int64

  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 30
        minimum: 1
        maximum: 100
      description: Number of results to return (max 100).
    Offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
        maximum: 10000
      description: Number of results to skip.
    SeasonID:
      name: seasonID
      in: path
      required: true
      description: Numeric season identifier.
      schema:
        type: integer
        format: int64
        example: 77
    EventID:
      name: eventID
      in: path
      required: true
      description: Numeric event identifier.
      schema:
        type: integer
        format: int64
        example: 101
    SessionID:
      name: sessionID
      in: path
      required: true
      description: Numeric session identifier.
      schema:
        type: integer
        format: int64
        example: 501
    DriverID:
      name: driverID
      in: path
      required: true
      description: Numeric driver identifier.
      schema:
        type: integer
        format: int64
        example: 1
    TeamID:
      name: teamID
      in: path
      required: true
      description: Numeric team identifier.
      schema:
        type: integer
        format: int64
        example: 3
    CircuitID:
      name: circuitID
      in: path
      required: true
      description: Numeric circuit identifier.
      schema:
        type: integer
        format: int64
        example: 14

  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            error:
              code: auth_required
              message: Authentication required. Provide a valid Bearer API key.
    Forbidden:
      description: API key does not have access to this endpoint (tier restriction).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            error:
              code: forbidden
              message: Your current plan does not include access to this endpoint. Upgrade to unlock it.
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            error:
              code: bad_request
              message: invalid driver ID
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            error:
              code: not_found
              message: resource not found
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the rate limit resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RateLimitError"
          example:
            error:
              code: rate_limit_minute
              message: Per-minute rate limit exceeded. Please slow down.
              limit: 10
              used: 10
              reset_at: "2026-04-04T12:01:00Z"
              upgrade_url: https://rapidapi.com/gridpulse/pricing
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            error:
              code: internal_error
              message: failed to process request

  schemas:
    APIError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              example: not_found
            message:
              type: string
              example: resource not found
            request_id:
              type: string
              example: abc123

    RateLimitError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, limit, used, reset_at]
          properties:
            code:
              type: string
              enum: [rate_limit_minute, rate_limit_monthly]
            message:
              type: string
            limit:
              type: integer
            used:
              type: integer
            reset_at:
              type: string
              format: date-time
            upgrade_url:
              type: string
              format: uri

    Pagination:
      type: object
      required: [limit, offset, total]
      properties:
        limit:
          type: integer
          example: 30
        offset:
          type: integer
          example: 0
        total:
          type: integer
          format: int64
          example: 120

    Driver:
      type: object
      required: [id, ref_code, first_name, last_name]
      properties:
        id:
          type: integer
          format: int64
          example: 1
        ref_code:
          type: string
          example: hamilton
        first_name:
          type: string
          example: Lewis
        last_name:
          type: string
          example: Hamilton
        abbreviation:
          type: string
          example: HAM
        permanent_number:
          type: integer
          nullable: true
          example: 44
        nationality:
          type: string
          example: British
        nationality_code:
          type: string
          example: GB

    Team:
      type: object
      required: [id, ref_code, name]
      properties:
        id:
          type: integer
          format: int64
          example: 3
        ref_code:
          type: string
          example: mercedes
        name:
          type: string
          example: Mercedes
        nationality:
          type: string
          example: German

    Season:
      type: object
      required: [id, year, is_complete]
      properties:
        id:
          type: integer
          format: int64
          example: 77
        year:
          type: integer
          example: 2024
        official_name:
          type: string
          example: 2024 FIA Formula One World Championship
        total_rounds:
          type: integer
          nullable: true
          example: 24
        is_complete:
          type: boolean
          example: true

    Event:
      type: object
      required: [id, round, official_name, event_date, is_sprint, status]
      properties:
        id:
          type: integer
          format: int64
          example: 101
        round:
          type: integer
          example: 1
        official_name:
          type: string
          example: Gulf Air Bahrain Grand Prix
        event_date:
          type: string
          format: date
          example: "2024-03-02"
        is_sprint:
          type: boolean
          example: false
        status:
          type: string
          enum: [scheduled, completed, cancelled]
          example: completed
        manual_override:
          type: boolean
          example: false

    Session:
      type: object
      required: [id, event_id, session_type, status]
      properties:
        id:
          type: integer
          format: int64
          example: 501
        event_id:
          type: integer
          format: int64
          example: 101
        session_type:
          type: string
          enum: [fp1, fp2, fp3, qualifying, sprint_qualifying, sprint, race]
          example: race
        scheduled_start:
          type: string
          format: date-time
          nullable: true
          example: "2024-03-02T15:00:00Z"
        status:
          type: string
          enum: [scheduled, completed, cancelled]
          example: completed

    ScheduleEvent:
      allOf:
        - $ref: "#/components/schemas/Event"
        - type: object
          required: [sessions]
          properties:
            sessions:
              type: array
              items:
                $ref: "#/components/schemas/Session"

    Standing:
      type: object
      required: [position, points, wins, entity_id]
      properties:
        position:
          type: integer
          example: 1
        points:
          type: number
          format: double
          example: 331
        wins:
          type: integer
          example: 7
        entity_id:
          type: integer
          format: int64
          description: Driver ID for driver standings; team ID for constructor standings.
          example: 42

    SessionResult:
      type: object
      required: [driver_id, points, status]
      properties:
        driver_id:
          type: integer
          format: int64
          example: 1
        team_id:
          type: integer
          format: int64
          nullable: true
          example: 3
        position:
          type: integer
          nullable: true
          example: 1
        grid_position:
          type: integer
          nullable: true
          example: 1
        points:
          type: number
          format: double
          example: 25
        status:
          type: string
          example: Finished
        status_detail:
          type: string
          nullable: true
        laps_completed:
          type: integer
          nullable: true
          example: 57
        gap_to_leader:
          type: string
          nullable: true
          example: "+5.123s"
        fastest_lap:
          type: boolean
          example: false
        time_ms:
          type: integer
          format: int64
          nullable: true
          example: 5583714

    Circuit:
      type: object
      required: [id, ref_code, name, country]
      properties:
        id:
          type: integer
          format: int64
          example: 14
        ref_code:
          type: string
          example: monza
        name:
          type: string
          example: Autodromo Nazionale Monza
        locality:
          type: string
          example: Monza
        country:
          type: string
          example: Italy
        latitude:
          type: number
          format: double
          nullable: true
          example: 45.6156
        longitude:
          type: number
          format: double
          nullable: true
          example: 9.2811
        altitude_m:
          type: integer
          nullable: true
          example: 162
        track_length_m:
          type: integer
          nullable: true
          example: 5793
        turns:
          type: integer
          nullable: true
          example: 11
        drs_zones:
          type: integer
          nullable: true
          example: 2

    LapTime:
      type: object
      required: [driver_id, lap_number]
      properties:
        driver_id:
          type: integer
          format: int64
          example: 1
        lap_number:
          type: integer
          example: 1
        time_ms:
          type: integer
          format: int64
          nullable: true
          example: 98234
        sector1_ms:
          type: integer
          format: int64
          nullable: true
          example: 31100
        sector2_ms:
          type: integer
          format: int64
          nullable: true
          example: 35200
        sector3_ms:
          type: integer
          format: int64
          nullable: true
          example: 31934
        is_personal_best:
          type: boolean
          example: false
        compound:
          type: string
          enum: [SOFT, MEDIUM, HARD, INTERMEDIATE, WET]
          example: MEDIUM

    PitStop:
      type: object
      required: [driver_id, stop_number, lap]
      properties:
        driver_id:
          type: integer
          format: int64
          example: 1
        stop_number:
          type: integer
          example: 1
        lap:
          type: integer
          example: 22
        duration_ms:
          type: integer
          format: int64
          nullable: true
          example: 2340
        compound_from:
          type: string
          example: MEDIUM
        compound_to:
          type: string
          example: HARD

    DriverTeamHistory:
      type: object
      required: [season_year, team_id, team_name, role]
      properties:
        season_year:
          type: integer
          example: 2024
        team_id:
          type: integer
          format: int64
          example: 3
        team_name:
          type: string
          example: Mercedes
        team_nationality:
          type: string
          example: German
        role:
          type: string
          example: driver

    DriverCarNumber:
      type: object
      required: [season_year, car_number, round]
      properties:
        season_year:
          type: integer
          example: 2024
        car_number:
          type: integer
          example: 44
        round:
          type: integer
          example: 1

    # ── Response envelopes ────────────────────────────────────────────────────

    DriverListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Driver"
        pagination:
          $ref: "#/components/schemas/Pagination"

    DriverSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/Driver"

    TeamListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Team"
        pagination:
          $ref: "#/components/schemas/Pagination"

    TeamSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/Team"

    SeasonListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Season"
        pagination:
          $ref: "#/components/schemas/Pagination"

    SeasonSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/Season"

    EventListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Event"
        pagination:
          $ref: "#/components/schemas/Pagination"

    EventSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/Event"

    SessionListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Session"
        pagination:
          $ref: "#/components/schemas/Pagination"

    SessionSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/Session"

    ScheduleListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ScheduleEvent"
        pagination:
          $ref: "#/components/schemas/Pagination"

    StandingListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Standing"
        pagination:
          $ref: "#/components/schemas/Pagination"

    SessionResultListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SessionResult"
        pagination:
          $ref: "#/components/schemas/Pagination"

    CircuitListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Circuit"
        pagination:
          $ref: "#/components/schemas/Pagination"

    CircuitSingleResponse:
      type: object
      required: [data]
      properties:
        data:
          $ref: "#/components/schemas/Circuit"

    LapTimeListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/LapTime"
        pagination:
          $ref: "#/components/schemas/Pagination"

    PitStopListResponse:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/PitStop"
        pagination:
          $ref: "#/components/schemas/Pagination"

    DriverTeamHistoryListResponse:
      type: object
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/DriverTeamHistory"

    DriverCarNumberListResponse:
      type: object
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/DriverCarNumber"