components:
  schemas:
    common.CommunityUser:
      properties:
        display_name:
          description: User's display name.
          example: Elon Musk
          type: string
        id:
          description: Unique Twitter/X user ID.
          example: '44196397'
          type: string
        profile_image_url:
          description: URL of the user's avatar image.
          example: https://pbs.twimg.com/profile_images/123/photo.jpg
          type: string
        protected:
          description: Whether the account's tweets are protected (private).
          example: false
          type: boolean
        username:
          description: Current Twitter/X handle (without @).
          example: elonmusk
          type: string
        verified:
          description: Whether the account has a verified badge.
          example: true
          type: boolean
      type: object
    common.CommunityUsersResponse:
      properties:
        next_cursor:
          description: Cursor for fetching the next page of results. Null or absent if no more pages.
          type: string
        users:
          description: Array of user profile objects.
          items:
            $ref: '#/components/schemas/common.CommunityUser'
          type: array
      type: object
    common.Follower:
      properties:
        bio_urls:
          description: URLs found in the user's bio.
          items:
            type: string
          type: array
        can_dm:
          description: Whether the account accepts direct messages.
          example: false
          type: boolean
        created_at:
          description: Account creation date in ISO 8601 format.
          example: '2009-06-02T20:12:29Z'
          type: string
        description:
          description: Profile bio text.
          example: Bio text
          type: string
        display_name:
          description: User's display name.
          example: Elon Musk
          type: string
        favourites_count:
          description: Total number of tweets this user has liked.
          example: 1200
          type: integer
        followerDate:
          description: Date when this user started following the target account, in ISO 8601 format.
          example: '2024-01-15T10:30:00Z'
          type: string
        followers_count:
          description: Number of accounts following this user.
          example: 100000
          type: integer
        followings_count:
          description: Number of accounts this user follows.
          example: 500
          type: integer
        id:
          description: Unique Twitter/X user ID.
          example: '44196397'
          type: string
        media_count:
          description: Total number of media items posted by this user.
          example: 300
          type: integer
        pinned_tweet_ids:
          description: IDs of the user's pinned tweets.
          items:
            type: string
          type: array
        possibly_sensitive:
          description: Whether the account is flagged as possibly containing sensitive content.
          example: false
          type: boolean
        profile_background_image_url:
          description: URL of the user's profile background image.
          example: https://pbs.twimg.com/profile_banners/44196397/123
          type: string
        profile_image_url:
          description: URL of the user's avatar image.
          example: https://pbs.twimg.com/profile_images/123/photo.jpg
          type: string
        protected:
          description: Whether the account's tweets are protected (private).
          example: false
          type: boolean
        tweets_count:
          description: Total number of tweets posted by this user.
          example: 5000
          type: integer
        username:
          description: Current Twitter/X handle (without @).
          example: elonmusk
          type: string
        verified:
          description: Whether the account has a verified badge.
          example: true
          type: boolean
      type: object
    common.FollowersResponse:
      properties:
        users:
          description: Array of follower profile objects with follow dates.
          items:
            $ref: '#/components/schemas/common.Follower'
          type: array
      type: object
    common.Place:
      properties:
        created_at:
          type: integer
        creator:
          $ref: '#/components/schemas/common.User'
        id:
          type: string
        is_subscribed:
          type: boolean
        media_key:
          type: string
        participants:
          $ref: '#/components/schemas/common.PlaceParticipants'
        scheduled_start:
          type: integer
        settings:
          $ref: '#/components/schemas/common.PlaceSettings'
        state:
          type: string
        stats:
          $ref: '#/components/schemas/common.PlaceStats'
        title:
          type: string
        updated_at:
          type: integer
      type: object
    common.PlaceParticipant:
      properties:
        avatar:
          type: string
        id:
          type: string
        is_muted_by_admin:
          type: boolean
        is_muted_by_guest:
          type: boolean
        is_verified:
          type: boolean
        name:
          type: string
        periscope_user_id:
          type: string
        start:
          type: integer
        username:
          type: string
      type: object
    common.PlaceParticipants:
      properties:
        admins:
          items:
            $ref: '#/components/schemas/common.PlaceParticipant'
          type: array
        listeners:
          items:
            $ref: '#/components/schemas/common.PlaceParticipant'
          type: array
        speakers:
          items:
            $ref: '#/components/schemas/common.PlaceParticipant'
          type: array
        total:
          type: integer
      type: object
    common.PlaceSettings:
      properties:
        conversation_controls:
          type: integer
        disallow_join:
          type: boolean
        is_employee_only:
          type: boolean
        is_locked:
          type: boolean
        is_muted:
          type: boolean
        is_space_available_for_clipping:
          type: boolean
        is_space_available_for_replay:
          type: boolean
        max_admin_capacity:
          type: integer
        max_guest_sessions:
          type: integer
        narrow_cast_space_type:
          type: integer
        no_incognito:
          type: boolean
      type: object
    common.PlaceStats:
      properties:
        total_live_listeners:
          type: integer
        total_participants:
          type: integer
        total_replay_watched:
          type: integer
      type: object
    common.TopFollower:
      properties:
        can_dm:
          example: false
          type: boolean
        created_at:
          description: Account creation date in ISO 8601 format.
          example: '2009-06-02T20:12:29Z'
          type: string
        description:
          description: Profile bio text.
          example: Bio text
          type: string
        display_name:
          description: User's display name.
          example: Elon Musk
          type: string
        followers_count:
          description: Number of accounts following this user.
          example: 100000
          type: integer
        followings_count:
          description: Number of accounts this user follows.
          example: 500
          type: integer
        id:
          description: Unique Twitter/X user ID.
          example: '44196397'
          type: string
        profile_background_image_url:
          description: URL of the user's profile background image.
          example: https://pbs.twimg.com/profile_banners/44196397/123
          type: string
        profile_image_url:
          description: URL of the user's avatar image.
          example: https://pbs.twimg.com/profile_images/123/photo.jpg
          type: string
        protected:
          description: Whether the account's tweets are protected (private).
          example: false
          type: boolean
        score:
          description: Whether the account accepts direct messages.
          example: 100
          type: number
        tweets_count:
          description: Total number of tweets posted by this user.
          example: 5000
          type: integer
        username:
          description: Current Twitter/X handle (without @).
          example: elonmusk
          type: string
        verified:
          description: Whether the account has a verified badge.
          example: true
          type: boolean
      type: object
    common.TopFollowersResponse:
      properties:
        users:
          description: Array of follower profile objects with follow dates.
          items:
            $ref: '#/components/schemas/common.TopFollower'
          type: array
      type: object
    common.Trend:
      properties:
        name:
          type: string
        query:
          type: string
        url:
          type: string
      type: object
    common.TrendsResponse:
      properties:
        trends:
          items:
            $ref: '#/components/schemas/common.Trend'
          type: array
      type: object
    common.Tweet:
      properties:
        bookmark_count:
          description: Number of times the tweet has been bookmarked.
          example: 15
          type: integer
        conversation_id_str:
          description: ID of the root tweet in the conversation thread.
          example: '1782368585664626774'
          type: string
        created_at:
          description: Tweet publication date in ISO 8601 format.
          example: '2024-01-15T10:30:00Z'
          type: string
        entities:
          description: Media, links, and other embedded entities attached to the tweet.
          items:
            $ref: '#/components/schemas/common.TweetEntity'
          type: array
        full_text:
          description: Full text content of the tweet.
          example: Hello world
          type: string
        id:
          description: Unique tweet ID.
          example: '1782368585664626774'
          type: string
        in_reply_to_tweet_id:
          description: ID of the tweet this tweet is replying to. Null if not a reply.
          example: '1782368585664626000'
          type: string
        in_reply_to_username:
          description: Username of the account this tweet is replying to.
          example: username
          type: string
        is_quote_status:
          description: Whether this tweet quotes another tweet.
          example: false
          type: boolean
        is_replies_limited:
          description: Whether replies to this tweet are restricted by the author.
          example: false
          type: boolean
        is_reply:
          description: Whether this tweet is a reply to another tweet.
          example: false
          type: boolean
        lang:
          description: Detected language code of the tweet (e.g. `en`, `es`).
          example: en
          type: string
        likes_count:
          description: Number of likes on the tweet.
          example: 200
          type: integer
        quote_count:
          description: Number of quote tweets.
          example: 5
          type: integer
        quoted_status:
          allOf:
          - $ref: '#/components/schemas/common.Tweet'
          description: The original tweet being quoted. Present only if `is_quote_status` is true.
        reply_count:
          description: Number of replies to the tweet.
          example: 10
          type: integer
        retweet_count:
          description: Number of retweets.
          example: 50
          type: integer
        retweeted_status:
          allOf:
          - $ref: '#/components/schemas/common.Tweet'
          description: The original tweet being retweeted. Present only for retweets.
        user:
          allOf:
          - $ref: '#/components/schemas/common.User'
          description: Author of the tweet.
        view_count:
          description: Number of views (impressions).
          example: 10000
          type: integer
      type: object
    common.TweetEntity:
      properties:
        link:
          description: Direct URL of the entity.
          example: https://t.co/example
          type: string
        preview:
          description: Preview or thumbnail URL for the entity.
          example: https://pbs.twimg.com/preview
          type: string
        type:
          description: Entity type (e.g. `photo`, `video`, `url`).
          example: photo
          type: string
      type: object
    common.TweetsBulkResponse:
      properties:
        tweets:
          description: Array of tweet objects.
          items:
            $ref: '#/components/schemas/common.Tweet'
          type: array
      type: object
    common.TweetsResponse:
      properties:
        next_cursor:
          description: Cursor for fetching the next page of results. Null or absent if no more pages.
          type: string
        tweets:
          description: Array of tweet objects.
          items:
            $ref: '#/components/schemas/common.Tweet'
          type: array
      type: object
    common.User:
      properties:
        bio_urls:
          description: URLs found in the user's bio.
          items:
            type: string
          type: array
        can_dm:
          description: Whether the account accepts direct messages.
          example: false
          type: boolean
        created_at:
          description: Account creation date in ISO 8601 format.
          example: '2009-06-02T20:12:29Z'
          type: string
        description:
          description: Profile bio text.
          example: Bio text
          type: string
        display_name:
          description: User's display name.
          example: Elon Musk
          type: string
        favourites_count:
          description: Total number of tweets this user has liked.
          example: 1200
          type: integer
        followers_count:
          description: Number of accounts following this user.
          example: 100000
          type: integer
        followings_count:
          description: Number of accounts this user follows.
          example: 500
          type: integer
        id:
          description: Unique Twitter/X user ID.
          example: '44196397'
          type: string
        location:
          description: Location string from the user's profile.
          example: Austin, TX
          type: string
        media_count:
          description: Total number of media items posted by this user.
          example: 300
          type: integer
        pinned_tweet_ids:
          description: IDs of the user's pinned tweets.
          items:
            type: string
          type: array
        possibly_sensitive:
          description: Whether the account is flagged as possibly containing sensitive content.
          example: false
          type: boolean
        profile_background_image_url:
          description: URL of the user's profile background image.
          example: https://pbs.twimg.com/profile_banners/44196397/123
          type: string
        profile_image_url:
          description: URL of the user's avatar image.
          example: https://pbs.twimg.com/profile_images/123/photo.jpg
          type: string
        protected:
          description: Whether the account's tweets are protected (private).
          example: false
          type: boolean
        tweets_count:
          description: Total number of tweets posted by this user.
          example: 5000
          type: integer
        username:
          description: Current Twitter/X handle (without @).
          example: elonmusk
          type: string
        verified:
          description: Whether the account has a verified badge.
          example: true
          type: boolean
      type: object
    common.UsersResponse:
      properties:
        next_cursor:
          description: Cursor for fetching the next page of results. Null or absent if no more pages.
          type: string
        users:
          description: Array of user profile objects.
          items:
            $ref: '#/components/schemas/common.User'
          type: array
      type: object
    community.CommunityMembersReq:
      properties:
        community_link:
          description: Community ID or full community URL.
          example: '1966045657589813686'
          type: string
        next_cursor:
          description: Pagination cursor from a previous response.
          example: '123'
          type: string
      required:
      - community_link
      type: object
    community.CommunityTweetsReq:
      properties:
        community_id:
          description: Numeric community ID.
          example: '1966045657589813686'
          type: string
        next_cursor:
          description: Pagination cursor from a previous response.
          example: '123'
          type: string
        order:
          description: 'Sort order: `popular` or `latest`. Defaults to `latest`.'
          example: popular
          type: string
      required:
      - community_id
      type: object
    community.SearchCommunityTweetsReq:
      properties:
        community_link:
          description: Full community URL or community ID.
          example: https://x.com/i/communities/1966045657589813686
          type: string
        next_cursor:
          description: Pagination cursor from a previous response.
          example: '123'
          type: string
        order:
          description: 'Sort order: `popular` or `latest`.'
          example: popular
          type: string
        query:
          description: Search query string.
          example: elonmusk
          type: string
      required:
      - community_link
      type: object
    handler.ErrorResponse:
      properties:
        message:
          type: string
      type: object
    search.SearchMentionsReq:
      properties:
        min_likes:
          example: 100
          type: integer
        min_replies:
          example: 100
          type: integer
        min_retweets:
          example: 100
          type: integer
        next_cursor:
          example: JKHSJFHADUYJKSDy2y3u123
          type: string
        order:
          example: popular
          type: string
        query:
          example: elonmusk
          type: string
        since_date:
          example: '2026-01-01'
          type: string
        until_date:
          example: '2026-01-01'
          type: string
      type: object
    search.SearchTweetsReq:
      properties:
        next_cursor:
          example: JKHSJFHADUYJKSDy2y3u123
          type: string
        order:
          example: popular
          type: string
        query:
          example: elonmusk
          type: string
      type: object
    search.SearchUsersReq:
      properties:
        next_cursor:
          example: JKHSJFHADUYJKSDy2y3u123
          type: string
        query:
          example: elonmusk
          type: string
      type: object
    sorsa.FollowersStatsResp:
      properties:
        followers_count:
          description: Total number of categorized followers.
          example: 16
          type: integer
        influencers_count:
          description: Number of followers classified as influencers.
          example: 12
          type: integer
        projects_count:
          description: Number of followers classified as projects.
          example: 3
          type: integer
        user_protected:
          description: '`true` if the target account is protected.'
          example: false
          type: boolean
        venture_capitals_count:
          description: Number of followers classified as VC employees.
          example: 1
          type: integer
      type: object
    sorsa.ScoreChangesResp:
      properties:
        month_delta:
          description: Score change over the last 30 days.
          example: 24
          type: number
        week_delta:
          description: Score change over the last 7 days.
          example: 12
          type: number
      type: object
    sorsa.ScoreResp:
      properties:
        score:
          description: Numeric influence score. Higher values indicate stronger recognition among influencers, projects, and
            VCs.
          example: 1.25
          type: number
      type: object
    technical.HandleRes:
      properties:
        handle:
          description: Current Twitter/X handle (without @).
          example: elonmusk
          type: string
      type: object
    technical.IDRes:
      properties:
        id:
          description: Numeric Twitter/X user ID.
          example: '1'
          type: string
      type: object
    technical.KeysResp:
      properties:
        key_requests:
          description: Number of requests allocated for the current period.
          example: 100
          type: integer
        remaining_requests:
          description: Number of requests remaining.
          example: 100
          type: integer
        total_requests:
          description: Total requests used across all periods.
          example: 1000
          type: integer
        valid_until:
          description: Expiration date of the current request balance in ISO 8601 format.
          example: '2021-01-01T00:00:00Z'
          type: string
      type: object
    technical.LinkToIDResp:
      properties:
        id:
          description: Numeric Twitter/X user ID.
          type: string
      type: object
    tweets.ArticleReq:
      properties:
        tweet_link:
          description: Full URL of the tweet or article (e.g. `https://x.com/user/status/123`) or just the tweet ID.
          type: string
      type: object
    tweets.ArticleRes:
      properties:
        author:
          allOf:
          - $ref: '#/components/schemas/common.User'
          description: Author profile data.
        bookmark_count:
          description: Number of bookmarks.
          type: integer
        cover_image_url:
          description: URL of the article's cover image.
          type: string
        full_text:
          description: Complete article text.
          type: string
        likes_count:
          description: Number of likes.
          type: integer
        preview_text:
          description: Short preview or excerpt of the article.
          type: string
        published_at:
          description: Publication date in ISO 8601 format.
          type: string
        quote_count:
          description: Number of quote tweets.
          type: integer
        reply_count:
          description: Number of replies.
          type: integer
        retweet_count:
          description: Number of retweets.
          type: integer
        views_count:
          description: Number of views (impressions).
          type: integer
      type: object
    tweets.CommentsReq:
      properties:
        next_cursor:
          description: Pagination cursor from a previous response.
          example: JKHSJFHADUYJKSDy2y3u123
          type: string
        order_by:
          description: 'Sort order: `Relevance`, `Recency` or `Likes`. Defaults to `Relevance`.'
          example: Relevance
          type: string
        tweet_link:
          description: Full URL of the tweet (e.g. `https://x.com/user/status/123`) or just the tweet ID.
          type: string
      type: object
    tweets.QuotesReq:
      properties:
        next_cursor:
          description: Pagination cursor from a previous response.
          example: JKHSJFHADUYJKSDy2y3u123
          type: string
        tweet_link:
          description: Full URL of the tweet (e.g. `https://x.com/user/status/123`) or just the tweet ID.
          type: string
      type: object
    tweets.RetweetsReq:
      properties:
        next_cursor:
          description: Pagination cursor from a previous response.
          example: JKHSJFHADUYJKSDy2y3u123
          type: string
        tweet_link:
          description: Full URL of the tweet (e.g. `https://x.com/user/status/123`) or just the tweet ID.
          type: string
      type: object
    tweets.TweetInfoBulkReq:
      properties:
        tweet_links:
          description: Array of tweet URLs or tweet IDs (up to 100).
          items:
            type: string
          type: array
      type: object
    tweets.TweetInfoReq:
      properties:
        tweet_link:
          description: Full URL of the tweet (e.g. `https://x.com/user/status/123`) or just the tweet ID.
          type: string
      type: object
    tweets.UserTweetsReq:
      properties:
        next_cursor:
          description: Pagination cursor from a previous response.
          example: ASDJKHFJWQE123Q
          type: string
        user_id:
          description: Numeric Twitter/X user ID. Provide either `link` or `user_id`.
          example: '123'
          type: string
        user_link:
          description: Full URL of the user's profile. Provide either `link` or `user_id`.
          example: https://twitter.com/username
          type: string
        username:
          description: Twitter/X handle of the user. Provide either `link` or `username`.
          example: username
          type: string
      type: object
    usersdata.AboutRes:
      properties:
        country:
          description: Country associated with the account.
          example: United States
          type: string
        last_username_change_at:
          description: Date of the most recent username change in ISO 8601 format.
          example: '2021-01-01T00:00:00Z'
          type: string
        username_change_count:
          description: Total number of username changes.
          example: 1
          type: integer
      type: object
    usersdata.InfoBatchRes:
      properties:
        users:
          description: Array of user profile objects.
          items:
            $ref: '#/components/schemas/common.User'
          type: array
      type: object
    verification.CheckCommentResp:
      properties:
        commented:
          description: '`true` if the user has commented on the tweet.'
          type: boolean
        tweet:
          allOf:
          - $ref: '#/components/schemas/common.Tweet'
          description: The user's reply tweet data. Present only if `commented` is `true`.
      type: object
    verification.CheckFollowReq:
      properties:
        user_id_1:
          example: '44196397'
          type: string
        user_id_2:
          example: '44196397'
          type: string
        user_link_1:
          example: https://twitter.com/elonmusk
          type: string
        user_link_2:
          example: https://twitter.com/elonmusk
          type: string
        username_1:
          example: elonmusk
          type: string
        username_2:
          example: elonmusk
          type: string
      type: object
    verification.CheckFollowResp:
      properties:
        follow:
          description: '`true` if the user follows the target account.'
          example: true
          type: boolean
        user_protected:
          description: '`true` if the checked user''s account is protected.'
          example: false
          type: boolean
      type: object
    verification.CheckQuotedReq:
      properties:
        tweet_link:
          example: https://twitter.com/TweetScout_io/status/1782368585664626774
          type: string
        user_id:
          example: '44196397'
          type: string
        user_link:
          example: https://twitter.com/elonmusk
          type: string
        username:
          example: elonmusk
          type: string
      type: object
    verification.CheckQuotedResp:
      properties:
        date:
          description: Date of the interaction (if found).
          example: '2024-04-27 06:43:09'
          type: string
        status:
          description: 'Interaction type: `quoted`, `retweet`, or `not_found`.'
          example: quoted
          type: string
        text:
          description: Text of the quote tweet (if status is `quoted`).
          example: Quote text
          type: string
        user_protected:
          description: '`true` if the checked user''s account is protected.'
          example: false
          type: boolean
      type: object
    verification.CheckRetweetReq:
      properties:
        next_cursor:
          type: string
        tweet_link:
          type: string
        user_id:
          type: string
        user_link:
          type: string
        username:
          type: string
      type: object
    verification.CheckRetweetResp:
      properties:
        next_cursor:
          description: Cursor for checking more retweets if needed.
          type: string
        retweet:
          description: '`true` if the user has retweeted the tweet.'
          type: boolean
        user_protected:
          description: '`true` if the checked user''s account is protected.'
          type: boolean
      type: object
    verification.CommunityReq:
      properties:
        community_id:
          example: '1966045657589813686'
          type: string
        user_id:
          type: string
        user_link:
          example: https://twitter.com/elonmusk
          type: string
        username:
          example: elonmusk
          type: string
      required:
      - community_id
      type: object
    verification.CommunityResp:
      properties:
        is_member:
          description: '`true` if the user is a member of the specified community.'
          type: boolean
      type: object
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: ApiKey
      description: Include your API key in the `ApiKey` header with every request.
