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