openapi: 3.0.3
info:
  title: Sorsa Community Lists 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
servers:
- url: https://api.sorsa.io/v3
  description: Sorsa API v3 production
security:
- ApiKey: []
tags:
- name: Lists
  description: Twitter/X List tweets, members, and followers
paths:
  /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
components:
  schemas:
    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.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
    handler.ErrorResponse:
      properties:
        message:
          type: string
      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
    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.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
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: ApiKey
      description: Include your API key in the `ApiKey` header with every request.