{
  "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"
    }
  ]
}