openapi: 3.1.0
info:
  title: Watchlists
  version: 2.2.0
  description: tastytrade Watchlists API.
  contact:
    name: tastytrade API support
    email: api.support@tastytrade.com
    url: https://developer.tastytrade.com
tags:
  - name: public-watchlists
  - name: user-watchlists
  - name: pairs-watchlists
paths:
  /public-watchlists:
    get:
      description: Returns every read-only tastytrade-published ("public") watchlist
        available to all clients. An optional boolean `counts-only` query
        parameter (default `false`) is supported.
      parameters:
        - in: query
          name: counts-only
          required: false
          schema:
            type: boolean
            default: false
          example: true
      responses:
        "200":
          description: A list of all tastytrade public watchlists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/Watchlist"
                    required:
                      - items
                  context:
                    type: string
                    example: /public-watchlists
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - public-watchlists
      operationId: getPublicWatchlists
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: List Public Watchlists
  /public-watchlists/{watchlist_name}:
    get:
      description: Returns a single read-only tastytrade public watchlist along with
        its full `watchlist-entries`.
      parameters:
        - in: path
          name: watchlist_name
          required: true
          schema:
            type: integer
            format: int32
          example: 1
      responses:
        "200":
          description: The requested public watchlist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Watchlist"
                  context:
                    type: string
                    example: /public-watchlists/{watchlist_name}
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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.
        "404":
          description: The requested public watchlist was not found. Verify the identifier
            and the environment (sandbox vs production).
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - public-watchlists
      operationId: getPublicWatchlistsWatchlistName
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Public Watchlist
  /watchlists:
    post:
      description: Creates a new watchlist for the authenticated user. The body
        requires `name` and `watchlist-entries`; each entry requires a `symbol`,
        and `instrument-type` is optional.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/postWatchlists"
        required: true
      responses:
        "201":
          description: The watchlist was created and is returned as stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Watchlist"
                  context:
                    type: string
                    example: /watchlists
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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 creating watchlists.
          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
        "422":
          description: The body is invalid in context — for example a missing required
            `name`/`watchlist-entries` or an entry without a `symbol`. Read
            `error.message` for the reason.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - user-watchlists
      operationId: postWatchlists
      x-tt-class: mutating
      x-money-moving: false
      x-idempotent: false
      x-rate-limit-bucket: write
      summary: Create Watchlist
    get:
      description: Returns every watchlist belonging to the authenticated user, each
        with its full `watchlist-entries`.
      responses:
        "200":
          description: A list of all of the user's watchlists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/Watchlist"
                    required:
                      - items
                  context:
                    type: string
                    example: /watchlists
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - user-watchlists
      operationId: getWatchlists
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: List Watchlists
  /watchlists/{watchlist_name}:
    put:
      description: Replaces **all** properties of an existing user watchlist — this is
        a full replacement, not a merge, so send the complete
        `watchlist-entries` array you want to keep; omitted entries are removed.
      parameters:
        - in: path
          name: watchlist_name
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/putWatchlistsWatchlistName"
        required: true
      responses:
        "200":
          description: The watchlist was replaced and the updated version is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Watchlist"
                  context:
                    type: string
                    example: /watchlists/{watchlist_name}
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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 modifying this watchlist.
          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 watchlist exists with the given name for this user.
          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
        "422":
          description: The body is invalid in context — for example a missing required
            `name`/`watchlist-entries` or an entry without a `symbol`. Read
            `error.message` for the reason.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - user-watchlists
      operationId: putWatchlistsWatchlistName
      x-tt-class: mutating
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: write
      summary: Replace Watchlist
    delete:
      description: Permanently deletes the named user watchlist and returns the
        deleted watchlist in the response.
      parameters:
        - in: path
          name: watchlist_name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The watchlist was deleted and is returned as it existed before
            deletion.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Watchlist"
                  context:
                    type: string
                    example: /watchlists/{watchlist_name}
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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 deleting this watchlist.
          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 watchlist exists with the given name for this user.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - user-watchlists
      operationId: deleteWatchlistsWatchlistName
      x-tt-class: mutating
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: write
      summary: Delete Watchlist
    get:
      description: Returns a single watchlist belonging to the authenticated user,
        with its full `watchlist-entries`. URL-encode the name if it contains
        spaces (for example `Tech%20Megacaps`).
      parameters:
        - in: path
          name: watchlist_name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The requested user watchlist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Watchlist"
                  context:
                    type: string
                    example: /watchlists/{watchlist_name}
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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.
        "404":
          description: No watchlist exists with the given name for this user.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - user-watchlists
      operationId: getWatchlistsWatchlistName
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Watchlist
  /pairs-watchlists:
    get:
      description: Returns every read-only tastytrade-published pairs watchlist. Each
        pairs watchlist groups related instruments via `pairs-equations` for
        pairs-trading analysis.
      responses:
        "200":
          description: A list of all tastytrade pairs watchlists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: "#/components/schemas/PairsWatchlist"
                    required:
                      - items
                  context:
                    type: string
                    example: /pairs-watchlists
                  pagination:
                    type: object
                    description: Paging metadata, present on paginated list responses.
                    properties:
                      per-page:
                        type: integer
                      page-offset:
                        type: integer
                      item-offset:
                        type: integer
                      total-items:
                        type: integer
                      total-pages:
                        type: integer
                      current-item-count:
                        type: integer
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - pairs-watchlists
      operationId: getPairsWatchlists
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: List Pairs Watchlists
  /pairs-watchlists/{pairs_watchlist_name}:
    get:
      description: Returns a single read-only tastytrade pairs watchlist, including
        its `pairs-equations`.
      parameters:
        - in: path
          name: pairs_watchlist_name
          required: true
          schema:
            type: integer
            format: int32
          example: 1
      responses:
        "200":
          description: The requested pairs watchlist.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/PairsWatchlist"
                  context:
                    type: string
                    example: /pairs-watchlists/{pairs_watchlist_name}
                required:
                  - data
                  - context
        "401":
          description: Missing or invalid access token, or a missing/malformed
            `User-Agent` header.
          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.
        "404":
          description: The requested pairs watchlist was not found. Verify the identifier
            and the environment (sandbox vs production).
          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: Rate limit exceeded. Back off exponentially 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
      tags:
        - pairs-watchlists
      operationId: getPairsWatchlistsPairsWatchlistName
      x-tt-class: read
      x-money-moving: false
      x-idempotent: true
      x-rate-limit-bucket: read
      summary: Get Pairs Watchlist
