openapi: 3.0.3
info:
  title: Sorsa Community 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: Community
  description: Twitter/X Community tweets, members, and community search
paths:
  /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
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
    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
    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
    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
    handler.ErrorResponse:
      properties:
        message:
          type: string
      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
    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.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.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.