Odds-API.io Mappings API

openapi: 3.2.0
info:
  description: 'Odds-API.io is a powerful sports betting odds comparison API, providing real-time data from 450+ bookmakers across 34 sports with near zero latency.


    - 450+ bookmakers supported

    - 34 sports including Football, Basketball, Tennis, Esports and more

    - Real-time odds with close to zero latency

    - Pre-match & In-play odds coverage

    - 99.9% uptime for reliability'
  title: Odds-API.io - Real-Time Sports Betting Odds API (v3)…
  contact: {}
  version: 3.0.0
servers:
- url: https://api.odds-api.io/v3
tags:
- name: Mappings
paths:
  /mappings:
    get:
      security:
      - ApiKeyAuth: []
      description: 'Maps our events and selections to a bookmaker''s own identifiers, so our prices can be matched to the bookmaker''s own markets. For Polymarket, `marketId` is the conditionId and `outcomeId` is the CLOB token id. For Kalshi, `marketId` is the contract ticker and `outcomeId` is `yes` or `no`. Each row carries our event''s `home`, `away`, `date`, `sport` and `league`.


        Modes:

        - `eventId`, or `eventIds` with up to 10 ids

        - `marketId`, or `marketIds` with up to 10 ids, optionally with `outcomeId`

        - `outcomeId` alone

        - bulk sync: `bookmaker` with none of the above. Returns every mapping for upcoming and live linked events as `{ "data": [...], "nextCursor": "..." }`. Pass `nextCursor` back as `cursor` until it is `null`.


        Every mode returns `{data, nextCursor}`; `nextCursor` is null for lookups. `market` and `active` narrow every mode; `sport`, `league`, `limit` and `cursor` apply to bulk sync only. When `outcomeId` alone matches outcomes in more than one market (Kalshi outcome ids are `yes` and `no`), the request returns 400 and `marketId` must be added. `market`, `hdp` and `side` use our event''s orientation, the same as `/v3/odds`. A mapping stays listed with `active: false` after the bookmaker withdraws the outcome. A batch or bulk call counts as one request. Available on paid plans; the bookmaker must be in your selection.'
      tags:
      - Mappings
      summary: Get Native ID Mappings
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: Polymarket
        description: Bookmaker name
        name: bookmaker
        in: query
        required: true
        schema:
          type: string
      - example: '71515842'
        description: Our event id. Returns every mapping of this event.
        name: eventId
        in: query
        schema:
          type: string
      - example: 71515842,71515900
        description: Comma-separated list of up to 10 of our event ids. Use instead of `eventId`.
        name: eventIds
        in: query
        schema:
          type: string
      - description: The bookmaker's market id (Polymarket conditionId, Kalshi contract ticker). Can be combined with `outcomeId`.
        name: marketId
        in: query
        schema:
          type: string
      - example: KXNFLGAME-26OCT04BUFNE-BUF,KXNFLGAME-26OCT04BUFNE-NE
        description: Comma-separated list of up to 10 bookmaker market ids. Use instead of `marketId`; can be combined with `outcomeId`.
        name: marketIds
        in: query
        schema:
          type: string
      - description: The bookmaker's outcome id (Polymarket CLOB token id, Kalshi `yes` or `no`). For Kalshi, pass it together with `marketId`.
        name: outcomeId
        in: query
        schema:
          type: string
      - example: Spread
        description: Only this market, by its exact name as served in `/v3/odds` (case-sensitive).
        name: market
        in: query
        schema:
          type: string
      - description: '`true` for outcomes the bookmaker still lists, `false` for withdrawn ones. Default: both.'
        name: active
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - example: american-football
        description: 'Bulk sync only: sport slug or name.'
        name: sport
        in: query
        schema:
          type: string
      - example: usa-nfl
        description: 'Bulk sync only: league slug. Requires `sport`.'
        name: league
        in: query
        schema:
          type: string
      - description: 'Bulk sync only: rows per page.'
        name: limit
        in: query
        schema:
          type: integer
          default: 1000
          minimum: 1
          maximum: 5000
      - description: 'Bulk sync only: the `nextCursor` of the previous page.'
        name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK. data holds the mappings; nextCursor is set only in bulk sync while more pages remain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NativeIDMappingPage'
        '400':
          description: Bad Request Also returned when a lookup matches more than 5000 mappings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found (unknown league in bulk sync)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Map our events and selections to a bookmaker's own ids, such as Polymarket condition and token ids or Kalshi tickers, by event, market or bulk sync.
      operationId: getMappings
      x-operation-id-source: derived
components:
  schemas:
    controllers.Sport:
      type: object
      properties:
        name:
          type: string
          example: Football
        slug:
          type: string
          example: football
    controllers.NativeIDMappingPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/controllers.NativeIDMapping'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as `cursor` to get the next page. `null` on the last page.
      description: Every /v3/mappings response. nextCursor is null for lookups and set in bulk sync while more pages remain.
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    controllers.League:
      type: object
      properties:
        name:
          type: string
          example: Premier League
        slug:
          type: string
          example: premier-league
    controllers.NativeIDMapping:
      type: object
      properties:
        eventId:
          type: integer
          example: 71515842
          description: Our event id
        home:
          type: string
          example: Pittsburgh Steelers
          description: Home team of our event, in our orientation
        away:
          type: string
          example: Cleveland Browns
          description: Away team of our event, in our orientation
        date:
          type: string
          format: date-time
          description: Start time of our event
        sport:
          $ref: '#/components/schemas/controllers.Sport'
        league:
          $ref: '#/components/schemas/controllers.League'
        bookmaker:
          type: string
          example: Polymarket
        market:
          type: string
          example: Spread
          description: Market name, as in /v3/odds
        label:
          type: string
          description: Selection label for labelled markets such as player props
        hdp:
          type: number
          example: -2.5
          description: The line as /v3/odds shows it (the home handicap on a Spread). Omitted on markets without a line
        side:
          type: string
          example: home
          enum:
          - home
          - away
          - draw
          - over
          - under
          - 'yes'
          - 'no'
        nativeEventId:
          type: string
          example: '885112'
          description: 'The bookmaker''s event id. For Polymarket it is the same value as `bookmakerIds` in `/v3/odds`. For Kalshi it is the event ticker the contract belongs to: the game ticker (the `bookmakerIds` value) for ML, and the spread or total event ticker for those contracts.'
        marketId:
          type: string
          example: 0x3b5c0c7e...
          description: The bookmaker's market id (Polymarket conditionId, Kalshi contract ticker)
        outcomeId:
          type: string
          example: '71321045679252212594626385532706912750332728571942532289631379312455583992563'
          description: The bookmaker's outcome id (Polymarket CLOB token id, Kalshi `yes` or `no`)
        outcomeLabel:
          type: string
          example: Browns
          description: The outcome's name at the bookmaker
        extra:
          type: object
          additionalProperties: {}
          description: Bookmaker-specific details, such as the Polymarket question
        active:
          type: boolean
          example: true
          description: False once the bookmaker stopped listing the outcome
        firstSeenAt:
          type: string
          format: date-time
        lastCheckedAt:
          type: string
          format: date-time
          description: When we last saw the outcome at the bookmaker. Refreshed at least every 30 minutes while we track the event; Polymarket mappings stop refreshing at kickoff.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: Your Odds-API.io API key, sent as the apiKey query parameter. Get one at https://odds-api.io/pricing.
x-origin:
- url: https://api.odds-api.io/v3/docs/doc.json
  format: swagger
  version: '2.0'
  converter:
    url: https://github.com/mermade/oas-kit
    version: 7.0.8