openapi: 3.1.0
info:
  title: Quote Alerts
  version: 1.23.2
  description: tastytrade Quote Alerts API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
tags:
  - name: quote-alerts
paths:
  /quote-alerts:
    get:
      description: Returns quote alerts for the authenticated user. Use it to render
        an alert dashboard or to reconcile local state before creating or
        cancelling alerts.
      responses:
        "200":
          description: The authenticated user's quote alerts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/QuoteAlertDeserializer"
                  context:
                    type: string
                    example: /quote-alerts
                required:
                  - data
                  - context
        "401":
          description: "Missing, expired, or invalid access token, or a missing/malformed
            `User-Agent` header. Send `Authorization: Bearer <token>` (tokens
            last 15 minutes) and a `User-Agent` like `my-app/1.0`."
          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.
        "429":
          description: Too many requests in a short period. Back off exponentially and
            reduce your request rate.
          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
      tags:
        - quote-alerts
      operationId: getQuoteAlerts
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: List Quote Alerts
    post:
      description: Creates a quote alert for a symbol. Provide a `field` (`Last`,
        `Bid`, `Ask`, or `IV`), an `operator` (`>` or `<`), the `symbol`, and a
        `threshold` the watched field is compared against. Keys are dasherized
        and the request body must be JSON.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/postQuoteAlerts"
        required: true
      responses:
        "201":
          description: The newly created quote alert.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/QuoteAlertDeserializer"
                  context:
                    type: string
                    example: /quote-alerts
                required:
                  - data
                  - context
        "401":
          description: "Missing, expired, or invalid access token, or a missing/malformed
            `User-Agent` header. Send `Authorization: Bearer <token>` (tokens
            last 15 minutes) and a `User-Agent` like `my-app/1.0`."
          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.
        "422":
          description: The alert could not be created — for example a missing required
            field or an unrecognized `field`/`operator` value. The reason is in
            the response JSON's `error.message`.
          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: preflight_check_failure
                    message: One or more preflight checks failed
                    errors:
                      - code: preflight_check_failure
                        message: A specific validation failed for this order.
        "429":
          description: Too many requests in a short period. Back off exponentially and
            reduce your request rate.
          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
      tags:
        - quote-alerts
      operationId: postQuoteAlerts
      x-tt-class: mutating
      x-money-moving: false
      x-idempotent: false
      x-rate-limit-bucket: write
      summary: Create Quote Alert
  /quote-alerts/{alert_external_id}:
    delete:
      description: Cancels (deletes) the quote alert identified by its
        `alert_external_id` for the authenticated user. On success the alert is
        no longer active and the endpoint returns an empty `204 No Content`
        response. This operation is idempotent.
      parameters:
        - in: path
          name: alert_external_id
          required: true
          schema:
            type: integer
            format: int32
          example: 1
      responses:
        "204":
          description: The quote alert was cancelled successfully. No response body is
            returned.
        "401":
          description: "Missing, expired, or invalid access token, or a missing/malformed
            `User-Agent` header. Send `Authorization: Bearer <token>` (tokens
            last 15 minutes) and a `User-Agent` like `my-app/1.0`."
          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 scope or account authority does not
            permit cancelling this alert.
          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
        "404":
          description: No quote alert exists for the supplied `alert_external_id`.
          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
        "429":
          description: Too many requests in a short period. Back off exponentially and
            reduce your request rate.
          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
      tags:
        - quote-alerts
      operationId: deleteQuoteAlertsAlertExternalId
      x-tt-class: mutating
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: write
      summary: Cancel Quote Alert
servers:
  - url: https://api.cert.tastyworks.com
    description: Sandbox
  - url: https://api.tastyworks.com
    description: Production