servers:
  - url: https://api.cert.tastyworks.com
    description: Sandbox
  - url: https://api.tastyworks.com
    description: Production
components:
  schemas:
    Watchlist:
      type: object
      properties:
        name:
          description: The name of the watchlist. For user watchlists it is the
            `watchlist_name` path parameter; URL-encode it when it contains
            spaces.
          type: string
          example: Tech Megacaps
        watchlist-entries:
          description: The instruments being watched. Each entry has a `symbol` and an
            optional `instrument-type`.
          type: object
        cms-id:
          description: Content management system identifier of the watchlist.
          type: string
          example: tt-tech-megacaps
        group-name:
          description: The group this watchlist belongs to, used to organize related
            watchlists.
          type: string
          example: Sectors
        order-index:
          description: The order index of the watchlist.
          type: integer
          format: int32
          example: 10
      description: A named collection of instruments to track. Used for both user
        watchlists and read-only public watchlists. JSON keys are dasherized.
    postWatchlists:
      type: object
      properties:
        name:
          type: string
          description: The watchlist name.
          example: Tech Megacaps
        group-name:
          type: string
          description: Optional group the watchlist belongs to, used to organize related
            watchlists.
          example: Sectors
        order-index:
          type: integer
          format: int32
          description: Optional order index of the watchlist. Defaults to `9999`.
          default: 9999
          example: 10
        watchlist-entries:
          type: array
          description: The instruments being watched. Each entry requires a `symbol`;
            `instrument-type` is optional.
          items:
            type: object
            properties:
              symbol:
                type: string
                description: The instrument symbol
              instrument-type:
                type: string
                description: The instrument type
            required:
              - symbol
          example:
            - symbol: AAPL
              instrument-type: Equity
            - symbol: MSFT
              instrument-type: Equity
      required:
        - name
        - watchlist-entries
      description: Request body for creating a user watchlist. Requires `name` and
        `watchlist-entries`.
    putWatchlistsWatchlistName:
      type: object
      properties:
        name:
          type: string
          description: The watchlist name.
          example: Tech Megacaps
        group-name:
          type: string
          description: Optional group the watchlist belongs to, used to organize related
            watchlists.
          example: Sectors
        order-index:
          type: integer
          format: int32
          description: Optional order index of the watchlist. Defaults to `9999`.
          default: 9999
          example: 10
        watchlist-entries:
          type: array
          description: The complete set of instruments to keep. Each entry requires a
            `symbol`; `instrument-type` is optional.
          items:
            type: object
            properties:
              symbol:
                type: string
                description: The instrument symbol
              instrument-type:
                type: string
                description: The instrument type
            required:
              - symbol
          example:
            - symbol: AAPL
              instrument-type: Equity
            - symbol: MSFT
              instrument-type: Equity
            - symbol: NVDA
              instrument-type: Equity
      required:
        - name
        - watchlist-entries
      description: "Request body for replacing a user watchlist. This is a full
        replacement: send the complete `watchlist-entries` array you want to
        keep — omitted entries are removed. Requires `name` and
        `watchlist-entries`."
    PairsWatchlist:
      type: object
      properties:
        name:
          description: The unique name of the pairs watchlist.
          type: string
          example: Index Pairs
        pairs-equations:
          description: The equations defining the instrument pairs tracked by this
            watchlist. The structure is not formally specified; inspect a live
            response before coding against it.
          type: object
        order-index:
          description: The order index of the pairs watchlist.
          type: integer
          format: int32
          example: 0
      description: A read-only tastytrade-published pairs watchlist that groups
        related instruments via pairs equations for pairs-trading analysis. JSON
        keys are dasherized.
x-tastytrade-service:
  serviceName: watchlists-api
  group: watchlists
  title: Watchlists
