Kalshi Structured Targets API

openapi: 3.2.0
info:
  title: Kalshi Trade API Manual Endpoints Structured Targets API
  version: 3.34.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: structured-targets
  description: Structured targets endpoints
paths:
  /structured_targets:
    get:
      operationId: GetStructuredTargets
      summary: Get Structured Targets
      description: 'Page size (min: 1, max: 2000)'
      tags:
      - structured-targets
      parameters:
      - name: ids
        in: query
        description: Filter by specific structured target IDs. Pass multiple IDs by repeating the parameter (e.g. `?ids=uuid1&ids=uuid2`).
        required: false
        schema:
          type: array
          maxItems: 2000
          items:
            type: string
        style: form
        explode: true
      - name: type
        in: query
        description: Filter by structured target type
        required: false
        schema:
          type: string
          example: basketball_player
      - name: competition
        in: query
        description: Filter by competition. Matches against the league, conference, division, or tour in the structured target details, or any entry in the details leagues array.
        required: false
        schema:
          type: string
          example: NBA
      - name: page_size
        in: query
        description: Number of items per page (min 1, max 2000, default 100)
        required: false
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 2000
          default: 100
      - name: cursor
        in: query
        description: Pagination cursor
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Structured targets retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStructuredTargetsResponse'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
  /structured_targets/{structured_target_id}:
    get:
      operationId: GetStructuredTarget
      summary: Get Structured Target
      description: Endpoint for getting data about a specific structured target by its ID.
      tags:
      - structured-targets
      parameters:
      - name: structured_target_id
        in: path
        required: true
        description: Structured target ID
        schema:
          type: string
      responses:
        '200':
          description: Structured target retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStructuredTargetResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not found
        '500':
          description: Internal server error
components:
  schemas:
    StructuredTarget:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the structured target.
        name:
          type: string
          description: Name of the structured target.
        type:
          type: string
          description: Type of the structured target.
        details:
          type: object
          description: Additional details about the structured target. Contains flexible JSON data specific to the target type.
        source_id:
          type: string
          description: External source identifier for the structured target, if available (e.g., third-party data provider ID).
        source_ids:
          type: object
          additionalProperties:
            type: string
          description: Source ids of structured target if available.
        last_updated_ts:
          type: string
          format: date-time
          description: Timestamp when this structured target was last updated.
    GetStructuredTargetsResponse:
      type: object
      properties:
        structured_targets:
          type: array
          items:
            $ref: '#/components/schemas/StructuredTarget'
        cursor:
          type: string
          description: Pagination cursor for the next page. Empty if there are no more results.
    GetStructuredTargetResponse:
      type: object
      properties:
        structured_target:
          $ref: '#/components/schemas/StructuredTarget'
  securitySchemes:
    kalshiOauthAccessToken:
      type: http
      scheme: bearer
      description: User OAuth access token with read::compliance_partner, issued to an explicitly authorized partner. Accepted only on current and historical fills and current portfolio positions endpoints; generic read and partner client-credentials tokens do not grant access.
    kalshiAccessKey:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-KEY
      description: Your API key ID
    kalshiAccessSignature:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-SIGNATURE
      description: Base64 signature of the pre-sign text (timestamp + method + path) made with the API key's algorithm - RSA-PSS with SHA-256 for RSA keys, Ed25519 for Ed25519 keys
    kalshiAccessTimestamp:
      type: apiKey
      in: header
      name: KALSHI-ACCESS-TIMESTAMP
      description: Request timestamp in milliseconds
x-provenance:
  method: harvested
  publisher: Kalshi
  source: https://docs.kalshi.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)