{
  "openapi": "3.0.3",
  "info": {
    "title": "StockTwits API",
    "description": "The StockTwits API provides access to the StockTwits social network for investors and traders. It allows developers to access streams of messages (twits), user profiles, trending symbols, and more. StockTwits is a social media platform designed for sharing ideas between investors, traders, and entrepreneurs.",
    "version": "2.0",
    "contact": {
      "name": "StockTwits",
      "url": "https://stocktwits.com"
    },
    "termsOfService": "https://stocktwits.com/terms",
    "x-jentic-source-url": "https://raw.githubusercontent.com/sophie-jentic/openapi-specs/refs/heads/import-jentic-pr-specs/stocktwits.com/stocktwits-api/2.0/openapi.json"
  },
  "servers": [
    {
      "url": "https://api.stocktwits.com/api/2",
      "description": "StockTwits API v2 Production"
    }
  ],
  "paths": {
    "/streams/symbol/{symbol}.json": {
      "get": {
        "operationId": "getSymbolStream",
        "summary": "Symbol Stream",
        "description": "Returns the most recent messages for the specified symbol. This stream includes all messages that contain the specified symbol, including those from private accounts if the authenticated user follows them.",
        "tags": [
          "Streams"
        ],
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Ticker symbol, e.g. AAPL, TSLA",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          },
          {
            "name": "filter",
            "in": "query",
            "description": "Filter messages by links, charts, or videos",
            "schema": {
              "type": "string",
              "enum": [
                "links",
                "charts",
                "videos"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with messages for the symbol",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          },
          "404": {
            "description": "Symbol not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/streams/user/{user_id}.json": {
      "get": {
        "operationId": "getUserStream",
        "summary": "User Stream",
        "description": "Returns the most recent messages for the specified user.",
        "tags": [
          "Streams"
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "User ID or username",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          },
          {
            "name": "filter",
            "in": "query",
            "description": "Filter messages by links, charts, or videos",
            "schema": {
              "type": "string",
              "enum": [
                "links",
                "charts",
                "videos"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with messages for the user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/streams/home.json": {
      "get": {
        "operationId": "getHomeStream",
        "summary": "Home Stream",
        "description": "Returns the most recent messages from the authenticated user's home stream, including messages from users and symbols they follow.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "oauth2": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          },
          {
            "name": "filter",
            "in": "query",
            "description": "Filter messages by links, charts, or videos",
            "schema": {
              "type": "string",
              "enum": [
                "links",
                "charts",
                "videos"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with home stream messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/streams/friends.json": {
      "get": {
        "operationId": "getFriendsStream",
        "summary": "Friends Stream",
        "description": "Returns the most recent messages from users the authenticated user follows.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "oauth2": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/streams/trending.json": {
      "get": {
        "operationId": "getTrendingStream",
        "summary": "Trending Stream",
        "description": "Returns the most recent messages with trending sentiment on StockTwits.",
        "tags": [
          "Streams"
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with trending messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          }
        }
      }
    },
    "/streams/all.json": {
      "get": {
        "operationId": "getAllStream",
        "summary": "All Stream",
        "description": "Returns the most recent messages across StockTwits.",
        "tags": [
          "Streams"
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          },
          {
            "name": "filter",
            "in": "query",
            "description": "Filter messages by links, charts, or videos",
            "schema": {
              "type": "string",
              "enum": [
                "links",
                "charts",
                "videos"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with all stream messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          }
        }
      }
    },
    "/streams/watchlist/{watchlist_id}.json": {
      "get": {
        "operationId": "getWatchlistStream",
        "summary": "Watchlist Stream",
        "description": "Returns the most recent messages for the symbols in the specified watchlist.",
        "tags": [
          "Streams"
        ],
        "security": [
          {
            "oauth2": []
          }
        ],
        "parameters": [
          {
            "name": "watchlist_id",
            "in": "path",
            "required": true,
            "description": "The watchlist ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "Returns results with an ID greater than the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max",
            "in": "query",
            "description": "Returns results with an ID less than or equal to the specified ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of results to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/messages/show/{message_id}.json": {
      "get": {
        "operationId": "getMessage",
        "summary": "Show Message",
        "description": "Returns the specified message by ID.",
        "tags": [
          "Messages"
        ],
        "parameters": [
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "description": "The message ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with the message",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "message": {
                      "$ref": "#/components/schemas/Message"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Message not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/messages/create.json": {
      "post": {
        "operationId": "createMessage",
        "summary": "Create Message",
        "description": "Creates a new message (twit) for the authenticated user.",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "oauth2": [
              "publish_messages"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "body"
                ],
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The body of the message. Must include a $TICKER symbol (e.g. $AAPL). Max 1000 characters.",
                    "maxLength": 1000
                  },
                  "in_reply_to_message_id": {
                    "type": "integer",
                    "description": "The ID of the message being replied to"
                  },
                  "sentiment": {
                    "type": "string",
                    "description": "The sentiment of the message",
                    "enum": [
                      "bullish",
                      "bearish"
                    ]
                  },
                  "chart": {
                    "type": "string",
                    "format": "binary",
                    "description": "A chart image to attach to the message"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "message": {
                      "$ref": "#/components/schemas/Message"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error (e.g. missing ticker symbol)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/messages/like.json": {
      "post": {
        "operationId": "likeMessage",
        "summary": "Like Message",
        "description": "Likes a message for the authenticated user.",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "oauth2": [
              "publish_messages"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "integer",
                    "description": "The ID of the message to like"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message liked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "message": {
                      "$ref": "#/components/schemas/Message"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/messages/unlike.json": {
      "post": {
        "operationId": "unlikeMessage",
        "summary": "Unlike Message",
        "description": "Unlikes a previously liked message for the authenticated user.",
        "tags": [
          "Messages"
        ],
        "security": [
          {
            "oauth2": [
              "publish_messages"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "id"
                ],
                "properties": {
                  "id": {
                    "type": "integer",
                    "description": "The ID of the message to unlike"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message unliked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "message": {
                      "$ref": "#/components/schemas/Message"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search.json": {
      "get": {
        "operationId": "search",
        "summary": "Search",
        "description": "Search for symbols and users on StockTwits.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The search query (prefix match for symbols and usernames)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "symbol",
                              "user"
                            ]
                          },
                          "symbol": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "username": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/symbols.json": {
      "get": {
        "operationId": "searchSymbols",
        "summary": "Search Symbols",
        "description": "Search for symbols on StockTwits.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The search query for symbol lookup",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Symbol"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/users.json": {
      "get": {
        "operationId": "searchUsers",
        "summary": "Search Users",
        "description": "Search for users on StockTwits.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The search query for user lookup",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trending/symbols.json": {
      "get": {
        "operationId": "getTrendingSymbols",
        "summary": "Trending Symbols",
        "description": "Returns the list of trending symbols on StockTwits, based on message volume.",
        "tags": [
          "Trending"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of trending symbols to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with trending symbols",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "symbols": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Symbol"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/trending/symbols/equities.json": {
      "get": {
        "operationId": "getTrendingEquities",
        "summary": "Trending Equities",
        "description": "Returns the list of trending equity symbols on StockTwits.",
        "tags": [
          "Trending"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of trending symbols to return (default 30, max 30)",
            "schema": {
              "type": "integer",
              "default": 30,
              "maximum": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with trending equity symbols",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "symbols": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Symbol"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/graph/user/{user_id}/following.json": {
      "get": {
        "operationId": "getUserFollowing",
        "summary": "User Following",
        "description": "Returns the list of users the specified user is following.",
        "tags": [
          "Graph (Social)"
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "User ID or username",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with list of followed users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/graph/user/{user_id}/followers.json": {
      "get": {
        "operationId": "getUserFollowers",
        "summary": "User Followers",
        "description": "Returns the list of users following the specified user.",
        "tags": [
          "Graph (Social)"
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "User ID or username",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with list of followers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/friendships/create/{user_id}.json": {
      "post": {
        "operationId": "followUser",
        "summary": "Follow User",
        "description": "Follow a user on StockTwits.",
        "tags": [
          "Friendships"
        ],
        "security": [
          {
            "oauth2": [
              "follow_users"
            ]
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "User ID or username to follow",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully followed user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "user": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/friendships/destroy/{user_id}.json": {
      "post": {
        "operationId": "unfollowUser",
        "summary": "Unfollow User",
        "description": "Unfollow a user on StockTwits.",
        "tags": [
          "Friendships"
        ],
        "security": [
          {
            "oauth2": [
              "follow_users"
            ]
          }
        ],
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "description": "User ID or username to unfollow",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully unfollowed user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "user": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists.json": {
      "get": {
        "operationId": "getWatchlists",
        "summary": "List Watchlists",
        "description": "Returns all watchlists for the authenticated user.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with watchlists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlists": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Watchlist"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/create.json": {
      "post": {
        "operationId": "createWatchlist",
        "summary": "Create Watchlist",
        "description": "Creates a new watchlist for the authenticated user.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The name of the watchlist"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Watchlist created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlist": {
                      "$ref": "#/components/schemas/Watchlist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/update/{watchlist_id}.json": {
      "post": {
        "operationId": "updateWatchlist",
        "summary": "Update Watchlist",
        "description": "Updates the name of an existing watchlist.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "parameters": [
          {
            "name": "watchlist_id",
            "in": "path",
            "required": true,
            "description": "The watchlist ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The new name of the watchlist"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Watchlist updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlist": {
                      "$ref": "#/components/schemas/Watchlist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/destroy/{watchlist_id}.json": {
      "post": {
        "operationId": "deleteWatchlist",
        "summary": "Delete Watchlist",
        "description": "Deletes an existing watchlist.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "parameters": [
          {
            "name": "watchlist_id",
            "in": "path",
            "required": true,
            "description": "The watchlist ID to delete",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Watchlist deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlist": {
                      "$ref": "#/components/schemas/Watchlist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/{watchlist_id}/symbols/create.json": {
      "post": {
        "operationId": "addSymbolToWatchlist",
        "summary": "Add Symbol to Watchlist",
        "description": "Adds symbols to an existing watchlist.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "parameters": [
          {
            "name": "watchlist_id",
            "in": "path",
            "required": true,
            "description": "The watchlist ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "symbols"
                ],
                "properties": {
                  "symbols": {
                    "type": "string",
                    "description": "Comma-separated list of ticker symbols to add (e.g. AAPL,TSLA,GOOG)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Symbols added successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlist": {
                      "$ref": "#/components/schemas/Watchlist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/{watchlist_id}/symbols/destroy.json": {
      "post": {
        "operationId": "removeSymbolFromWatchlist",
        "summary": "Remove Symbol from Watchlist",
        "description": "Removes symbols from an existing watchlist.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "parameters": [
          {
            "name": "watchlist_id",
            "in": "path",
            "required": true,
            "description": "The watchlist ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "symbols"
                ],
                "properties": {
                  "symbols": {
                    "type": "string",
                    "description": "Comma-separated list of ticker symbols to remove"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Symbols removed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlist": {
                      "$ref": "#/components/schemas/Watchlist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/watchlists/show/{watchlist_id}.json": {
      "get": {
        "operationId": "getWatchlist",
        "summary": "Show Watchlist",
        "description": "Returns the specified watchlist with its symbols.",
        "tags": [
          "Watchlists"
        ],
        "security": [
          {
            "oauth2": [
              "watchlists"
            ]
          }
        ],
        "parameters": [
          {
            "name": "watchlist_id",
            "in": "path",
            "required": true,
            "description": "The watchlist ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with watchlist details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "watchlist": {
                      "$ref": "#/components/schemas/Watchlist"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/account/verify.json": {
      "get": {
        "operationId": "verifyAccount",
        "summary": "Verify Account",
        "description": "Verifies the authenticated user's credentials and returns their profile information.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "oauth2": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful verification with user profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "user": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired access token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/account/update.json": {
      "post": {
        "operationId": "updateAccount",
        "summary": "Update Account",
        "description": "Updates the authenticated user's profile information.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "oauth2": [
              "publish_messages"
            ]
          }
        ],
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The user's display name"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The user's email address"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "user": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/deletions/messages.json": {
      "get": {
        "operationId": "getDeletedMessages",
        "summary": "Deleted Messages",
        "description": "Returns a list of message IDs that have been deleted since the specified ID.",
        "tags": [
          "Deletions"
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": true,
            "description": "Returns deleted message IDs greater than this ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with deleted message IDs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "user_id": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/deletions/users.json": {
      "get": {
        "operationId": "getDeletedUsers",
        "summary": "Deleted Users",
        "description": "Returns a list of user IDs that have been deleted since the specified ID.",
        "tags": [
          "Deletions"
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": true,
            "description": "Returns deleted user IDs greater than this ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with deleted user IDs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "response": {
                      "$ref": "#/components/schemas/ResponseStatus"
                    },
                    "users": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "StockTwits uses OAuth 2.0 for authentication. Some endpoints are available without authentication using just an access_token query parameter.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.stocktwits.com/api/2/oauth/authorize",
            "tokenUrl": "https://api.stocktwits.com/api/2/oauth/token",
            "scopes": {
              "read": "Read access to public data",
              "publish_messages": "Create and interact with messages",
              "publish_watch_lists": "Create and manage watchlists",
              "follow_users": "Follow and unfollow users",
              "follow_stocks": "Follow and unfollow stocks"
            }
          }
        }
      },
      "accessToken": {
        "type": "apiKey",
        "in": "query",
        "name": "access_token",
        "description": "Access token passed as a query parameter. Can be an application-level token for public endpoints or a user-level OAuth token for authenticated endpoints."
      }
    },
    "schemas": {
      "StreamResponse": {
        "type": "object",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseStatus"
          },
          "symbol": {
            "$ref": "#/components/schemas/Symbol"
          },
          "cursor": {
            "type": "object",
            "properties": {
              "more": {
                "type": "boolean",
                "description": "Whether there are more results available"
              },
              "since": {
                "type": "integer",
                "description": "The ID to use for the since parameter to get newer results"
              },
              "max": {
                "type": "integer",
                "description": "The ID to use for the max parameter to get older results"
              }
            }
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique message ID"
          },
          "body": {
            "type": "string",
            "description": "The message body text"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the message was created"
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "source": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "title": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "symbols": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Symbol"
            }
          },
          "entities": {
            "type": "object",
            "properties": {
              "sentiment": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "basic": {
                    "type": "string",
                    "enum": [
                      "Bullish",
                      "Bearish"
                    ],
                    "description": "The sentiment of the message"
                  }
                }
              },
              "chart": {
                "type": "object",
                "nullable": true,
                "properties": {
                  "thumb": {
                    "type": "string",
                    "format": "uri"
                  },
                  "large": {
                    "type": "string",
                    "format": "uri"
                  },
                  "original": {
                    "type": "string",
                    "format": "uri"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          },
          "conversation": {
            "type": "object",
            "nullable": true,
            "properties": {
              "parent_message_id": {
                "type": "integer"
              },
              "in_reply_to_message_id": {
                "type": "integer"
              },
              "parent": {
                "type": "boolean"
              },
              "replies": {
                "type": "integer"
              }
            }
          },
          "likes": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "user_ids": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              }
            }
          },
          "reshares": {
            "type": "object",
            "properties": {
              "reshared_count": {
                "type": "integer"
              },
              "user_ids": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique user ID"
          },
          "username": {
            "type": "string",
            "description": "The user's username"
          },
          "name": {
            "type": "string",
            "description": "The user's display name"
          },
          "avatar_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to the user's avatar image"
          },
          "avatar_url_ssl": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS URL to the user's avatar image"
          },
          "join_date": {
            "type": "string",
            "format": "date-time",
            "description": "Date the user joined StockTwits"
          },
          "official": {
            "type": "boolean",
            "description": "Whether the user is an official/verified account"
          },
          "followers": {
            "type": "integer",
            "description": "Number of followers"
          },
          "following": {
            "type": "integer",
            "description": "Number of users being followed"
          },
          "ideas": {
            "type": "integer",
            "description": "Number of messages posted"
          },
          "watchlist_stocks_count": {
            "type": "integer",
            "description": "Number of stocks in the user's watchlist"
          },
          "like_count": {
            "type": "integer",
            "description": "Number of likes received"
          },
          "classification": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "User classification tags (e.g. suggested, official)"
          }
        }
      },
      "Symbol": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique symbol ID"
          },
          "symbol": {
            "type": "string",
            "description": "The ticker symbol (e.g. AAPL)"
          },
          "title": {
            "type": "string",
            "description": "The full company/asset name"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Alternative names or aliases"
          },
          "is_following": {
            "type": "boolean",
            "description": "Whether the authenticated user is following this symbol"
          },
          "has_pricing": {
            "type": "boolean",
            "description": "Whether pricing data is available for this symbol"
          },
          "watchlist_count": {
            "type": "integer",
            "description": "Number of users who have this symbol in their watchlist"
          }
        }
      },
      "Watchlist": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique watchlist ID"
          },
          "name": {
            "type": "string",
            "description": "The watchlist name"
          },
          "static": {
            "type": "boolean",
            "description": "Whether the watchlist is a default/static list"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "symbols": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Symbol"
            }
          }
        }
      },
      "ResponseStatus": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "HTTP status code (200 for success)"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer"
              }
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "description": "Error message description"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {},
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "Streams",
      "description": "Stream endpoints return collections of messages (twits). Streams can be filtered by symbol, user, trending, etc."
    },
    {
      "name": "Messages",
      "description": "Message endpoints for creating, viewing, liking, and managing individual messages (twits)."
    },
    {
      "name": "Search",
      "description": "Search endpoints for finding symbols and users on StockTwits."
    },
    {
      "name": "Trending",
      "description": "Trending endpoints return currently popular symbols based on message volume."
    },
    {
      "name": "Graph (Social)",
      "description": "Social graph endpoints for viewing followers and following lists."
    },
    {
      "name": "Friendships",
      "description": "Friendship management endpoints for following and unfollowing users."
    },
    {
      "name": "Watchlists",
      "description": "Watchlist management endpoints for creating and managing symbol watchlists."
    },
    {
      "name": "Account",
      "description": "Account management endpoints for verifying and updating user profiles."
    },
    {
      "name": "Deletions",
      "description": "Deletion tracking endpoints for finding messages and users that have been removed."
    }
  ],
  "externalDocs": {
    "description": "StockTwits API Documentation",
    "url": "https://api.stocktwits.com/developers/docs/api"
  }
}