openapi: 3.0.1
info:
  title: Entity Sport Cricket API V2
  description: >-
    Token-authenticated REST API for cricket data from Entity Sport (Entity
    Digital Sports). Covers competitions and seasons, fixtures, results, live
    ball-by-ball scoring, scorecards, fantasy points, squads, player and team
    profiles, standings, and betting odds. Clients obtain a short-lived access
    token by POSTing access_key and secret_key to /auth, then pass the token as
    the `token` query parameter on every request.
  termsOfService: https://www.entitysport.com/terms-conditions/
  contact:
    name: Entity Sport Support
    email: sales@entitysport.com
    url: https://www.doc.entitysport.com/cricket-api-v2
  version: '2.0'
servers:
  - url: https://restapi.entitysport.com/v2
    description: Entity Sport Cricket API V2 production server
security:
  - accessToken: []
tags:
  - name: Authentication
    description: Access token generation.
  - name: Competitions
    description: Competitions, seasons, and standings.
  - name: Matches
    description: Match listing, info, and live scoring.
  - name: Scorecards
    description: Match scorecards and innings detail.
  - name: Fantasy
    description: Fantasy points and squads.
  - name: Players
    description: Player profiles and statistics.
  - name: Teams
    description: Team profiles and rosters.
  - name: Odds
    description: Cricket Exchange live odds.
paths:
  /auth:
    post:
      operationId: createAccessToken
      tags:
        - Authentication
      summary: Generate an access token.
      description: >-
        Exchanges an access_key and secret_key for a short-lived access token
        used to authenticate all subsequent requests via the `token` query
        parameter.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials.
  /seasons:
    get:
      operationId: listSeasons
      tags:
        - Competitions
      summary: List seasons.
      description: Returns available seasons identified by sid.
      parameters:
        - $ref: '#/components/parameters/token'
        - $ref: '#/components/parameters/perPage'
        - $ref: '#/components/parameters/paged'
      responses:
        '200':
          description: A list of seasons.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /competitions:
    get:
      operationId: listCompetitions
      tags:
        - Competitions
      summary: List competitions.
      description: Returns cricket competitions (tournaments, tours, cups) identified by cid.
      parameters:
        - $ref: '#/components/parameters/token'
        - name: status
          in: query
          description: Filter by competition status (e.g. live, fixture, result).
          schema:
            type: string
        - $ref: '#/components/parameters/perPage'
        - $ref: '#/components/parameters/paged'
      responses:
        '200':
          description: A list of competitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /competitions/{cid}:
    get:
      operationId: getCompetition
      tags:
        - Competitions
      summary: Get a competition.
      description: Returns details for a single competition by cid.
      parameters:
        - $ref: '#/components/parameters/cid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Competition detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /competitions/{cid}/matches:
    get:
      operationId: listCompetitionMatches
      tags:
        - Competitions
      summary: List matches for a competition.
      parameters:
        - $ref: '#/components/parameters/cid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Matches within the competition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /competitions/{cid}/standings:
    get:
      operationId: getCompetitionStandings
      tags:
        - Competitions
      summary: Get standings for a competition.
      description: Returns the points table / standings for a competition by cid.
      parameters:
        - $ref: '#/components/parameters/cid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Competition standings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches:
    get:
      operationId: listMatches
      tags:
        - Matches
      summary: List matches.
      description: Returns fixtures, live, and completed matches identified by mid.
      parameters:
        - $ref: '#/components/parameters/token'
        - name: status
          in: query
          description: Filter by match status (e.g. 1 fixture, 2 completed, 3 live).
          schema:
            type: integer
        - $ref: '#/components/parameters/perPage'
        - $ref: '#/components/parameters/paged'
      responses:
        '200':
          description: A list of matches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches/{mid}/info:
    get:
      operationId: getMatchInfo
      tags:
        - Matches
      summary: Get match info.
      description: Returns metadata and current state for a single match by mid.
      parameters:
        - $ref: '#/components/parameters/mid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Match info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches/{mid}/live:
    get:
      operationId: getMatchLive
      tags:
        - Matches
      summary: Get live ball-by-ball scoring.
      description: Returns real-time ball-by-ball live scoring for a match by mid.
      parameters:
        - $ref: '#/components/parameters/mid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Live match data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches/{mid}/scorecard:
    get:
      operationId: getMatchScorecard
      tags:
        - Scorecards
      summary: Get match scorecard.
      description: Returns full batting, bowling, and innings detail for a match by mid.
      parameters:
        - $ref: '#/components/parameters/mid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Match scorecard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches/{mid}/squads:
    get:
      operationId: getMatchSquads
      tags:
        - Fantasy
      summary: Get match squad / fantasy roster.
      description: >-
        Returns the pre-match fantasy squad/roster with player roles and fantasy
        credits for a match by mid.
      parameters:
        - $ref: '#/components/parameters/mid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Match squads.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches/{mid}/point:
    get:
      operationId: getMatchFantasyPoints
      tags:
        - Fantasy
      summary: Get match fantasy points.
      description: Returns Entity Sport fantasy cricket points for a match by mid.
      parameters:
        - $ref: '#/components/parameters/mid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Fantasy points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /matches/{mid}/odds:
    get:
      operationId: getMatchOdds
      tags:
        - Odds
      summary: Get match odds.
      description: >-
        Returns live betting odds and Cricket Exchange data for a match by mid.
        Availability depends on plan and the Cricket Exchange product.
      parameters:
        - $ref: '#/components/parameters/mid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Match odds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /players/{pid}:
    get:
      operationId: getPlayer
      tags:
        - Players
      summary: Get a player profile.
      description: Returns the profile and career statistics for a player by pid.
      parameters:
        - $ref: '#/components/parameters/pid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Player profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /teams/{tid}:
    get:
      operationId: getTeam
      tags:
        - Teams
      summary: Get a team profile.
      description: Returns the profile and roster for a team by tid.
      parameters:
        - $ref: '#/components/parameters/tid'
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          description: Team profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  securitySchemes:
    accessToken:
      type: apiKey
      in: query
      name: token
      description: >-
        Short-lived access token obtained from POST /auth, passed as the `token`
        query parameter on every request.
  parameters:
    token:
      name: token
      in: query
      required: true
      description: Short-lived access token from POST /auth.
      schema:
        type: string
    cid:
      name: cid
      in: path
      required: true
      description: Competition identifier.
      schema:
        type: integer
    mid:
      name: mid
      in: path
      required: true
      description: Match identifier.
      schema:
        type: integer
    pid:
      name: pid
      in: path
      required: true
      description: Player identifier.
      schema:
        type: integer
    tid:
      name: tid
      in: path
      required: true
      description: Team identifier.
      schema:
        type: integer
    perPage:
      name: per_page
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
    paged:
      name: paged
      in: query
      required: false
      description: Page number for paginated results.
      schema:
        type: integer
  schemas:
    AuthRequest:
      type: object
      required:
        - access_key
        - secret_key
      properties:
        access_key:
          type: string
          description: Account access key.
        secret_key:
          type: string
          description: Account secret key.
    AuthResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        response:
          type: object
          properties:
            token:
              type: string
              description: Short-lived access token.
            expires:
              type: integer
              description: Token expiry as a Unix timestamp.
    ApiResponse:
      type: object
      description: Standard Entity Sport response envelope.
      properties:
        status:
          type: string
          description: Response status (e.g. ok).
          example: ok
        response:
          type: object
          description: Endpoint-specific payload.
      additionalProperties: true