Sorsa API v3

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: [email protected]
    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:
    

# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sorsa/refs/heads/main/openapi/sorsa-openapi.yml