openapi: 3.0.0
info:
  title: Kalshi Trade API Manual Endpoints account milestone API
  version: 3.19.0
  description: Manually defined OpenAPI spec for endpoints being migrated to spec-first approach
servers:
- url: https://external-api.kalshi.com/trade-api/v2
  description: Production Trade API server
- url: https://api.elections.kalshi.com/trade-api/v2
  description: Production shared API server, also supported
- url: https://external-api.demo.kalshi.co/trade-api/v2
  description: Demo Trade API server
- url: https://demo-api.kalshi.co/trade-api/v2
  description: Demo shared API server, also supported
tags:
- name: milestone
  description: Milestone endpoints
paths:
  /milestones/{milestone_id}:
    get:
      operationId: GetMilestone
      summary: Get Milestone
      description: ' Endpoint for getting data about a specific milestone by its ID.'
      tags:
      - milestone
      parameters:
      - name: milestone_id
        in: path
        required: true
        description: Milestone ID
        schema:
          type: string
      responses:
        '200':
          description: Milestone retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMilestoneResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /milestones:
    get:
      operationId: GetMilestones
      summary: Get Milestones
      description: 'Minimum start date to filter milestones. Format: RFC3339 timestamp'
      tags:
      - milestone
      parameters:
      - name: limit
        in: query
        description: Number of milestones to return per page
        required: true
        schema:
          type: integer
          minimum: 1
          maximum: 500
      - name: minimum_start_date
        in: query
        description: Minimum start date to filter milestones. Format RFC3339 timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: category
        in: query
        description: Filter by milestone category. E.g. Sports, Elections, Esports, Crypto.
        required: false
        schema:
          type: string
          example: Sports
      - name: competition
        in: query
        description: Filter by competition. E.g. Pro Football, Pro Basketball (M), Pro Baseball, Pro Hockey, College Football.
        required: false
        schema:
          type: string
          example: Pro Football
      - name: source_id
        in: query
        description: Filter by source id
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Filter by milestone type. E.g. football_game, basketball_game, soccer_tournament_multi_leg, baseball_game, hockey_match, political_race.
        required: false
        schema:
          type: string
          example: football_game
      - name: related_event_ticker
        in: query
        description: Filter by related event ticker
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        description: Pagination cursor. Use the cursor value returned from the previous response to get the next page of results
        required: false
        schema:
          type: string
      - name: min_updated_ts
        in: query
        required: false
        description: Filter milestones with metadata updated after this Unix timestamp (in seconds). Use this to efficiently poll for changes.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Milestones retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMilestonesResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
components:
  schemas:
    GetMilestonesResponse:
      type: object
      required:
      - milestones
      properties:
        milestones:
          type: array
          items:
            $ref: '#/components/schemas/Milestone'
          description: List of milestones.
        cursor:
          type: string
          description: Cursor for pagination.
    GetMilestoneResponse:
      type: object
      required:
      - milestone
      properties:
        milestone:
          $ref: '#/components/schemas/Milestone'
          description: The milestone data.
    Milestone:
      type: object
      required:
      - id
      - category
      - type
      - start_date
      - related_event_tickers
      - title
      - notification_message
      - details
      - primary_event_tickers
      - last_updated_ts
      properties:
        id:
          type: string
          description: Unique identifier for the milestone.
        category:
          type: string
          description: Category of the milestone. E.g. Sports, Elections, Esports, Crypto.
          example: Sports
        type:
          type: string
          description: Type of the milestone. E.g. football_game, basketball_game, soccer_tournament_multi_leg, baseball_game, hockey_match, golf_tournament, political_race.
          example: football_game
        start_date:
          type: string
          format: date-time
          description: Start date of the milestone.
        end_date:
          type: string
          format: date-time
          nullable: true
          description: End date of the milestone, if any.
        related_event_tickers:
          type: array
          items:
            type: string
          description: List of event tickers related to this milestone.
        title:
          type: string
          description: Title of the milestone.
        notification_message:
          type: string
          description: Notification message for the milestone.
        source_id:
          type: string
          nullable: true
          description: Source id of milestone if available.
        source_ids:
          type: object
          additionalProperties:
            type: string
          description: Source ids of milestone if available.
        details:
          type: object
          additionalProperties: true
          description: Additional details about the milestone.
        primary_event_tickers:
          type: array
          items:
            type: string
          description: List of event tickers directly related to the outcome of this milestone.
        last_updated_ts:
          type: string
          format: date-time
          description: Last time this structured target was updated.
  securitySchemes:
    kalshiAccessKey:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-KEY
      description: Your API key ID
    kalshiAccessSignature:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-SIGNATURE
      description: RSA-PSS signature of the request
    kalshiAccessTimestamp:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-TIMESTAMP
      description: Request timestamp in milliseconds