info:
  title: Sorsa API
  version: '3.0'
  description: Real-time X (Twitter) data API providing access to tweets, profiles, search, mentions, lists, communities,
    engagement verification, and Sorsa Score crypto-influence analytics via 40 REST endpoints. Affordable alternative to the
    official X API.
  contact:
    name: Sorsa Support
    email: contacts@sorsa.io
    url: https://docs.sorsa.io/
  license:
    name: Proprietary
    url: https://sorsa.io/
  termsOfService: https://sorsa.io/terms
openapi: 3.0.3
paths:
  /about:
    get:
      description: 'Returns metadata from the "About" section of a Twitter/X account, including country, total number of username
        changes, and the date of the most recent change. Identify the user by providing exactly one of: `user_link`, `username`,
        or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usersdata.AboutRes'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Account About Info
      tags:
      - Users Data
  /article:
    post:
      description: Returns full data for a Twitter/X Article (long-form post) by its URL. The response includes the complete
        article text, a short preview excerpt, cover image URL, publication date, engagement metrics, and the author's profile.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.ArticleReq'
        description: Article request
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tweets.ArticleRes'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Article Data
      tags:
      - Tweets
  /check-comment:
    get:
      description: 'Checks whether a specific user has posted a reply under a given tweet. Returns `commented: true` along
        with the full reply tweet data if a comment is found. Requires `tweet_link` and one of `user_handle` or `user_id`.'
      parameters:
      - description: Full URL of the tweet to check.
        in: query
        name: tweet_link
        required: true
        schema:
          type: string
      - description: Twitter/X handle of the user being checked.
        in: query
        name: username
        schema:
          type: string
      - description: Twitter/X profile link of the user being checked.
        in: query
        name: user_link
        schema:
          type: string
      - description: Numeric Twitter/X user ID of the user being checked.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verification.CheckCommentResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Check Comment
      tags:
      - Verification
  /check-community-member:
    post:
      description: 'Checks whether a specific user is a member of a given Twitter/X Community. Returns `is_member: true` if
        the user belongs to that community. Requires `community_id` and one user identifier (`username`, `user_link`, or `user_id`).'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/verification.CommunityReq'
        description: community_id and user_handle or user_id required
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verification.CommunityResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Check Community Membership
      tags:
      - Verification
  /check-follow:
    post:
      description: 'Checks if one account follows another. User 1 is the account that should be followed, User 2 is the one
        you want to check. For example: "Does Elon Musk (user_2) follow SorsaApp (user_1)?" Pass only one identifier per side:
        link, username, or ID. Returns follow: true if the relationship exists, and user_protected: true if the checked user''s
        profile is private.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/verification.CheckFollowReq'
        description: project_handle or project_id and user_link, username or user_id
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verification.CheckFollowResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Check Follow
      tags:
      - Verification
  /check-quoted:
    post:
      description: 'Checks whether a user has quoted or retweeted a given tweet. Returns a `status` field with one of three
        values: `quoted`, `retweet`, or `not_found`. If a quote or retweet is found, the response also includes the interaction
        date and the quote text (when applicable). Identify the user with `username`, `user_link`, or `user_id`.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/verification.CheckQuotedReq'
        description: tweet link, user link, username or user_id
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verification.CheckQuotedResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Check Quote or Retweet
      tags:
      - Verification
  /check-retweet:
    post:
      description: Checks whether a user has retweeted a given tweet. The endpoint scans up to 100 retweets per request. If
        the tweet has more retweets than that, a `next_cursor` is returned to continue checking. Identify the user with `username`,
        `user_link`, or `user_id`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/verification.CheckRetweetReq'
        description: tweet link, user handle required, next_cursor not required
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verification.CheckRetweetResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Check Retweet
      tags:
      - Verification
  /comments:
    post:
      description: Returns a paginated list of replies (comments) posted under a specific tweet. Up to 20 replies per page.
        Each reply includes text, creation date, engagement metrics, conversation context, and the author's profile.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.CommentsReq'
        description: tweet link required, next_cursor optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Tweet Comments
      tags:
      - Tweets
  /community-members:
    post:
      description: Returns a paginated list of user profiles for members of the specified Twitter/X Community. Each profile
        includes display name, bio, follower stats, avatar, account creation date, and verification status.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/community.CommunityMembersReq'
        description: Community members request
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.CommunityUsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Community Members
      tags:
      - Community
  /community-search-tweets:
    post:
      description: Searches for tweets within a specific Twitter/X Community by keyword. Up to 20 matching tweets per page.
        Results can be sorted by `popular` or `latest`. Each tweet includes text, creation date, engagement metrics, and author
        profile.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/community.SearchCommunityTweetsReq'
        description: Search community tweets request
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Search Community Tweets
      tags:
      - Community
  /community-tweets:
    post:
      description: 'Returns a paginated feed of tweets published inside the specified Twitter/X Community. Up to 20 tweets
        per page. Each tweet includes text, creation date, engagement metrics, and author profile. Results can be sorted by
        `popular` or `latest` (default: `latest`).'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/community.CommunityTweetsReq'
        description: community_id required, next_cursor optional, order optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Community Tweets
      tags:
      - Community
  /followers:
    get:
      description: 'Returns a paginated list of users who follow the specified account. Up to 200 user profiles per page.
        Use the returned `next_cursor` to load subsequent pages. Identify the user by providing exactly one of: `user_link`,
        `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      - description: Pagination cursor from a previous response.
        in: query
        name: next_cursor
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Followers
      tags:
      - Users Data
  /followers-stats:
    get:
      description: 'Returns a breakdown of the account''s followers by Sorsa category: influencers, projects, and VC (venture
        capital) employees. Also indicates whether the account is protected. If the account is already indexed in the Sorsa
        database, the response is fast. For new accounts, the initial data collection may take longer, especially for large
        follower bases. Identify the user by providing exactly one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sorsa.FollowersStatsResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Follower Category Stats
      tags:
      - Sorsa Info Crypto Related
  /follows:
    get:
      description: 'Returns a paginated list of accounts that the specified user follows. Up to 200 user profiles per page.
        Use the returned `next_cursor` to load subsequent pages. Identify the user by providing exactly one of: `user_link`,
        `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      - description: Pagination cursor from a previous response.
        in: query
        name: next_cursor
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Following
      tags:
      - Users Data
  /id-to-username/{user_id}:
    get:
      description: Converts a numeric Twitter/X user ID into the account's current username. Useful for resolving stored IDs
        back into human-readable handles, especially when usernames may have changed.
      parameters:
      - description: user_id required
        in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/technical.HandleRes'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Convert User ID to Username
      tags:
      - Technical Endpoints
  /info:
    get:
      description: 'Returns the public profile of a Twitter/X account, including display name, bio, follower and following
        counts, tweet count, avatar, account creation date, and verification status. Identify the user by providing exactly
        one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.User'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: User Profile
      tags:
      - Users Data
  /info-batch:
    get:
      description: Returns public profile data for multiple Twitter/X accounts in a single request. Works the same way as
        the single-user endpoint, but accepts arrays of usernames or user IDs. Up to 100 accounts per request. Provide either
        `usernames` or `user_ids`.
      parameters:
      - description: Array of Twitter/X handles (without @).
        in: query
        name: usernames
        schema:
          items:
            type: string
          type: array
      - description: Array of numeric Twitter/X user IDs.
        in: query
        name: user_ids
        schema:
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usersdata.InfoBatchRes'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: User Profile (batch)
      tags:
      - Users Data
  /key-usage-info:
    get:
      description: 'Returns usage statistics for the current API key: total allocated requests, remaining balance, and the
        expiration date of the current request quota. No parameters required; the key is read from the `ApiKey` header.'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/technical.KeysResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: API Key Usage
      tags:
      - Technical Endpoints
  /link-to-id:
    get:
      description: Extracts the stable numeric user ID from a Twitter/X profile URL. Useful for normalizing profile links
        into consistent identifiers before making further API calls.
      parameters:
      - description: link required
        in: query
        name: link
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/technical.LinkToIDResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Convert Profile Link to User ID
      tags:
      - Technical Endpoints
  /list-followers:
    get:
      description: Returns a paginated list of users who follow (are subscribed to) the specified Twitter/X List. Each entry
        contains the follower's profile data.
      parameters:
      - description: Full URL or ID of the Twitter/X List.
        in: query
        name: list_link
        required: true
        schema:
          type: string
      - description: Pagination cursor from a previous response.
        in: query
        name: next_cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: List Followers
      tags:
      - Lists
  /list-members:
    get:
      description: Returns user profiles for all accounts included in the specified Twitter/X List. Each profile contains
        display name, bio, follower stats, avatar, and verification status.
      parameters:
      - description: Numeric ID of the Twitter/X List.
        in: query
        name: list_id
        required: true
        schema:
          type: string
      - description: Pagination cursor from a previous response.
        in: query
        name: next_cursor
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: List Members
      tags:
      - Lists
  /list-tweets:
    get:
      description: Returns a paginated feed of tweets published by members of the specified Twitter/X List. Up to 20 tweets
        per page. Each tweet includes text, creation date, engagement metrics, and basic author information.
      parameters:
      - description: Numeric ID of the Twitter/X List.
        in: query
        name: list_id
        required: true
        schema:
          type: string
      - description: Pagination cursor from a previous response.
        in: query
        name: next_cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: List Tweets
      tags:
      - Lists
  /mentions:
    post:
      description: 'Returns tweets that mention the specified user handle. Up to 20 results per page, sorted by mention time
        (newest first by default). Supports the richest set of filters among all search endpoints: minimum likes, replies,
        retweets, and a date range. Results can also be sorted by `popular` or `latest`.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/search.SearchMentionsReq'
        description: query required, next_cursor optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Search Mentions
      tags:
      - Search
  /new-followers-7d:
    get:
      description: 'Returns accounts that started following the specified user in the last 7 days. Both the target account
        and the returned followers must be present in the Sorsa database, which primarily tracks crypto-related accounts (influencers,
        projects, VCs). This means the results do not represent all new followers, only those already tracked by our system.
        Each entry includes profile data and the exact follow date. Identify the user by providing exactly one of: `user_link`,
        `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.FollowersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: New Followers (7 Days)
      tags:
      - Sorsa Info Crypto Related
  /new-following-7d:
    get:
      description: 'Returns accounts that the specified user started following in the last 7 days. Both the target account
        and the returned followings must be present in the Sorsa database, which primarily tracks crypto-related accounts
        (influencers, projects, VCs). This means the results do not represent all new follows, only those already tracked
        by our system. Each entry includes profile data and the exact follow date. Identify the user by providing exactly
        one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.FollowersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: New Following (7 Days)
      tags:
      - Sorsa Info Crypto Related
  /place:
    get:
      description: Returns detailed information about a place (Twitter Space) using its ID or link. Useful for viewing Space
        metadata, participants, settings, and statistics.
      parameters:
      - description: The unique identifier of the place (Space ID)
        in: query
        name: id
        schema:
          type: string
      - description: Full link to the place (Space link, e.g. https://twitter.com/i/spaces/1lPKqBajQrWGb)
        in: query
        name: link
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.Place'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Place Information
      tags:
      - Search
  /quotes:
    post:
      description: Returns a paginated list of tweets that quoted the specified tweet. Up to 20 results per page. Each quote
        tweet includes the added commentary text, creation date, engagement metrics, and the quoting user's profile.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.QuotesReq'
        description: tweet link required, next_cursor optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Quote Tweets
      tags:
      - Tweets
  /retweeters:
    post:
      description: 'Returns a paginated list of users who retweeted the specified tweet, sorted by retweet time (newest first).
        Each entry contains the retweeter''s profile data. Note: the response uses the users format (`common.UsersResponse`),
        not tweets.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.RetweetsReq'
        description: Retweets request
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Retweeters List
      tags:
      - Tweets
  /score:
    get:
      description: 'Returns the Sorsa Score for a Twitter/X account. The score is a numeric value that estimates the account''s
        recognition and popularity among crypto influencers, projects, and venture capital firms. A higher score indicates
        stronger visibility within the ecosystem. For accounts with a large follower base, the response may take longer to
        generate. Identify the user by providing exactly one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sorsa.ScoreResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Sorsa Score
      tags:
      - Sorsa Info Crypto Related
  /score-changes:
    get:
      description: 'Returns the change in Sorsa Score over the last 7 days and the last 30 days. Useful for tracking momentum
        and identifying accounts that are gaining or losing influence. The account must already be indexed in the Sorsa database.
        Identify the user by providing exactly one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sorsa.ScoreChangesResp'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Sorsa Score Changes
      tags:
      - Sorsa Info Crypto Related
  /search-tweets:
    post:
      description: 'Searches for tweets matching a text query using the same syntax as Twitter/X Advanced Search. Supports
        operators such as `from:`, `to:`, `since:`, `until:`, exact phrases in quotes, and hashtags. Returns up to 20 results
        per page, sortable by `popular` or `latest`. For a full list of supported query operators, see: https://github.com/igorbrigadir/twitter-advanced-search'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/search.SearchTweetsReq'
        description: query required, next_cursor optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Search Tweets
      tags:
      - Search
  /search-users:
    post:
      description: 'Searches for Twitter/X accounts by a keyword or phrase. Returns matching user profiles with basic info:
        handle, display name, bio, follower stats, and verification status. Supports pagination via `next_cursor`.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/search.SearchUsersReq'
        description: query required, next_cursor optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Search Users
      tags:
      - Search
  /top-followers:
    get:
      description: 'Returns the 20 followers of the specified account with the highest Sorsa Score. Each entry includes the
        follower''s profile data and follow date. Useful for identifying the most influential accounts in a user''s audience.
        Identify the user by providing exactly one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TopFollowersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Top 20 Followers by Score
      tags:
      - Sorsa Info Crypto Related
  /top-following:
    get:
      description: 'Returns the 20 accounts that the specified user follows with the highest Sorsa Score. Each entry includes
        profile data and follow date. Useful for understanding whose content and activity the user values most within the
        ecosystem. Identify the user by providing exactly one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.FollowersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Top 20 Following by Score
      tags:
      - Sorsa Info Crypto Related
  /trends:
    get:
      description: Returns a list of trending topics for the specified WOEID (location identifier). Each trend contains its
        name and search query for the region. Useful for monitoring popular topics by location.
      parameters:
      - description: 'WOEID (Where On Earth IDentifier) of the location to get trends for Woeid list: https://gist.github.com/tedyblood/5bb5a9f78314cc1f478b3dd7cde790b9'
        in: query
        name: woeid
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TrendsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Trends List
      tags:
      - Tweets
  /tweet-info:
    post:
      description: 'Returns full data for a single tweet by its URL: text, creation date, language, engagement metrics (likes,
        retweets, quotes, replies, views, bookmarks), and the author''s profile. If the tweet is a reply, quote, or repost,
        the nested original tweet and its author data are included as well.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.TweetInfoReq'
        description: tweet link required
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.Tweet'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Tweet Data
      tags:
      - Tweets
  /tweet-info-bulk:
    post:
      description: Returns full data for up to 100 tweets in a single request. Each tweet object includes text, creation date,
        engagement metrics, and author profile. Works the same way as the single-tweet endpoint, but accepts an array of URLs.
        The response is not paginated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.TweetInfoBulkReq'
        description: tweet links or ids required
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsBulkResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Tweet Data (batch)
      tags:
      - Tweets
  /user-tweets:
    post:
      description: Returns a paginated list of tweets posted by a specific user. Up to 20 tweets per page. Each tweet includes
        text, creation date, engagement metrics, view count, and nested data for replies, quotes, and retweets when available.
        Provide either `link` (profile URL) or `user_id`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tweets.UserTweetsReq'
        description: link or user id required, next_cursor optional
        required: true
        x-originalParamName: payload
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.TweetsResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: User Tweets
      tags:
      - Tweets
  /username-to-id/{user_handle}:
    get:
      description: Converts a Twitter/X username into the corresponding stable numeric user ID. Unlike usernames, user IDs
        never change, making them reliable for long-term storage and cross-referencing.
      parameters:
      - description: user_handle required
        in: path
        name: user_handle
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/technical.IDRes'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Convert Username to User ID
      tags:
      - Technical Endpoints
  /verified-followers:
    get:
      description: 'Returns a paginated list of verified users who follow the specified account. Works the same way as the
        regular followers endpoint, but filters to only include accounts with a verified badge. Identify the user by providing
        exactly one of: `user_link`, `username`, or `user_id`.'
      parameters:
      - description: Full URL of the user's Twitter/X profile.
        in: query
        name: user_link
        schema:
          type: string
      - description: Twitter/X handle (without @).
        in: query
        name: username
        schema:
          type: string
      - description: Numeric Twitter/X user ID.
        in: query
        name: user_id
        schema:
          type: string
      - description: Pagination cursor from a previous response.
        in: query
        name: next_cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/common.UsersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Internal Server Error
      security:
      - ApiKey: []
      summary: Verified Followers
      tags:
      - Users Data
servers:
- url: https://api.sorsa.io/v3
  description: Sorsa API v3 production
security:
- ApiKey: []
tags:
- name: Users Data
  description: User profile, followers, following, verified followers, About metadata
- name: Tweets
  description: Tweet data (single and batch), articles, user timelines, quotes, retweets, comments, trends
- name: Search
  description: Search tweets, users, mentions, and Twitter Spaces (Places)
- name: Lists
  description: Twitter/X List tweets, members, and followers
- name: Community
  description: Twitter/X Community tweets, members, and community search
- name: Verification
  description: Verify follow, comment, retweet, quote and community-membership relationships
- name: Sorsa Info (Crypto)
  description: Sorsa Score, follower category stats, top followers/following, new follower deltas
- name: Technical
  description: Username <-> User ID conversion, profile link parsing, API key usage