openapi: 3.1.0
info:
  title: Symbol Search
  version: 1.0.0
  description: tastytrade Symbol Search API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
paths:
  /symbols/search/{symbol}:
    get:
      description: Search tastytrade's tradeable instruments by symbol or symbol
        fragment — for example, searching `AAP` returns both `AAP` and `AAPL` —
        letting you power type-ahead and symbol-picker experiences. Each match
        returns lightweight metadata such as the company name, listed market,
        instrument type, and whether the symbol has listed options. This is a
        read-only lookup; use the full `/instruments/...` endpoints once you
        know the exact symbol you want to trade.
      responses:
        "200":
          description: Returns an array of symbol data for instruments matching the search
            term.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/SymbolData"
                  context:
                    type: string
                    example: /symbols/search/{symbol}
                required:
                  - data
                  - context
        "401":
          description: "Missing or expired access token, or a missing/malformed
            `User-Agent` header. tastytrade requires a `User-Agent` in
            `<product>/<version>` form and a valid `Authorization: Bearer
            <token>` (tokens expire after 15 minutes) on every request."
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: unauthorized
                    message: No valid access token was provided; access tokens expire after 15
                      minutes.
        "403":
          description: Authenticated, but the token's OAuth scope does not permit reading
            instrument data.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
                example:
                  error:
                    code: not_permitted
                    message: User not permitted access
        "429":
          description: Request rate exceeded. Back off exponentially and reduce your
            polling rate before retrying.
          content:
            application/json:
              schema:
                type: object
                description: Standard tastytrade error envelope. Branch on error.code, not the
                  message text.
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                        description: Machine-readable error code (see the Error reference).
                      message:
                        type: string
                        description: Human-readable explanation.
                      errors:
                        type: array
                        description: Present for multi-error / validation failures; one entry per
                          problem.
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            domain:
                              type: string
                required:
                  - error
      parameters:
        - in: path
          name: symbol
          required: true
          description: Symbol or fragment of a symbol to search, i.e. `AAP` will return
            AAP and AAPL data
          schema:
            type: string
          example: AAP
      operationId: searchSymbols
      tags:
        - symbol-search
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Search Symbols
servers:
  - url: https://api.cert.tastyworks.com
    description: Sandbox
  - url: https://api.tastyworks.com
    description: Production
components:
  schemas:
    SymbolData:
      type: object
      properties:
        symbol:
          type: string
          description: The instrument's unique symbol, used as its primary identifier
            across lookups, order legs, and positions.
          example: AAPL
        description:
          type: string
          description: Human-readable company or instrument name for display alongside the
            symbol.
          example: APPLE INC
        listed-market:
          type: string
          description: Code of the market where the instrument is listed (e.g. `XNAS`,
            `ARCX`, `OTC`).
          example: XNAS
        price-increments:
          type: string
          description: Allowable price increments (tick sizes) for the instrument,
            expressed as a string.
        trading-hours:
          type: string
          description: Trading hours for the instrument.
        options:
          type: boolean
          description: Whether the instrument has listed options available for trading.
          example: true
        instrument-type:
          type: string
          description: The kind of instrument the symbol represents, e.g. Equity, Equity
            Option, Future, Future Option, or Cryptocurrency.
          example: Equity
      description: A lightweight search result describing an instrument that matched a
        symbol search. It carries just enough metadata (name, market, instrument
        type, options availability) to display a match in a symbol picker; fetch
        the full instrument definition from the `/instruments/...` endpoints
        once the exact symbol is known.
x-tastytrade-service:
  serviceName: symbol-search-server
  group: symbol-search
  title: Symbol Search
tags:
  - name: symbol-search
