openapi: 3.0.0
info:
  title: Kalshi Trade API Manual Endpoints account structured-targets 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: 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.
        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:
    GetStructuredTargetResponse:
      type: object
      properties:
        structured_target:
          $ref: '#/components/schemas/StructuredTarget'
    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.
    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.
  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