components:
  schemas:
    postQuoteAlerts:
      type: object
      properties:
        dx-symbol:
          type: string
          description: The DXLink streamer symbol for the instrument.
          example: AAPL
        expires-at:
          type: string
          description: Optional expiration time for the alert.
          example: 2026-12-31T23:59:59.000Z
        field:
          type: string
          enum:
            - Last
            - Bid
            - Ask
            - IV
          description: The quote field to watch. One of `Last`, `Bid`, `Ask`, or `IV`
            (implied volatility).
          example: Last
        instrument-type:
          type: string
          description: The type of instrument the alert is for, such as `Equity` or
            `Equity Option`.
          example: Equity
        operator:
          type: string
          enum:
            - ">"
            - <
          description: The comparison operator applied between the watched `field` and the
            `threshold`. Either `>` (greater than) or `<` (less than).
          example: ">"
        symbol:
          type: string
          description: The tastytrade symbol for the instrument to watch, for example an
            equity symbol like `AAPL`.
          example: AAPL
        threshold:
          type: string
          description: The threshold value the watched `field` is compared against, sent
            as a string-decimal.
          example: "150.25"
        threshold-numeric:
          type: string
          description: Optional numeric form of the threshold value.
          example: "150.25"
      required:
        - field
        - operator
        - symbol
        - threshold
      description: Request body for creating a quote alert that watches `field`
        against `threshold` according to `operator` for the given `symbol`.
        `field`, `operator`, `symbol`, and `threshold` are required; keys are
        dasherized.
    QuoteAlertDeserializer:
      type: object
      properties:
        alert-external-id:
          description: Unique external identifier for the alert. Use this value as the
            `alert_external_id` path parameter when cancelling the alert.
          type: string
          example: "12345"
        completed-at:
          description: ISO-8601 timestamp when the alert finished its lifecycle (for
            example after it triggered).
          type: string
          format: date-time
          example: 2026-06-05T18:12:43.000Z
        created-at:
          description: ISO-8601 timestamp when the alert was created.
          type: string
          format: date-time
          example: 2026-06-01T14:30:00.000Z
        dismissed-at:
          description: ISO-8601 timestamp when the alert was dismissed by the user, if
            applicable.
          type: string
          format: date-time
          example: 2026-06-06T08:00:00.000Z
        dx-symbol:
          description: The DXLink streamer symbol for the watched instrument.
          type: string
          example: AAPL
        expired-at:
          description: ISO-8601 timestamp when the alert expired without triggering, if
            applicable.
          type: string
          format: date-time
          example: 2026-12-31T23:59:59.000Z
        expires-at:
          description: The configured expiration time for the alert.
          type: string
          example: 2026-12-31T23:59:59.000Z
        field:
          description: The quote field the alert watches, such as `Last`, `Bid`, `Ask`, or
            `IV`.
          type: string
          example: Last
        instrument-type:
          description: The type of instrument the alert is for, such as `Equity`.
          type: string
          example: Equity
        operator:
          description: The comparison operator between the watched field and the
            threshold, either `>` or `<`.
          type: string
          example: ">"
        provider:
          description: The market-data provider that supplies the quotes for this alert.
          type: string
        symbol:
          description: The tastytrade symbol for the watched instrument.
          type: string
          example: AAPL
        threshold:
          description: The threshold value the watched field is compared against, as a
            string-decimal.
          type: string
          example: "150.25"
        threshold-numeric:
          description: Numeric form of the threshold value. Decimal value serialized as a
            JSON string (e.g. "150.25").
          type: string
          format: decimal
          example: "150.25"
        triggered-at:
          description: ISO-8601 timestamp when the alert condition was first met and the
            alert fired.
          type: string
          format: date-time
          example: 2026-06-05T18:12:43.000Z
        user-external-id:
          description: External identifier of the user that owns the alert.
          type: string
      description: A quote alert belonging to a user. Describes the watched instrument
        and condition along with timestamps recording the alert's lifecycle
        (created, triggered, completed, expired, or dismissed).
x-tastytrade-service:
  serviceName: quote-alerts-api
  group: quote-alerts
  title: Quote Alerts
