openapi.yaml

openapi: 3.0.3
info:
  title: BotWitter API
  description: Comprehensive Twitter automation and management platform API.
  version: 1.0.0
servers:
  - url: http://localhost:8080/api/v1
    description: Current server

paths:
  /accounts/{id}/follow:
    post:
      tags:
      - Account Actions
      summary: Follow a user
      description: Follow a Twitter user by user ID or username
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will perform the follow action
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  format: int64
                  description: Target user ID to follow
                username:
                  type: string
                  description: Target username to follow
              oneOf:
              - required:
                - user_id
              - required:
                - username
            examples:
              byUserId:
                value:
                  user_id: 123456789
              byUsername:
                value:
                  username: elonmusk
      responses:
        '200':
          description: User followed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  user_id:
                    type: integer
                    format: int64
                  username:
                    type: string
        '400':
          description: Invalid request or follow action failed
        '404':
          description: Account not found
        '500':
          description: Failed to follow user
  /accounts/{id}/unfollow:
    post:
      tags:
      - Account Actions
      summary: Unfollow a user
      description: Unfollow a Twitter user by user ID or username
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will perform the unfollow action
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  format: int64
                  description: Target user ID to unfollow
                username:
                  type: string
                  description: Target username to unfollow
              oneOf:
              - required:
                - user_id
              - required:
                - username
            examples:
              byUserId:
                value:
                  user_id: 123456789
              byUsername:
                value:
                  username: elonmusk
      responses:
        '200':
          description: User unfollowed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  user_id:
                    type: integer
                    format: int64
                  username:
                    type: string
        '400':
          description: Invalid request or unfollow action failed
        '404':
          description: Account not found
        '500':
          description: Failed to unfollow user
  /accounts/{id}/like:
    post:
      tags:
      - Account Actions
      summary: Like a tweet
      description: Like a tweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will like the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to like (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to like
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '200':
          description: Tweet liked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or like action failed
        '404':
          description: Account not found
        '500':
          description: Failed to like tweet
  /accounts/{id}/unlike:
    post:
      tags:
      - Account Actions
      summary: Unlike a tweet
      description: Remove like from a tweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will unlike the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to unlike (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to unlike
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '200':
          description: Tweet unliked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or unlike action failed
        '404':
          description: Account not found
        '500':
          description: Failed to unlike tweet
  /accounts/{id}/bookmark:
    post:
      tags:
      - Account Actions
      summary: Bookmark a tweet
      description: Bookmark a tweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will bookmark the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to bookmark (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to bookmark
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '200':
          description: Tweet bookmarked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or bookmark action failed
        '404':
          description: Account not found
        '500':
          description: Failed to bookmark tweet
  /accounts/{id}/tweet:
    post:
      tags:
      - Account Actions
      summary: Create a tweet
      description: Post a new tweet with text content, optional media, and optional community
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will post the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: Tweet text content
                  minLength: 1
                media:
                  type: array
                  description: Array of base64-encoded media (images/videos) to attach to the tweet (optional)
                  items:
                    type: object
                    required:
                    - data
                    properties:
                      data:
                        type: string
                        description: Base64-encoded media content
                      type:
                        type: string
                        description: 'MIME type of the media (optional).

                          If not provided, will be auto-detected from binary data using magic bytes.

                          Supported types: image/jpeg, image/png, image/gif, video/mp4

                          '
                        enum:
                        - image/jpeg
                        - image/png
                        - image/gif
                        - video/mp4
                community_id:
                  type: string
                  description: Community ID to post tweet in (optional)
                  example: '1234567890123456789'
            examples:
              simple:
                summary: Simple text tweet
                value:
                  text: Hello World! This is my first tweet.
              withImage:
                summary: Tweet with image
                value:
                  text: Check out this photo!
                  media:
                  - data: /9j/4AAQSkZJRgABAQEAYABgAAD...
                    type: image/jpeg
              withVideo:
                summary: Tweet with video
                value:
                  text: Watch this video!
                  media:
                  - data: AAAAIGZ0eXBpc29tAAACAGlzb21...
                    type: video/mp4
              withMultipleMedia:
                summary: Tweet with multiple images
                value:
                  text: Multiple photos!
                  media:
                  - data: /9j/4AAQSkZJRgABAQEAYABgAAD...
                    type: image/jpeg
                  - data: iVBORw0KGgoAAAANSUhEUgAAAAUA...
                    type: image/png
              withCommunity:
                summary: Tweet in community
                value:
                  text: Sharing in our community!
                  community_id: '1234567890123456789'
              full:
                summary: Tweet with media and community
                value:
                  text: Full featured tweet!
                  media:
                  - data: /9j/4AAQSkZJRgABAQEAYABgAAD...
                    type: image/jpeg
                  community_id: '1234567890123456789'
      responses:
        '201':
          description: Tweet created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  text:
                    type: string
                  media_count:
                    type: integer
                    description: Number of media items uploaded (if any)
                  community_id:
                    type: string
                    description: Community ID (if posted to community)
        '400':
          description: Invalid request or tweet creation failed
        '404':
          description: Account not found
        '500':
          description: Failed to create tweet
    delete:
      tags:
      - Account Actions
      summary: Delete a tweet
      description: Delete a tweet owned by this account by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that owns the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to delete (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to delete
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/username/status/1234567890123456789
      responses:
        '200':
          description: Tweet deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or delete action failed
        '404':
          description: Account not found
        '500':
          description: Failed to delete tweet
  /accounts/{id}/pin:
    post:
      tags:
      - Account Actions
      summary: Pin a tweet
      description: Pin a tweet to your profile by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that owns the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to pin (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to pin
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/username/status/1234567890123456789
      responses:
        '200':
          description: Tweet pinned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or pin action failed
        '404':
          description: Account not found
        '500':
          description: Failed to pin tweet
    delete:
      tags:
      - Account Actions
      summary: Unpin a tweet
      description: Unpin the pinned tweet from your profile
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that owns the tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to unpin (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to unpin
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/username/status/1234567890123456789
      responses:
        '200':
          description: Tweet unpinned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or unpin action failed
        '404':
          description: Account not found
        '500':
          description: Failed to unpin tweet
  /accounts/{id}/retweet:
    post:
      tags:
      - Account Actions
      summary: Retweet a tweet
      description: Retweet a tweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will retweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to retweet (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to retweet
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '201':
          description: Tweet retweeted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or retweet action failed
        '404':
          description: Account not found
        '500':
          description: Failed to retweet
  /accounts/{id}/unretweet:
    post:
      tags:
      - Account Actions
      summary: Remove a retweet
      description: Remove a retweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will remove the retweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to unretweet (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to unretweet
              oneOf:
              - required:
                - tweet_id
              - required:
                - tweet_url
            examples:
              byTweetId:
                value:
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '200':
          description: Retweet removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
        '400':
          description: Invalid request or unretweet action failed
        '404':
          description: Account not found
  /accounts/{id}/report:
    post:
      tags:
      - Account Actions
      summary: Report a user
      description: Report a Twitter user by user ID
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will perform the report action
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: integer
                  format: int64
                  description: Target user ID to report
            examples:
              byUserId:
                value:
                  user_id: 123456789
      responses:
        '200':
          description: User reported successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  user_id:
                    type: integer
                    format: int64
        '400':
          description: Invalid request or report action failed
        '404':
          description: Account not found
        '500':
          description: Failed to report user
  /accounts/{id}/reply:
    post:
      tags:
      - Account Actions
      summary: Reply to a tweet
      description: Post a reply to a tweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will post the reply
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: Reply text content
                  minLength: 1
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to reply to (as integer or string)
                tweet_url:
                  type: string
                  description: Tweet URL to reply to
              oneOf:
              - required:
                - text
                - tweet_id
              - required:
                - text
                - tweet_url
            examples:
              byTweetId:
                value:
                  text: Great tweet! Thanks for sharing.
                  tweet_id: 1234567890123456789
              byTweetUrl:
                value:
                  text: Interesting perspective!
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '201':
          description: Reply posted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
                  text:
                    type: string
        '400':
          description: Invalid request or reply action failed
        '404':
          description: Account not found
        '500':
          description: Failed to post reply
  /accounts/{id}/quote:
    post:
      tags:
      - Account Actions
      summary: Quote tweet
      description: Post a quote tweet by tweet ID or tweet URL
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID that will post the quote tweet
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: Quote tweet text content
                  minLength: 1
                tweet_id:
                  oneOf:
                  - type: integer
                    format: int64
                  - type: string
                  description: Tweet ID to quote (as integer or string)
                tweet_username:
                  type: string
                  description: Username of the tweet author (Required if using tweet_id)
                tweet_url:
                  type: string
                  description: Tweet URL to quote
              oneOf:
              - required:
                - text
                - tweet_id
                - tweet_username
              - required:
                - text
                - tweet_url
            examples:
              byTweetId:
                value:
                  text: Adding my thoughts on this...
                  tweet_id: 1234567890123456789
                  tweet_username: elonmusk
              byTweetUrl:
                value:
                  text: This is important!
                  tweet_url: https://x.com/elonmusk/status/1234567890123456789
      responses:
        '201':
          description: Quote tweet posted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  tweet_id:
                    type: string
                  text:
                    type: string
        '400':
          description: Invalid request or quote tweet action failed
        '404':
          description: Account not found
        '500':
          description: Failed to post quote tweet
  /accounts/{id}/change-password:
    post:
      tags:
      - Account Actions
      summary: Change account password
      description: 'Changes the password for a Twitter account.


        **Password Source:**

        - If `current_password` is provided in request, it will be used

        - If not provided, the password stored in the account database will be used

        - If neither is available, returns a 400 error

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - new_password
              properties:
                new_password:
                  type: string
                  description: New password to set for the account
                  minLength: 1
                current_password:
                  type: string
                  description: Current password (optional if stored in database)
            examples:
              withCurrentPassword:
                summary: Change password with current password provided
                value:
                  current_password: oldPassword123
                  new_password: newSecurePassword456
              withoutCurrentPassword:
                summary: Change password using stored password
                value:
                  new_password: newSecurePassword456
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Password changed successfully
                  username:
                    type: string
                    example: example_user
        '400':
          description: Bad request - Invalid parameters or password requirements not met
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                examples:
                  missingNewPassword:
                    summary: Missing new_password field
                    value:
                      error: '''new_password'' field is required'
                  emptyPassword:
                    summary: Empty new_password
                    value:
                      error: New password cannot be empty
                  noPasswordAvailable:
                    summary: No current password available
                    value:
                      error: Current password is required. Either provide 'current_password' in request or ensure account
                        has password stored
                  passwordChangeFailed:
                    summary: Twitter API rejected password change
                    value:
                      error: Password change failed
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Account not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Failed to change password: <error details>'
  /accounts/{id}/protected:
    put:
      tags:
      - Account Actions
      summary: Set account protection status
      description: 'Set whether the Twitter account is protected (tweets only visible to followers) or public.

        Throws an error if the account is already in the requested state.

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - protected
              properties:
                protected:
                  type: boolean
                  description: Set to true to protect the account, false to make it public
            examples:
              protect:
                summary: Protect the account
                value:
                  protected: true
              unprotect:
                summary: Make account public
                value:
                  protected: false
      responses:
        '200':
          description: Account protection status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Account is now protected
                  username:
                    type: string
                    example: example_user
                  protected:
                    type: boolean
                    example: true
        '400':
          description: Bad request - Invalid parameters
        '404':
          description: Account not found
        '409':
          description: Account already in the requested state
        '500':
          description: Internal server error
  /accounts/{id}/username:
    put:
      tags:
      - Account Actions
      summary: Change account username
      description: 'Changes the username (screen_name) of the Twitter account.

        Updates local database and user agent specific storage upon success.

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              properties:
                username:
                  type: string
                  description: New username to set for the account
                  minLength: 1
            examples:
              changeUsername:
                summary: Change username to 'new_handle'
                value:
                  username: new_handle
      responses:
        '200':
          description: Username changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Username changed successfully
                  username:
                    type: string
                    example: new_handle
        '400':
          description: Bad request - Invalid parameters or empty username
        '404':
          description: Account not found
        '500':
          description: Internal server error or change failed upstream
  /accounts/{id}/languages:
    get:
      tags:
      - Account Actions
      summary: Get account languages
      description: Retrieve the account's display language and preferred content languages.
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      responses:
        '200':
          description: Languages retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  display_language:
                    type: object
                    properties:
                      language_name:
                        type: string
                  preferred_content_languages:
                    type: array
                    items:
                      type: object
                      properties:
                        language_name:
                          type: string
        '404':
          description: Account not found
        '500':
          description: Internal server error
    post:
      tags:
      - Account Actions
      summary: Set account languages
      description: Update the account's display language and preferred content languages.
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      requestBody:
        description: Language selection
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - selected
              properties:
                selected:
                  type: array
                  description: List of language codes
                  items:
                    type: string
                    example: en
                  example:
                  - en
                  - tr
                primary:
                  type: string
                  description: Primary language code
                  example: en
      responses:
        '200':
          description: Languages updated successfully
        '400':
          description: Invalid request
        '404':
          description: Account not found
        '500':
          description: Internal server error
  /accounts/{id}/proxy-request:
    post:
      tags:
      - Account Actions
      summary: Proxy HTTP request through account
      description: 'Forward an HTTP request to Twitter/X domains using the account''s authenticated HTTP client.

        Only x.com and twitter.com domains (including subdomains) are allowed.


        **Data Format Options:**

        - `formData`: Key-value pairs → URL-encoded (application/x-www-form-urlencoded)

        - `jsonData`: Object → JSON body (application/json)

        - `rawData`: Raw string with optional `contentType`

        - `data`: Legacy field (object→JSON, string→raw)

        - `queryParams`: Appended to URL as query string


        Supports GET, POST, PUT, DELETE, PATCH methods with custom headers and multipart file uploads.

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID or username
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: Target URL (must be x.com or twitter.com domain)
                  example: https://api.x.com/1.1/users/show.json?screen_name=twitter
                method:
                  type: string
                  enum:
                  - GET
                  - POST
                  - PUT
                  - DELETE
                  - PATCH
                  default: GET
                  description: HTTP method
                headers:
                  type: object
                  additionalProperties:
                    type: string
                  description: Custom headers to include
                  example:
                    X-Custom-Header: value
                data:
                  oneOf:
                  - type: object
                  - type: string
                  description: 'Legacy field for request body (use formData, jsonData, or rawData instead).

                    - object/array: Serialized as JSON

                    - string: Sent as-is (default Content-Type: application/x-www-form-urlencoded)

                    '
                formData:
                  type: object
                  additionalProperties:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                  description: "Form data as key-value pairs. Automatically URL-encoded and sent with \nContent-Type: application/x-www-form-urlencoded\n"
                  example:
                    username: test
                    password: secret123
                jsonData:
                  type: object
                  description: 'JSON data to send in request body. Sent with Content-Type: application/json

                    '
                  example:
                    key: value
                    nested:
                      foo: bar
                rawData:
                  type: string
                  description: 'Raw string data to send in request body. Use with contentType to specify MIME type.

                    Default Content-Type: text/plain

                    '
                  example: key1=value1&key2=value2
                contentType:
                  type: string
                  description: "Content-Type header for rawData or string data. \nOnly used when rawData is provided or data\
                    \ is a string.\n"
                  example: application/x-www-form-urlencoded
                queryParams:
                  type: object
                  additionalProperties:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                  description: 'Query parameters to append to URL. Automatically URL-encoded.

                    '
                  example:
                    page: '1'
                    limit: '10'
                multipart:
                  type: boolean
                  default: false
                  description: Enable multipart/form-data mode
                fields:
                  type: object
                  additionalProperties:
                    type: string
                  description: Form fields for multipart requests
                files:
                  type: array
                  description: Files to upload in multipart mode
                  items:
                    type: object
                    required:
                    - data
                    properties:
                      field:
                        type: string
                        default: file
                        description: Form field name
                      filename:
                        type: string
                        default: file
                        description: File name
                      content_type:
                        type: string
                        default: application/octet-stream
                        description: MIME type
                      data:
                        type: string
                        format: byte
                        description: Base64-encoded file content
      responses:
        '200':
          description: Request completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: integer
                        description: HTTP status code from target
                      body:
                        type: string
                        description: Response body
                      headers:
                        type: object
                        additionalProperties:
                          type: string
                        description: Response headers
                      final_url:
                        type: string
                        description: Final URL after redirects
                      error:
                        type: string
                        description: Error message if request failed
        '400':
          description: Invalid parameter or request body
        '403':
          description: Domain not allowed (only x.com/twitter.com permitted)
        '404':
          description: Account not found
        '500':
          description: Internal server error
  /accounts:
    get:
      tags:
      - Account Management
      summary: Get all accounts
      description: Retrieve list of Twitter accounts
      parameters:
      - name: status
        in: query
        description: Filter accounts by working status
        schema:
          type: string
          enum:
          - active
          - inactive
      - name: tags
        in: query
        description: Filter accounts by tags (comma-separated)
        schema:
          type: string
      - name: filter
        in: query
        description: Search filter for username or email
        schema:
          type: string
      - name: min_followers
        in: query
        description: Filter by minimum number of followers
        schema:
          type: integer
      - name: max_followers
        in: query
        description: Filter by maximum number of followers
        schema:
          type: integer
      - name: min_following
        in: query
        description: Filter by minimum number of following
        schema:
          type: integer
      - name: max_following
        in: query
        description: Filter by maximum number of following
        schema:
          type: integer
      - name: min_tweets
        in: query
        description: Filter by minimum number of tweets
        schema:
          type: integer
      - name: max_tweets
        in: query
        description: Filter by maximum number of tweets
        schema:
          type: integer
      - name: min_account_age
        in: query
        description: Filter by minimum account age in days
        schema:
          type: integer
      - name: is_verified
        in: query
        description: Filter by verified status
        schema:
          type: boolean
      - name: has_profile_pic
        in: query
        description: Filter by profile picture existence
        schema:
          type: boolean
      - name: has_bio
        in: query
        description: Filter by bio existence
        schema:
          type: boolean
      - name: page
        in: query
        description: Page number for pagination (used with limit)
        schema:
          type: integer
          minimum: 1
      - name: limit
        in: query
        description: Number of accounts per page (used with page)
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: start
        in: query
        description: Start index for range pagination (alternative to page/limit)
        schema:
          type: integer
          minimum: 0
      - name: end
        in: query
        description: End index for range pagination (alternative to page/limit)
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      accounts:
                        type: array
                        items:
                          $ref: '#/components/schemas/Account'
                      tags:
                        type: array
                        description: List of all available tags with their count of working accounts
                        items:
                          type: object
                          properties:
                            tag:
                              type: string
                              description: Tag name
                            count:
                              type: integer
                              description: Number of working accounts with this tag
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          total_working:
                            type: integer
                          start:
                            type: integer
                          end:
                            type: integer
                          returned:
                            type: integer
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
    post:
      tags:
      - Account Management
      summary: Add new account
      description: Add single Twitter account to the system
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountRequest'
      responses:
        '201':
          description: Account added successfully
        '400':
          description: Invalid account data
  /accounts/bulk:
    post:
      tags:
      - Account Management
      summary: Bulk create accounts
      description: Create multiple Twitter accounts at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - accounts
              properties:
                accounts:
                  type: array
                  items:
                    $ref: '#/components/schemas/AccountRequest'
                  minItems: 1
      responses:
        '201':
          description: All accounts created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAccountResponse'
        '207':
          description: Multi-Status - Some accounts created, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAccountResponse'
        '400':
          description: Bad request - All accounts failed to create
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAccountResponse'
  /accounts/username/{username}:
    get:
      tags:
      - Account Management
      summary: Get account by username
      description: Retrieve account details by username
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter username
        schema:
          type: string
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
  /accounts/{id}:
    get:
      tags:
      - Account Management
      summary: Get account details
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Account'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
    delete:
      tags:
      - Account Management
      summary: Delete account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Account deleted successfully
  /accounts/{id}/refreshUserInfo:
    get:
      tags:
      - Account Management
      summary: Refresh user info
      description: Update account user information from Twitter
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: User info refreshed successfully
        '404':
          description: Account not found
  /accounts/{id}/profile:
    put:
      tags:
      - Account Management
      summary: Update account profile
      description: Update Twitter account profile settings including bio, location, website, profile image (avatar), and banner
        image
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name for the account
                bio:
                  type: string
                  description: Account bio/description
                location:
                  type: string
                  description: Location displayed on profile
                website:
                  type: string
                  description: Website URL displayed on profile
                avatar:
                  type: string
                  format: byte
                  description: Profile image in base64 encoded format (optional)
                banner:
                  type: string
                  format: byte
                  description: Banner/cover image in base64 encoded format (optional)
            example:
              name: John Doe
              bio: Software Developer | Open Source Enthusiast
              location: San Francisco, CA
              website: https://example.com
              avatar: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
              banner: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Invalid profile data or account ID
        '404':
          description: Account not found
  /accounts/{id}/proxy:
    put:
      tags:
      - Account Management
      summary: Update account proxy
      description: 'Update, assign, or remove proxy for an account.

        - Send `proxy` with string to add new proxy

        - Send `proxy` with empty string or null to remove proxy

        - Send `proxy_id` to assign existing proxy

        - Send `auto_assign: true` to auto-assign available proxy

        '
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                proxy:
                  type: string
                  nullable: true
                  description: 'Proxy string in format "ip:port:username:password" or "ip:port".

                    Set to empty string or null to remove proxy.

                    '
                proxy_id:
                  type: integer
                  description: ID of existing proxy to assign to account
                auto_assign:
                  type: boolean
                  description: Auto-assign an available proxy from the pool
            examples:
              add_new_proxy:
                summary: Add new proxy
                value:
                  proxy: 192.168.1.1:8080:user:pass
              assign_existing_proxy:
                summary: Assign existing proxy by ID
                value:
                  proxy_id: 123
              remove_proxy:
                summary: Remove proxy from account
                value:
                  proxy: ''
              auto_assign_proxy:
                summary: Auto-assign available proxy
                value:
                  auto_assign: true
      responses:
        '200':
          description: Proxy updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  account_id:
                    type: integer
                  proxy_id:
                    type: integer
                    description: New proxy ID (or -1 if removed)
                  proxy:
                    type: string
                    description: Proxy string (not present if removed)
                  previous_proxy_id:
                    type: integer
                    description: Previous proxy ID (only when removing)
              examples:
                proxy_added:
                  summary: Proxy added successfully
                  value:
                    success: true
                    message: Proxy updated successfully
                    account_id: 1
                    proxy_id: 5
                    proxy: 192.168.1.1:8080:user:pass
                proxy_removed:
                  summary: Proxy removed successfully
                  value:
                    success: true
                    message: Proxy removed successfully
                    account_id: 1
                    previous_proxy_id: 5
        '400':
          description: Invalid request or proxy not found
        '404':
          description: Account not found
  /accounts/validate:
    post:
      tags:
      - Account Management
      summary: Validate accounts
      description: Check account status and working state
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                account_ids:
                  type: array
                  items:
                    type: integer
                force:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Validation completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  validated:
                    type: integer
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        account_id:
                          type: integer
                        status:
                          type: string
                        message:
                          type: string
  /accounts/{id}/retry:
    post:
      tags:
      - Account Management
      summary: Reset account state for retry
      description: 'Reset account status to Pending so it will be retried on next validation.


        **Use Cases:**

        - Account failed authentication but credentials were updated

        - Proxy error occurred but new proxy was assigned

        - Temporary issue resolved and want to retry

        - Account was locked but now unlocked


        **Status Reset:**

        - Sets account status to `Pending`

        - Account will be re-validated on next check cycle

        - Previous status is returned in response for reference

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID to retry
        schema:
          type: integer
        example: 1
      responses:
        '200':
          description: Account state reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    type: integer
                    description: Account ID that was reset
                    example: 1
                  previous_status:
                    type: string
                    description: Previous account status before reset
                    example: AuthFailed
                  new_status:
                    type: string
                    description: New account status (always Pending)
                    example: Pending
                  message:
                    type: string
                    description: Success message
                    example: Account state reset successfully. Account will be retried on next validation.
        '400':
          description: Invalid account ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid account ID
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Account not found
        '500':
          description: Failed to reset account state
  /accounts/{id}/stats:
    get:
      tags:
      - Account Management
      summary: Get account statistics history
      description: Retrieve historical statistics for a specific account to track growth over time
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of stats records to return (default 50)
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: Stats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  account_id:
                    type: integer
                    example: 1
                  count:
                    type: integer
                    description: Number of stats records returned
                    example: 50
                  stats:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountStats'
        '400':
          description: Invalid account ID
        '500':
          description: Failed to retrieve stats
  /accounts/{id}/stats/latest:
    get:
      tags:
      - Account Management
      summary: Get account latest statistics
      description: Retrieve the most recent statistics snapshot for a specific account
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID
        schema:
          type: integer
      responses:
        '200':
          description: Latest stats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  account_id:
                    type: integer
                    example: 1
                  stats:
                    $ref: '#/components/schemas/AccountStats'
        '400':
          description: Invalid account ID
        '404':
          description: No stats found for this account
        '500':
          description: Failed to retrieve latest stats
  /accounts/{id}/stats/growth:
    get:
      tags:
      - Account Management
      summary: Get account growth data
      description: Calculate growth metrics by comparing the two most recent statistics snapshots (follower change, following
        change, etc.)
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID
        schema:
          type: integer
      responses:
        '200':
          description: Growth data calculated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  account_id:
                    type: integer
                    example: 1
                  growth:
                    $ref: '#/components/schemas/AccountGrowth'
        '400':
          description: Invalid account ID
        '404':
          description: Not enough stats data to calculate growth (need at least 2 records)
        '500':
          description: Failed to calculate growth
  /accounts/{id}/task-history:
    get:
      tags:
      - Account Management
      summary: Get account task history
      description: 'Retrieve the task execution history for a specific account.


        Shows all tasks (FOLLOW, LIKE, RETWEET, TWEET, QUOTE, REPLY) executed by this account

        within the last week. Useful for:

        - Tracking account activity

        - Preventing duplicate actions

        - Monitoring task execution patterns

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID
        schema:
          type: integer
      responses:
        '200':
          description: Task history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  account_id:
                    type: integer
                    example: 1
                  username:
                    type: string
                    example: AdrianoPessoaV2
                  task_count:
                    type: integer
                    description: Number of tasks in history
                    example: 4
                  data:
                    type: object
                    description: Task entries keyed by index
                    additionalProperties:
                      type: object
                      properties:
                        taskType:
                          type: string
                          enum:
                          - FOLLOW
                          - LIKE
                          - RETWEET
                          - TWEET
                          - QUOTE
                          - REPLY
                          description: Type of task executed
                        targetInfo:
                          type: string
                          description: Target identifier (username, tweet_id, or text prefix)
                        taskDetails:
                          type: string
                          description: Additional details (e.g., tweet text)
                        timestamp:
                          type: integer
                          format: int64
                          description: Unix timestamp of execution
                        date:
                          type: integer
                          format: int64
                          description: Date timestamp
                    example:
                      '1':
                        taskType: FOLLOW
                        targetInfo: elonmusk
                        taskDetails: ''
                        timestamp: 1763254512
                        date: 1763254512
                      '2':
                        taskType: LIKE
                        targetInfo: '1989854827292094499'
                        taskDetails: ''
                        timestamp: 1763254539
                        date: 1763254539
                      '3':
                        taskType: TWEET
                        targetInfo: Hello world! This is my first automated
                        taskDetails: Hello world! This is my first automated tweet.
                        timestamp: 1763254736
                        date: 1763254736
                  lastIndex:
                    type: integer
                    description: Last used index for task entries
                    example: 3
        '400':
          description: Invalid account ID format
        '404':
          description: Account not found
  /accounts/{id}/unlock:
    post:
      tags:
      - Account Management
      summary: Start account unlock process
      description: 'Start the unlock process for a locked/suspended account in the background.

        If the process is already running, returns 409 Conflict.

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID to unlock
        schema:
          type: integer
      responses:
        '202':
          description: Unlock process started
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    type: integer
                  status:
                    type: string
                    example: RUNNING
                  message:
                    type: string
                    example: Unlock process started in background
        '400':
          description: Invalid account ID
        '404':
          description: Account not found
        '409':
          description: Unlock process already running
    get:
      tags:
      - Account Management
      summary: Get unlock process status
      description: Check the status of a running or completed unlock process
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID
        schema:
          type: integer
      responses:
        '200':
          description: Status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_id:
                    type: integer
                  status:
                    type: string
                    enum:
                    - NONE
                    - RUNNING
                    - SUCCESS
                    - FAILED
                  message:
                    type: string
                  start_time:
                    type: integer
                    format: int64
                  end_time:
                    type: integer
                    format: int64
                  duration_seconds:
                    type: integer
                    description: Duration of the process (if finished)
        '400':
          description: Invalid account ID
        '500':
          description: Failed to retrieve status
  /accounts/{id}/following:
    get:
      tags:
      - Account Management
      summary: Get account following list
      description: Retrieve the list of users that this account follows on Twitter
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID (local database ID)
        schema:
          type: integer
      - name: limit
        in: query
        description: Number of users to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: Pagination cursor from previous response (optional, for fetching next page)
        schema:
          type: string
        example: DAABCgABGaEbiMu__-gKAAIZoRtIyz__5ggAAwAAAAIAAA
      responses:
        '200':
          description: Following list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardSuccessResponse'
              example:
                success: true
                data:
                  users:
                  - id: 12345
                    username: example_user
                    screen_name: example_user
                    name: Example User
                    bio: Just a sample user
                    followers_count: 1000
                    following_count: 500
                    tweet_count: 250
                    profile_image_url: https://pbs.twimg.com/profile_images/example.jpg
                    is_blue_verified: false
                    following: true
                    followed_by: false
                  count: 1
                  nextCursor: DAABCgABGaEbiMu__-gKAAIZoRtIyz__5ggAAwAAAAIAAA
                  hasMore: true
                meta:
                  timestamp: '2025-12-21T04:21:00.123Z'
                  path: /api/v1/accounts/1/following
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '500':
          description: External service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
  /accounts/{id}/followers:
    get:
      tags:
      - Account Management
      summary: Get account followers list
      description: Retrieve the list of users that follow this account on Twitter
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID (local database ID)
        schema:
          type: integer
      - name: limit
        in: query
        description: Number of users to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: cursor
        in: query
        description: Pagination cursor from previous response (optional, for fetching next page)
        schema:
          type: string
        example: DAABCgABGaEbiMu__-gKAAIZoRtIyz__5ggAAwAAAAIAAA
      responses:
        '200':
          description: Followers list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardSuccessResponse'
              example:
                success: true
                data:
                  users:
                  - id: 12345
                    username: example_follower
                    screen_name: example_follower
                    name: Example Follower
                    bio: Just a sample follower
                    followers_count: 500
                    following_count: 300
                    tweet_count: 150
                    profile_image_url: https://pbs.twimg.com/profile_images/example.jpg
                    is_blue_verified: true
                    following: false
                    followed_by: true
                  count: 1
                  nextCursor: DAABCgABGaEbiMu__-gKAAIZoRtIyz__5ggAAwAAAAIAAA
                  hasMore: true
                meta:
                  timestamp: '2025-12-21T04:21:00.123Z'
                  path: /api/v1/accounts/1/followers
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '500':
          description: External service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
  /accounts/{id}/home-timeline:
    get:
      tags:
      - Account Management
      summary: Get account home timeline
      description: Retrieve the home timeline tweets for this account
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID (local database ID)
        schema:
          type: integer
      - name: count
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Home timeline retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardSuccessResponse'
              example:
                success: true
                data:
                  tweets:
                  - id: '1876543210987654321'
                    text: Hello Twitter! This is a sample tweet from the timeline.
                    created_at: Thu Jan 02 12:00:00 +0000 2026
                    retweet_count: 42
                    like_count: 128
                    reply_count: 15
                    quote_count: 5
                    view_count: 5432
                    is_retweet: false
                    is_quote: false
                    is_reply: false
                    quoted_tweet_id:
                    replied_to_tweet_id:
                    retweeted_tweet_id:
                    hashtags:
                    - twitter
                    - api
                    mentions:
                    - elonmusk
                    lang: en
                    source: Twitter Web App
                    retweeted: false
                    favorited: true
                    url: https://twitter.com/example_user/status/1876543210987654321
                    author:
                      id: 123456789
                      username: example_user
                      screen_name: example_user
                      name: Example User
                      bio: Just a sample account for API documentation
                      followers_count: 1500
                      following_count: 500
                      profile_image_url: https://pbs.twimg.com/profile_images/example.jpg
                      is_blue_verified: true
                  count: 1
                meta:
                  timestamp: '2026-01-02T16:30:00.123Z'
                  path: /api/v1/accounts/1/home-timeline
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '500':
          description: External service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
  /accounts/{id}/tweets-and-replies:
    get:
      tags:
      - Account Management
      summary: Get account's own tweets and replies
      description: Retrieve the authenticated account's own tweets and replies
      parameters:
      - name: id
        in: path
        required: true
        description: Account ID (local database ID)
        schema:
          type: integer
      - name: limit
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Tweets and replies retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardSuccessResponse'
              example:
                success: true
                data:
                  tweets_count: 10
                  tweets:
                  - id: '1876543210987654321'
                    text: Hello Twitter! This is a sample tweet.
                    created_at: Thu Jan 02 12:00:00 +0000 2026
                    retweet_count: 42
                    like_count: 128
                    reply_count: 15
                    quote_count: 5
                    url: https://twitter.com/myuser/status/1876543210987654321
                    favorited: false
                    retweeted: false
                    author:
                      id: 123456789
                      name: My Account
                      screen_name: myuser
                      profile_image_url: https://pbs.twimg.com/profile_images/example.jpg
                meta:
                  timestamp: '2026-01-02T16:30:00.123Z'
                  path: /api/v1/accounts/1/tweets-and-replies
        '400':
          description: Invalid parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '403':
          description: Account suspended or forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
  /accounts/{id}/messages:
    get:
      tags:
      - Account Messages
      summary: Get message inbox
      description: 'Retrieve direct message conversations for an account with pagination support.


        **Modes:**

        - **Default**: Returns paginated messages from cache (fast)

        - **only_updates=true**: Returns only NEW messages since last fetch (for polling)

        - **force_refresh=true**: Forces full refresh from Twitter API

        '
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Page number (1-indexed, default 1)
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: limit
        in: query
        required: false
        description: Messages per page (default 50, max 100)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 100
      - name: only_updates
        in: query
        required: false
        description: If true, returns only new messages since last fetch (lightweight polling)
        schema:
          type: boolean
          default: false
      - name: force_refresh
        in: query
        required: false
        description: If true, forces a full refresh from Twitter API
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Inbox retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/MessageInboxResponse'
                - type: object
                  properties:
                    pagination:
                      $ref: '#/components/schemas/ApiPagination'
                    has_updates:
                      type: boolean
                      description: Only present when only_updates=true
        '404':
          description: Account not found
        '500':
          description: Failed to fetch inbox
  /accounts/{id}/messages/conversation/{conversationId}:
    get:
      tags:
      - Account Messages
      summary: Get conversation by ID
      description: Retrieve messages from a specific conversation
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: conversationId
        in: path
        required: true
        description: Conversation ID (format recipientId-currentUserId)
        schema:
          type: string
      responses:
        '200':
          description: Conversation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageInboxResponse'
        '400':
          description: Invalid conversation ID
        '404':
          description: Account not found
        '500':
          description: Failed to fetch conversation
  /accounts/{id}/messages/user/{userId}:
    get:
      tags:
      - Account Messages
      summary: Get conversation by user ID
      description: Retrieve messages with a specific user by their user ID
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: userId
        in: path
        required: true
        description: Target user ID
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Conversation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageInboxResponse'
        '400':
          description: Invalid user ID
        '404':
          description: Account not found
        '500':
          description: Failed to fetch conversation
  /accounts/{id}/messages/with/{targetUsername}:
    get:
      tags:
      - Account Messages
      summary: Get conversation by username
      description: Retrieve messages with a specific user by their username
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: targetUsername
        in: path
        required: true
        description: Target user's username
        schema:
          type: string
      responses:
        '200':
          description: Conversation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageInboxResponse'
        '400':
          description: Invalid target username
        '404':
          description: Account not found
        '500':
          description: Failed to fetch conversation
  /accounts/{id}/messages/search/users:
    get:
      tags:
      - Account Messages
      summary: Search users for messaging
      description: Search for users to start a conversation with
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: q
        in: query
        required: true
        description: Search query
        schema:
          type: string
      responses:
        '200':
          description: User search completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageUserSearchResponse'
        '400':
          description: Search query parameter required
        '404':
          description: Account not found
        '500':
          description: Failed to search users
  /accounts/{id}/messages/send:
    post:
      tags:
      - Account Messages
      summary: Send message to user
      description: Send a direct message to a user by recipient ID (creates new conversation if needed)
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - recipient_id
              - text
              properties:
                recipient_id:
                  type: integer
                  format: int64
                  description: Recipient user ID
                text:
                  type: string
                  description: Message text content
                media:
                  type: string
                  format: base64
                  description: Optional base64 encoded image (JPEG/PNG)
            example:
              recipient_id: 985086876922105856
              text: Hello with image!
              media: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
      responses:
        '201':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResult'
        '400':
          description: Invalid request or message send failed
        '404':
          description: Account not found
        '500':
          description: Failed to send message
  /accounts/{id}/messages/conversation/{conversationId}/send:
    post:
      tags:
      - Account Messages
      summary: Send message to conversation
      description: Send a direct message to an existing conversation
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: conversationId
        in: path
        required: true
        description: Conversation ID (format recipientId-currentUserId)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: Message text content
                media:
                  type: string
                  format: base64
                  description: Optional base64 encoded image (JPEG/PNG)
            example:
              text: Hello with image!
              media: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
      responses:
        '201':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResult'
        '400':
          description: Invalid request or message send failed
        '404':
          description: Account not found
        '500':
          description: Failed to send message
    delete:
      tags:
      - Account Messages
      summary: Delete conversation
      description: Delete an existing direct message conversation
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: conversationId
        in: path
        required: true
        description: Conversation ID to delete (format recipientId-currentUserId)
        schema:
          type: string
      responses:
        '200':
          description: Conversation deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  conversation_id:
                    type: string
              example:
                success: true
                message: Conversation deleted successfully
                conversation_id: 107225267-1501679329100668929
        '400':
          description: Failed to delete conversation
        '404':
          description: Account not found
        '500':
          description: Failed to delete conversation
  /accounts/{id}/messages/image:
    get:
      tags:
      - Account Messages
      summary: Load DM image
      description: Proxy endpoint to load direct message images through the user's authenticated session
      parameters:
      - name: id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: url
        in: query
        required: true
        description: The media_url_https from the message attachment
        schema:
          type: string
          format: uri
        example: https://pbs.twimg.com/dm_image/1234567890/photo.jpg
      responses:
        '200':
          description: Image returned successfully
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '400':
          description: Missing url parameter
        '404':
          description: Account not found
        '500':
          description: Failed to fetch image
  /ai/prompt:
    post:
      tags:
      - AI
      summary: Send prompt to AI
      description: 'Send a direct prompt to the configured AI service and receive a response.


        **Requirements:**

        - AI must be configured with valid API key and endpoint

        - AI must be enabled in configuration


        **Use Cases:**

        - Test AI configuration

        - Generate custom content for tweets

        - Get AI assistance for social media tasks

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  description: The prompt text to send to AI
                  example: Generate a creative tweet about artificial intelligence
            examples:
              simple:
                summary: Simple prompt
                value:
                  prompt: Write a short tweet about AI technology
              detailed:
                summary: Detailed prompt
                value:
                  prompt: Create an engaging tweet about the benefits of automation in social media marketing. Make it concise
                    and include relevant hashtags.
      responses:
        '200':
          description: AI response generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request was successful
                    example: true
                  response:
                    type: string
                    description: AI generated response text
                    example: 'AI is revolutionizing how we interact with technology! 🤖 From automation to intelligent assistance,
                      the future is here. #AI #Technology #Innovation'
                  prompt_length:
                    type: integer
                    description: Length of the input prompt in characters
                    example: 45
                  response_length:
                    type: integer
                    description: Length of the AI response in characters
                    example: 156
        '400':
          description: Invalid request (missing or empty prompt)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Missing required field: ''prompt'' (string)'
        '500':
          description: AI request failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'AI request failed: Connection timeout'
        '503':
          description: AI is not configured or disabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: AI is not configured. Please configure AI API key and endpoint in settings.
  /analytics/overview:
    get:
      tags:
      - Analytics
      summary: Get system-wide analytics overview
      description: Returns high-level analytics for all accounts including total followers, growing/declining accounts count
      responses:
        '200':
          description: System analytics overview
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: ../components/schemas/analytics.yaml#/SystemOverview
  /analytics/accounts:
    get:
      tags:
      - Analytics
      summary: Get all accounts with analytics
      description: Returns paginated list of all accounts with their current analytics and growth data
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Page number (1-indexed)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Items per page (max 100)
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 7
        description: 'Period for growth calculation: 1 = 24h, 2-7 = 7d, 8+ = 30d'
      responses:
        '200':
          description: Paginated list of accounts with analytics
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - pagination
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: ../components/schemas/analytics.yaml#/AnalyticsAccountItem
                  pagination:
                    $ref: ../components/schemas/common.yaml#/ApiPagination
  /analytics/top-growers:
    get:
      tags:
      - Analytics
      summary: Get top growing accounts
      description: Returns paginated list of accounts with highest follower growth in the specified period
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Page number (1-indexed)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Items per page (max 100)
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 7
        description: Time period in days
      responses:
        '200':
          description: Paginated list of top growing accounts
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - pagination
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: ../components/schemas/analytics.yaml#/GrowthRankItem
                  pagination:
                    $ref: ../components/schemas/common.yaml#/ApiPagination
  /analytics/decliners:
    get:
      tags:
      - Analytics
      summary: Get declining accounts
      description: Returns paginated list of accounts with highest follower loss in the specified period
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Page number (1-indexed)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Items per page (max 100)
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 7
        description: Time period in days
      responses:
        '200':
          description: Paginated list of declining accounts
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - pagination
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: ../components/schemas/analytics.yaml#/DeclineRankItem
                  pagination:
                    $ref: ../components/schemas/common.yaml#/ApiPagination
  /analytics/compare:
    post:
      tags:
      - Analytics
      summary: Compare multiple accounts
      description: Returns side-by-side comparison of multiple accounts with their dashboards
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_ids
              properties:
                account_ids:
                  type: array
                  items:
                    oneOf:
                    - type: integer
                    - type: string
                  description: Array of account IDs or usernames to compare
                  example:
                  - 1
                  - 2
                  - myusername
      responses:
        '200':
          description: Comparison result
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: ../components/schemas/analytics.yaml#/ComparisonResult
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: account_ids array required
        '404':
          description: No valid accounts found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: No valid accounts found
  /analytics/accounts/{id}/dashboard:
    get:
      tags:
      - Analytics
      summary: Get account analytics dashboard
      description: Returns complete analytics dashboard for a specific account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
          - type: string
        description: Account ID or username
      responses:
        '200':
          description: Account dashboard
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: ../components/schemas/analytics.yaml#/AccountDashboard
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Account not found
  /analytics/accounts/{id}/growth:
    get:
      tags:
      - Analytics
      summary: Get account growth data
      description: Returns growth metrics for a specific time period
      parameters:
      - name: id
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
          - type: string
        description: Account ID or username
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 7
        description: 'Period: 1 = 24h, 2-7 = 7d, 8+ = 30d'
      responses:
        '200':
          description: Growth data
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: ../components/schemas/analytics.yaml#/AccountGrowthData
        '404':
          description: Account not found
  /analytics/accounts/{id}/trend:
    get:
      tags:
      - Analytics
      summary: Get account growth trend
      description: Returns trend analysis with velocity, acceleration and projections
      parameters:
      - name: id
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
          - type: string
        description: Account ID or username
      responses:
        '200':
          description: Trend data
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: ../components/schemas/analytics.yaml#/GrowthTrend
        '404':
          description: Account not found
  /analytics/accounts/{id}/history:
    get:
      tags:
      - Analytics
      summary: Get account follower history
      description: Returns daily follower count history
      parameters:
      - name: id
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
          - type: string
        description: Account ID or username
      responses:
        '200':
          description: Follower history
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: ../components/schemas/analytics.yaml#/HistoryPoint
        '404':
          description: Account not found
  /autoreply/accounts/{id}:
    get:
      tags:
      - AutoReply
      summary: Get account AutoReply status
      description: Get AutoReply status and configuration for a specific account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Account status retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      account_id:
                        type: integer
                      enabled:
                        type: boolean
                      config:
                        $ref: '#/components/schemas/AutoReplyAccountConfig'
                      rules_count:
                        type: integer
        '404':
          description: Account not found
        '500':
          description: Server error
    post:
      tags:
      - AutoReply
      summary: Enable AutoReply for account
      description: Enable AutoReply bot for a specific Twitter account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Account enabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      account_id:
                        type: integer
        '400':
          description: Invalid request
        '500':
          description: Server error
    delete:
      tags:
      - AutoReply
      summary: Disable AutoReply for account
      description: Disable AutoReply bot for a specific Twitter account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Account disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      account_id:
                        type: integer
        '400':
          description: Invalid request
        '500':
          description: Server error
  /autoreply/accounts/{id}/config:
    get:
      tags:
      - AutoReply
      summary: Get account config
      description: Retrieve AutoReply configuration for a specific account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Config retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/AutoReplyAccountConfig'
        '404':
          description: Account not found
        '500':
          description: Server error
    put:
      tags:
      - AutoReply
      summary: Update account config
      description: Update AutoReply configuration for a specific account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoReplyAccountConfig'
      responses:
        '200':
          description: Config updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      config:
                        $ref: '#/components/schemas/AutoReplyAccountConfig'
        '400':
          description: Invalid configuration
        '404':
          description: Account not found
        '500':
          description: Server error
    delete:
      tags:
      - AutoReply
      summary: Reset account config
      description: Reset AutoReply configuration for an account to defaults
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Config reset successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      account_id:
                        type: integer
        '404':
          description: Account not found
        '500':
          description: Server error
  /autoreply/accounts/{id}/rules:
    get:
      tags:
      - AutoReply
      summary: Get account rules
      description: Retrieve all AutoReply rules for a specific account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Rules retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      rules:
                        type: array
                        items:
                          $ref: '#/components/schemas/AutoReplyRule'
                      count:
                        type: integer
                      account_id:
                        type: integer
        '404':
          description: Account not found
        '500':
          description: Server error
    post:
      tags:
      - AutoReply
      summary: Add rule to account
      description: Create a new AutoReply rule for a specific account
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoReplyRuleRequest'
      responses:
        '200':
          description: Rule created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      rule:
                        $ref: '#/components/schemas/AutoReplyRule'
        '400':
          description: Invalid rule data
        '404':
          description: Account not found
        '500':
          description: Server error
  /autoreply/accounts/{id}/logs:
    get:
      tags:
      - AutoReply
      summary: Get account logs
      description: Retrieve AutoReply logs for a specific account with pagination
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 100
      responses:
        '200':
          description: Logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AutoReplyLog'
                  meta:
                    $ref: '#/components/schemas/ApiPagination'
        '404':
          description: Account not found
        '500':
          description: Server error
  /autoreply/accounts:
    get:
      tags:
      - AutoReply
      summary: List all enabled accounts
      description: Retrieve all accounts with AutoReply enabled
      responses:
        '200':
          description: Accounts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      accounts:
                        type: array
                        items:
                          type: object
                          properties:
                            account_id:
                              type: integer
                            enabled:
                              type: boolean
                            rules_count:
                              type: integer
                      count:
                        type: integer
        '500':
          description: Server error
  /autoreply/accounts/bulk:
    post:
      tags:
      - AutoReply
      summary: Enable multiple accounts
      description: Enable AutoReply for multiple accounts at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_ids
              properties:
                account_ids:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Accounts enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      enabled_ids:
                        type: array
                        items:
                          type: integer
                      count:
                        type: integer
        '400':
          description: Invalid request
        '500':
          description: Server error
    delete:
      tags:
      - AutoReply
      summary: Disable multiple accounts
      description: Disable AutoReply for multiple accounts at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_ids
              properties:
                account_ids:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: Accounts disabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      disabled_ids:
                        type: array
                        items:
                          type: integer
                      count:
                        type: integer
        '400':
          description: Invalid request
        '500':
          description: Server error
  /autoreply/rules:
    get:
      tags:
      - AutoReply
      summary: Get all rules
      description: Retrieve all configured AutoReply rules across all accounts
      responses:
        '200':
          description: Rules retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      rules:
                        type: array
                        items:
                          $ref: '#/components/schemas/AutoReplyRule'
                      count:
                        type: integer
        '500':
          description: Server error
    post:
      tags:
      - AutoReply
      summary: Create a rule
      description: Create a new AutoReply rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoReplyRuleRequest'
      responses:
        '200':
          description: Rule created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      rule:
                        $ref: '#/components/schemas/AutoReplyRule'
        '400':
          description: Invalid rule data
        '500':
          description: Server error
  /autoreply/rules/{id}:
    get:
      tags:
      - AutoReply
      summary: Get a rule
      description: Retrieve a single AutoReply rule by ID
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Rule retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      rule:
                        $ref: '#/components/schemas/AutoReplyRule'
        '404':
          description: Rule not found
        '500':
          description: Server error
    put:
      tags:
      - AutoReply
      summary: Update a rule
      description: Update an existing AutoReply rule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoReplyRuleRequest'
      responses:
        '200':
          description: Rule updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      rule:
                        $ref: '#/components/schemas/AutoReplyRule'
        '404':
          description: Rule not found
        '400':
          description: Invalid rule data
        '500':
          description: Server error
    delete:
      tags:
      - AutoReply
      summary: Delete a rule
      description: Permanently delete an AutoReply rule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Rule deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      rule_id:
                        type: integer
        '404':
          description: Rule not found
        '500':
          description: Server error
  /accounts/batch:
    get:
      tags:
      - Batch Operations
      summary: List all batch operations
      description: Get a list of all batch operations with their status. Supports filtering by status or operation type.
      parameters:
      - name: status
        in: query
        description: Filter by batch operation status
        schema:
          type: string
          enum:
          - PENDING
          - RUNNING
          - PAUSED
          - COMPLETED
          - FAILED
          - CANCELLED
      - name: operation_type
        in: query
        description: Filter by operation type
        schema:
          type: string
          enum:
          - ADD_TAG
          - REMOVE_TAG
          - CHANGE_PROXY
          - DELETE_ACCOUNTS
          - UPDATE_PROFILE
          - FOLLOW_USER
          - UNFOLLOW_USER
          - LIKE_TWEET
          - UNLIKE_TWEET
          - RETWEET
          - UNRETWEET
          - TWEET
          - QUOTE_TWEET
          - REPLY_TWEET
          - JOIN_COMMUNITY
          - LEAVE_COMMUNITY
          - START_FARMING
          - STOP_FARMING
          - REPORT_USER
          - SEND_MESSAGE
      responses:
        '200':
          description: List of batch operations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchOperation'
              example:
              - id: 1
                batch_id: 1
                operation_type: ADD_TAG
                status: COMPLETED
                total_count: 10
                completed_count: 10
                failed_count: 0
                data:
                  tag: vip
                created_at: 1699999999
                updated_at: 1700000100
    post:
      tags:
      - Batch Operations
      summary: Create a new batch operation
      description: 'Start a bulk operation on multiple accounts. Operations include:

        - ADD_TAG: Add a tag to accounts

        - REMOVE_TAG: Remove a tag from accounts

        - CHANGE_PROXY: Change proxy for accounts


        - DELETE_ACCOUNTS: Delete accounts

        - UPDATE_PROFILE: Update account profile (name, bio, avatar, etc.)

        - START_FARMING: Start automated farming for accounts

        - STOP_FARMING: Stop automated farming for accounts

        - FOLLOW_USER/UNFOLLOW_USER: Follow or unfollow a user

        - LIKE_TWEET/UNLIKE_TWEET: Like or unlike a tweet

        - RETWEET/UNRETWEET: Retweet or unretweet a tweet

        - TWEET: Create a new tweet

        - QUOTE_TWEET: Quote a tweet with custom text

        - REPLY_TWEET: Reply to a tweet

        - JOIN_COMMUNITY/LEAVE_COMMUNITY: Join or leave a community

        - REPORT_USER: Report a Twitter user

        - SEND_MESSAGE: Send a direct message to a user


        Operations with 5+ items run in parallel using a thread pool.

        Supports selecting all accounts (optionally filtered by tag) using `select_all: true`.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchOperationRequest'
            examples:
              add_tag:
                summary: Add tag to accounts
                value:
                  operation: ADD_TAG
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  data:
                    tag: vip
              add_tag_all:
                summary: Add tag to ALL accounts with filtering
                value:
                  operation: ADD_TAG
                  select_all: true
                  excluded_ids:
                  - 99
                  filters:
                    tags: active_users
                    status: Active
                    min_followers: 100
                  data:
                    tag: vip_plus
              remove_tag:
                summary: Remove tag from accounts
                value:
                  operation: REMOVE_TAG
                  account_ids:
                  - 1
                  - 2
                  - 3
                  data:
                    tag: inactive
              change_proxy:
                summary: Change proxy for accounts
                value:
                  operation: CHANGE_PROXY
                  account_ids:
                  - 10
                  - 11
                  - 12
                  data:
                    proxy: user:pass@proxy.com:8080
              update_profile:
                summary: Update profile for accounts
                value:
                  operation: UPDATE_PROFILE
                  account_ids:
                  - 1
                  - 2
                  data:
                    bio: Crypto enthusiast 🚀
                    website: https://example.com
              start_farming:
                summary: Start farming for multiple accounts
                value:
                  operation: START_FARMING
                  select_all: true
                  filters:
                    tags: farmers
                    status: Active
                  data:
                    config:
                      likesPerHour: 15
                      followsPerHour: 5
              delete_accounts:
                summary: Delete accounts
                value:
                  operation: DELETE_ACCOUNTS
                  account_ids:
                  - 100
                  - 101
                  - 102
                  data: {}
              follow_user_by_id:
                summary: Multiple accounts follow a user by ID
                value:
                  operation: FOLLOW_USER
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  data:
                    user_id: '123456789'
                  delay_ms: 5000
              follow_user_by_username:
                summary: Multiple accounts follow a user by username
                value:
                  operation: FOLLOW_USER
                  account_ids:
                  - 1
                  - 2
                  - 3
                  data:
                    user_id: elonmusk
                  delay_ms: 3000
              like_tweet:
                summary: Multiple accounts like a tweet
                value:
                  operation: LIKE_TWEET
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  data:
                    tweet_id: '1234567890123456789'
                  delay_ms: 3000
              retweet:
                summary: Multiple accounts retweet
                value:
                  operation: RETWEET
                  account_ids:
                  - 1
                  - 2
                  - 3
                  data:
                    tweet_id: '1234567890123456789'
                  delay_ms: 2000
              join_community:
                summary: Multiple accounts join a community
                value:
                  operation: JOIN_COMMUNITY
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  data:
                    community_id: '1875614919212556724'
                  delay_ms: 10000
              create_tweet:
                summary: Multiple accounts create tweets
                value:
                  operation: TWEET
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  data:
                    text: Hello Twitter! This is an automated tweet.
                  delay_ms: 15000
              quote_tweet:
                summary: Multiple accounts quote a tweet
                value:
                  operation: QUOTE_TWEET
                  account_ids:
                  - 1
                  - 2
                  - 3
                  data:
                    text: Great point! Adding my thoughts here.
                    tweet_id: '1234567890123456789'
                  delay_ms: 10000
              reply_tweet:
                summary: Multiple accounts reply to a tweet
                value:
                  operation: REPLY_TWEET
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  data:
                    text: Thanks for sharing this!
                    tweet_id: '1234567890123456789'
                  delay_ms: 8000
              report_user:
                summary: Multiple accounts report a user
                value:
                  operation: REPORT_USER
                  account_ids:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  data:
                    user_id: '123456789'
                  delay_ms: 5000
              send_message_by_id:
                summary: Multiple accounts send a DM to a user by ID
                value:
                  operation: SEND_MESSAGE
                  account_ids:
                  - 1
                  - 2
                  - 3
                  data:
                    user_id: '123456789'
                    text: Hello! This is an automated message.
                  delay_ms: 5000
              send_message_by_username:
                summary: Multiple accounts send a DM to a user by username
                value:
                  operation: SEND_MESSAGE
                  account_ids:
                  - 1
                  - 2
                  - 3
                  data:
                    username: elonmusk
                    text: Hello! This is an automated message.
                  delay_ms: 5000
      responses:
        '201':
          description: Batch operation started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationResponse'
              example:
                batch_id: 550e8400-e29b-41d4-a716-446655440000
                status: RUNNING
                total: 5
                completed: 0
                failed: 0
                message: Batch operation started successfully
        '400':
          description: Invalid request parameters
  /accounts/batch/{id}:
    get:
      tags:
      - Batch Operations
      summary: Get batch operation status
      description: Get detailed status of a specific batch operation including all items
      parameters:
      - name: id
        in: path
        required: true
        description: Batch operation ID
        schema:
          type: integer
      responses:
        '200':
          description: Batch operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationDetail'
              example:
                batch_id: 1
                operation_type: ADD_TAG
                status: RUNNING
                total_count: 5
                completed_count: 3
                failed_count: 1
                data:
                  tag: vip
                result: {}
                created_at: 1699999999
                updated_at: 1700000050
                items:
                - id: 1
                  account_id: 1
                  status: SUCCESS
                  error_message: ''
                  processed_at: 1700000010
                  created_at: 1699999999
                - id: 2
                  account_id: 2
                  status: SUCCESS
                  error_message: ''
                  processed_at: 1700000020
                  created_at: 1699999999
                - id: 3
                  account_id: 3
                  status: FAILED
                  error_message: 'Account not found: 3'
                  processed_at: 1700000030
                  created_at: 1699999999
                - id: 4
                  account_id: 4
                  status: SUCCESS
                  error_message: ''
                  processed_at: 1700000040
                  created_at: 1699999999
                - id: 5
                  account_id: 5
                  status: PENDING
                  error_message: ''
                  processed_at: 0
                  created_at: 1699999999
        '404':
          description: Batch operation not found
    delete:
      tags:
      - Batch Operations
      summary: Cancel a batch operation
      description: Cancel a running batch operation
      parameters:
      - name: id
        in: path
        required: true
        description: Batch operation ID
        schema:
          type: integer
      responses:
        '200':
          description: Batch operation cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: integer
                  status:
                    type: string
                  message:
                    type: string
              example:
                batch_id: 1
                status: CANCELLED
                message: Batch operation cancelled successfully
        '400':
          description: Failed to cancel batch operation
  /accounts/batch/{id}/pause:
    post:
      tags:
      - Batch Operations
      summary: Pause a running batch operation
      description: Pause a batch operation that is currently running. The operation can be resumed later.
      parameters:
      - name: id
        in: path
        required: true
        description: Batch operation ID
        schema:
          type: integer
      responses:
        '200':
          description: Batch operation paused
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: integer
                  status:
                    type: string
                  message:
                    type: string
              example:
                batch_id: 1
                status: PAUSED
                message: Batch operation paused successfully
        '400':
          description: Failed to pause batch operation - batch may not be running
  /accounts/batch/{id}/resume:
    post:
      tags:
      - Batch Operations
      summary: Resume a paused batch operation
      description: Resume a batch operation that was previously paused.
      parameters:
      - name: id
        in: path
        required: true
        description: Batch operation ID
        schema:
          type: integer
      responses:
        '200':
          description: Batch operation resumed
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: integer
                  status:
                    type: string
                  message:
                    type: string
              example:
                batch_id: 550e8400-e29b-41d4-a716-446655440000
                status: RUNNING
                message: Batch operation resumed successfully
        '400':
          description: Failed to resume batch operation - batch may not be paused
  /accounts/batch/{id}/permanent:
    delete:
      tags:
      - Batch Operations
      summary: Permanently delete a batch operation
      description: Permanently delete a batch operation and all its items from the database.
      parameters:
      - name: id
        in: path
        required: true
        description: Batch operation ID
        schema:
          type: integer
      responses:
        '200':
          description: Batch operation permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  batch_id:
                    type: integer
                  message:
                    type: string
              example:
                batch_id: 1
                message: Batch operation permanently deleted
        '400':
          description: Failed to delete batch operation
  /communities/{accountId}/{communityId}/info:
    get:
      tags:
      - Communities
      summary: Get community information
      description: Retrieve detailed information about a Twitter Community
      parameters:
      - name: accountId
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: communityId
        in: path
        required: true
        description: Community unique identifier
        schema:
          type: string
      responses:
        '200':
          description: Community information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Community'
        '404':
          description: Account or community not found
        '500':
          description: Internal server error
  /communities/{accountId}/{communityId}/join:
    post:
      tags:
      - Communities
      summary: Join a community
      description: Join a Twitter Community with the specified account
      parameters:
      - name: accountId
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: communityId
        in: path
        required: true
        description: Community unique identifier
        schema:
          type: string
      responses:
        '200':
          description: Successfully joined community
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Successfully joined community
        '400':
          description: Failed to join community
        '404':
          description: Account or community not found
        '500':
          description: Internal server error
  /communities/{accountId}/{communityId}/leave:
    post:
      tags:
      - Communities
      summary: Leave a community
      description: Leave a Twitter Community with the specified account
      parameters:
      - name: accountId
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: communityId
        in: path
        required: true
        description: Community unique identifier
        schema:
          type: string
      responses:
        '200':
          description: Successfully left community
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Successfully left community
        '400':
          description: Failed to leave community
        '404':
          description: Account or community not found
        '500':
          description: Internal server error
  /communities/{accountId}/{communityId}/tweets:
    get:
      tags:
      - Communities
      summary: Get community tweets
      description: Retrieve tweets from a Twitter Community
      parameters:
      - name: accountId
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: communityId
        in: path
        required: true
        description: Community unique identifier
        schema:
          type: string
      - name: count
        in: query
        description: Number of tweets to retrieve
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: ranking_mode
        in: query
        description: Ranking mode for tweets
        schema:
          type: string
          enum:
          - Recency
          - Relevance
          default: Recency
      - name: cursor
        in: query
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: Community tweets retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      tweets:
                        type: array
                        items:
                          type: object
                          description: Tweet object
                      count:
                        type: integer
                        example: 20
        '404':
          description: Account or community not found
        '500':
          description: Internal server error
    post:
      tags:
      - Communities
      summary: Post tweet to community
      description: Post a new tweet to a Twitter Community
      parameters:
      - name: accountId
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      - name: communityId
        in: path
        required: true
        description: Community unique identifier
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - text
              properties:
                text:
                  type: string
                  description: Tweet text content
                  minLength: 1
                  maxLength: 280
                media:
                  type: array
                  description: Array of base64-encoded media (images/videos) to attach to the tweet (optional)
                  items:
                    type: object
                    required:
                    - data
                    properties:
                      data:
                        type: string
                        description: Base64-encoded media content
                      type:
                        type: string
                        description: 'MIME type of the media (optional).

                          If not provided, will be auto-detected from binary data using magic bytes.

                          Supported types: image/jpeg, image/png, image/gif, video/mp4

                          '
                        enum:
                        - image/jpeg
                        - image/png
                        - image/gif
                        - video/mp4
            examples:
              simple:
                summary: Simple text tweet to community
                value:
                  text: Hello from the community!
              withImage:
                summary: Community tweet with image
                value:
                  text: Check out this photo in our community!
                  media:
                  - data: /9j/4AAQSkZJRgABAQEAYABgAAD...
                    type: image/jpeg
              withVideo:
                summary: Community tweet with video
                value:
                  text: Watch this video in our community!
                  media:
                  - data: AAAAIGZ0eXBpc29tAAACAGlzb21...
                    type: video/mp4
              withMultipleMedia:
                summary: Community tweet with multiple images
                value:
                  text: Multiple photos for our community!
                  media:
                  - data: /9j/4AAQSkZJRgABAQEAYABgAAD...
                    type: image/jpeg
                  - data: iVBORw0KGgoAAAANSUhEUgAAAAUA...
                    type: image/png
      responses:
        '200':
          description: Tweet posted successfully to community
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Successfully posted tweet to community
                  media_count:
                    type: integer
                    description: Number of media items uploaded (only present when media is attached)
                    example: 2
        '400':
          description: Failed to post tweet or invalid request
        '404':
          description: Account or community not found
        '500':
          description: Internal server error
  /configurations:
    get:
      tags:
      - Configuration
      summary: List all configurations
      description: Retrieve list of all stored configurations
      responses:
        '200':
          description: List of all configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Configuration'
              example:
              - name: proxy
                data:
                  check_interval: 30
                  max_account_per_proxy: 5
                created_at: 1704585600
                updated_at: 1704672000
              - name: account
                data:
                  auto_check_account: true
                  auto_replace_proxy: true
                created_at: 1704585600
                updated_at: 1704672000
        '500':
          description: Failed to retrieve configurations
  /configurations/proxy:
    get:
      tags:
      - Configuration
      summary: Get proxy configuration
      description: Retrieve current proxy management configuration
      responses:
        '200':
          description: Proxy configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyConfiguration'
        '500':
          description: Failed to retrieve proxy configuration
    put:
      tags:
      - Configuration
      summary: Update proxy configuration
      description: 'Update proxy management settings.


        **Configuration Options:**

        - `check_interval`: How often to check proxy health (in minutes)

        - `max_account_per_proxy`: Maximum accounts that can use a single proxy

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyConfiguration'
            example:
              check_interval: 30
              max_account_per_proxy: 5
      responses:
        '200':
          description: Proxy configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Proxy configuration updated successfully
        '400':
          description: Invalid configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Required field 'check_interval' is missing in proxy configuration
        '500':
          description: Failed to update proxy configuration
  /configurations/account:
    get:
      tags:
      - Configuration
      summary: Get account configuration
      description: Retrieve current account management configuration
      responses:
        '200':
          description: Account configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountConfiguration'
        '500':
          description: Failed to retrieve account configuration
    put:
      tags:
      - Configuration
      summary: Update account configuration
      description: 'Update account management settings.


        **Configuration Options:**

        - `auto_check_account`: Automatically check account status

        - `auto_replace_proxy`: Automatically replace failed proxies

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountConfiguration'
            example:
              auto_check_account: true
              auto_replace_proxy: true
      responses:
        '200':
          description: Account configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Account configuration updated successfully
        '400':
          description: Invalid configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Required field 'auto_check_account' is missing in account configuration
        '500':
          description: Failed to update account configuration
  /configurations/http_server:
    get:
      tags:
      - Configuration
      summary: Get HTTP server configuration
      description: Retrieve current HTTP server configuration
      responses:
        '200':
          description: HTTP server configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpServerConfiguration'
        '500':
          description: Failed to retrieve HTTP server configuration
    put:
      tags:
      - Configuration
      summary: Update HTTP server configuration
      description: 'Update HTTP server settings.


        **Configuration Options:**

        - `port`: Server listening port

        - `host`: Server host address

        - `cors_enabled`: Enable/disable CORS

        - `auth_enabled`: Enable/disable authentication

        - `auth_token`: Authentication token (if auth enabled)


        **Note:** Changes may require server restart to take effect.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpServerConfiguration'
            example:
              port: 8080
              host: 0.0.0.0
              cors_enabled: true
              auth_enabled: false
              auth_token: your-secret-token
      responses:
        '200':
          description: HTTP server configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: HTTP server configuration updated successfully
        '400':
          description: Invalid configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Required field 'port' is missing in HTTP server configuration
        '500':
          description: Failed to update HTTP server configuration
  /configurations/ai:
    get:
      tags:
      - Configuration
      summary: Get AI configuration
      description: Retrieve current AI configuration settings
      responses:
        '200':
          description: AI configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIConfiguration'
        '500':
          description: Failed to retrieve AI configuration
    put:
      tags:
      - Configuration
      summary: Update AI configuration
      description: 'Update AI configuration settings for text generation.


        **Custom API Support:**

        - Provide your own `endpoint` URL (OpenAI-compatible format)

        - Specify the `model` name you want to use

        - Configure `api_key` for authentication

        - Set `enabled` to activate/deactivate AI features


        **Example Providers:**

        - OpenAI: `https://api.openai.com/v1/chat/completions`

        - Groq: `https://api.groq.com/openai/v1/chat/completions`

        - Together.ai: `https://api.together.xyz/v1/chat/completions`

        - Any OpenAI-compatible API endpoint


        **API Key Validation:**

        - When API key changes, it will be automatically validated

        - Validation uses the `/models` endpoint if available

        - Returns error if validation fails

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIConfiguration'
            examples:
              openai:
                summary: OpenAI Configuration
                value:
                  endpoint: https://api.openai.com/v1/chat/completions
                  api_key: sk-...
                  model: gpt-4
                  enabled: true
                  max_tokens: 280
                  temperature: 0.7
              groq:
                summary: Groq Configuration
                value:
                  endpoint: https://api.groq.com/openai/v1/chat/completions
                  api_key: gsk_...
                  model: llama-3.1-70b-versatile
                  enabled: true
                  max_tokens: 280
                  temperature: 0.7
              custom:
                summary: Custom API Configuration
                value:
                  endpoint: https://your-custom-api.com/v1/chat/completions
                  api_key: your-api-key
                  model: custom-model-name
                  enabled: true
                  max_tokens: 280
                  temperature: 0.8
      responses:
        '200':
          description: AI configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: AI configuration updated successfully
                  api_key_validated:
                    type: boolean
                    description: Whether API key was validated (true if key changed)
                    example: true
        '400':
          description: Invalid configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                examples:
                  missingField:
                    summary: Missing required field
                    value:
                      error: Required field 'endpoint' is missing in AI configuration
                  emptyEndpoint:
                    summary: Empty endpoint
                    value:
                      error: Endpoint cannot be empty
                  emptyModel:
                    summary: Empty model
                    value:
                      error: Model cannot be empty
                  invalidApiKey:
                    summary: Invalid API key
                    value:
                      error: Invalid API key. Please check your API key and try again.
        '500':
          description: Failed to update AI configuration
  /configurations/initialize:
    post:
      tags:
      - Configuration
      summary: Initialize default configurations
      description: 'Initialize all default configurations in the database.


        **Default Configurations:**

        - Proxy configuration (auto_check, check_interval, etc.)

        - Account configuration (auto_assign_proxy, default_tags, etc.)

        - HTTP server configuration (port, host, cors_enabled, etc.)

        - AI configuration (endpoint, api_key, model, enabled, etc.)


        **Use Cases:**

        - First-time setup

        - Reset configurations to defaults

        - Recover from corrupted configuration

        '
      responses:
        '200':
          description: Default configurations initialized successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Default configurations initialized successfully
        '500':
          description: Failed to initialize configurations
  /configurations/{name}:
    get:
      tags:
      - Configuration
      summary: Get configuration by name
      description: Retrieve a specific configuration by its name
      parameters:
      - name: name
        in: path
        required: true
        description: Configuration name (e.g., "proxy", "account", "http_server", "ai", or custom)
        schema:
          type: string
        examples:
          proxy:
            value: proxy
            summary: Proxy configuration
          account:
            value: account
            summary: Account configuration
          http_server:
            value: http_server
            summary: HTTP server configuration
          ai:
            value: ai
            summary: AI configuration
          custom:
            value: my_custom_config
            summary: Custom configuration
      responses:
        '200':
          description: Configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
        '404':
          description: Configuration not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Configuration not found
        '400':
          description: Invalid request
    put:
      tags:
      - Configuration
      summary: Update configuration by name
      description: 'Update a specific configuration by its name.


        **Validation:**

        - For known configuration types (proxy, account, http_server, ai), required fields are validated

        - For custom configurations, any valid JSON object is accepted


        **Known Configuration Types:**

        - `proxy`: Requires check_interval, max_account_per_proxy

        - `account`: Requires auto_check_account, auto_replace_proxy

        - `http_server`: Requires host, port, cors_enabled, auth_enabled, auth_token

        - `ai`: Requires endpoint, api_key, enabled, model

        '
      parameters:
      - name: name
        in: path
        required: true
        description: Configuration name
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Configuration data as JSON object
              additionalProperties: true
            examples:
              custom:
                summary: Custom configuration
                value:
                  setting1: value1
                  setting2: 42
                  nested:
                    key: value
      responses:
        '200':
          description: Configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Configuration updated successfully
        '400':
          description: Invalid configuration or missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Missing required fields for configuration: proxy'
        '500':
          description: Failed to update configuration
    delete:
      tags:
      - Configuration
      summary: Delete configuration by name
      description: 'Delete a specific configuration from the database.


        **Warning:** Deleting system configurations (proxy, account, http_server, ai) may cause application malfunction.

        '
      parameters:
      - name: name
        in: path
        required: true
        description: Configuration name to delete
        schema:
          type: string
      responses:
        '204':
          description: Configuration deleted successfully
        '404':
          description: Configuration not found or could not be deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Configuration not found or could not be deleted
        '400':
          description: Invalid request
  /data-fetcher/user/{userId}/tweets:
    get:
      tags:
      - Data
      summary: Fetch user tweets by user ID
      description: 'Get tweets from specific user by their ID.


        **Account Selection**: Uses LRU (Least Recently Used) algorithm - selects the account with the oldest last-usage timestamp
        per operation type. Each account has a 20-second cooldown per operation. On failure, retries with different accounts
        (max 3 attempts).

        '
      parameters:
      - name: userId
        in: path
        required: true
        description: Twitter user ID
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Request processed (check status field for success/failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataFetcherResponse'
              example:
                success: true
                data:
                  status: Success
                  tweets_count: 2
                  error_message: ''
                  tweets:
                  - id: 1234567890123456789
                    text: This is a sample tweet
                    created_at: Wed Jan 08 12:00:00 +0000 2026
                    like_count: 100
                    retweet_count: 50
                    reply_count: 10
                    quote_count: 5
                    url: https://x.com/username/status/1234567890123456789
                    favorited: false
                    retweeted: false
                    author:
                      id: 44196397
                      name: Elon Musk
                      screen_name: elonmusk
                      profile_image_url: https://pbs.twimg.com/profile_images/2008546467615580160/57KcqsTA_normal.jpg
                meta:
                  path: /api/v1/data-fetcher/user/44196397/tweets
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Invalid user ID or limit
        '403':
          description: Protected user account
        '404':
          description: User not found
        '500':
          description: Failed to fetch tweets
  /data-fetcher/user/{userId}/tweets-and-replies:
    get:
      tags:
      - Data
      summary: Fetch user tweets and replies by user ID
      description: Get tweets and replies from specific user by their ID
      parameters:
      - name: userId
        in: path
        required: true
        description: Twitter user ID
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Request processed (check status field for success/failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataFetcherResponse'
        '400':
          description: Invalid user ID or limit
        '403':
          description: Protected user account
        '404':
          description: User not found
        '500':
          description: Failed to fetch tweets
  /data-fetcher/user/{username}/tweets-by-username:
    get:
      tags:
      - Data
      summary: Fetch user tweets by username
      description: Get tweets from specific user by their username
      parameters:
      - name: username
        in: path
        required: true
        description: Twitter username
        schema:
          type: string
      - name: limit
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Request processed (check status field for success/failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataFetcherResponse'
        '400':
          description: Invalid username or limit
        '403':
          description: Protected user account
        '404':
          description: User not found
        '500':
          description: Failed to fetch tweets
  /data-fetcher/tweet/{tweetId}:
    get:
      tags:
      - Data
      summary: Fetch tweet information by ID
      description: Get detailed information about a specific tweet
      parameters:
      - name: tweetId
        in: path
        required: true
        description: Twitter tweet ID
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Tweet information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - Success
                      tweet:
                        $ref: '#/components/schemas/TweetData'
                  meta:
                    type: object
              example:
                success: true
                data:
                  status: Success
                  tweet:
                    id: 1234567890123456789
                    text: This is a sample tweet
                    created_at: Wed Jan 08 12:00:00 +0000 2026
                    like_count: 100
                    retweet_count: 50
                    reply_count: 10
                    quote_count: 5
                    url: https://x.com/elonmusk/status/1234567890123456789
                    favorited: false
                    retweeted: false
                    author:
                      id: 44196397
                      name: Elon Musk
                      screen_name: elonmusk
                      profile_image_url: https://pbs.twimg.com/profile_images/2008546467615580160/57KcqsTA_normal.jpg
                meta:
                  path: /api/v1/data-fetcher/tweet/1234567890123456789
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Invalid tweet ID
        '404':
          description: Tweet not found
        '500':
          description: Failed to fetch tweet info
  /data-fetcher/search/tag/{tag}:
    get:
      tags:
      - Data
      summary: Search tweets by hashtag
      description: Search for tweets containing a specific hashtag
      parameters:
      - name: tag
        in: path
        required: true
        description: Hashtag to search for (without
        schema:
          type: string
      - name: limit
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: product
        in: query
        description: Search product type
        schema:
          type: string
          enum:
          - Latest
          - Top
          default: Latest
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - Success
                    - Failed
                    - NotFound
                    description: Search operation status
                  tweets_count:
                    type: integer
                    description: Number of tweets found
                  error_message:
                    type: string
                    description: Error description (if status is not Success)
                  search_query:
                    type: string
                    description: The full search query used (with
                  product:
                    type: string
                    description: Search product type used
                  tweets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TweetData'
                    description: Array of tweets (only present if status is Success)
        '400':
          description: Invalid tag or limit
        '404':
          description: No tweets found
        '500':
          description: Failed to search tweets
  /data-fetcher/search/text:
    get:
      tags:
      - Data
      summary: Search tweets by text query
      description: Search for tweets containing specific text or keywords
      parameters:
      - name: query
        in: query
        required: true
        description: Text query to search for
        schema:
          type: string
      - name: limit
        in: query
        description: Number of tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: product
        in: query
        description: Search product type
        schema:
          type: string
          enum:
          - Latest
          - Top
          default: Latest
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - Success
                    - Failed
                    - NotFound
                    description: Search operation status
                  tweets_count:
                    type: integer
                    description: Number of tweets found
                  error_message:
                    type: string
                    description: Error description (if status is not Success)
                  search_query:
                    type: string
                    description: The search query used
                  product:
                    type: string
                    description: Search product type used
                  tweets:
                    type: array
                    items:
                      $ref: '#/components/schemas/TweetData'
                    description: Array of tweets (only present if status is Success)
        '400':
          description: Invalid query or limit (query parameter required)
        '404':
          description: No tweets found
        '500':
          description: Failed to search tweets
  /data-fetcher/user/{username}/info:
    get:
      tags:
      - Data
      summary: Fetch user information by username
      description: Get detailed information about a Twitter user
      parameters:
      - name: username
        in: path
        required: true
        description: Twitter username
        schema:
          type: string
      responses:
        '200':
          description: User information retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - Success
                      user:
                        $ref: '#/components/schemas/UserData'
                  meta:
                    type: object
                    properties:
                      path:
                        type: string
                      timestamp:
                        type: string
              example:
                success: true
                data:
                  status: Success
                  user:
                    id: 44196397
                    username: elonmusk
                    screen_name: ''
                    name: Elon Musk
                    bio: ''
                    description: ''
                    followers_count: 231695346
                    following_count: 1264
                    tweet_count: 93604
                    profile_image_url: https://pbs.twimg.com/profile_images/2008546467615580160/57KcqsTA_normal.jpg
                    profile_banner_url: https://pbs.twimg.com/profile_banners/44196397/1739948056
                    following: false
                    followed_by: false
                    created_at: ''
                    location: ''
                    is_blue_verified: true
                    verified: false
                    protected_account: false
                    default_profile: false
                    default_profile_image: false
                    favourites_count: 0
                    listed_count: 0
                    media_count: 0
                    possibly_sensitive: false
                    profile_image_shape: Circle
                    can_dm: false
                    can_media_tag: false
                    pinned_tweet_ids: []
                    birth_day: 0
                    birth_month: 0
                    birth_year: 0
                    birth_visibility: ''
                    birth_year_visibility: ''
                    is_identity_verified: false
                    can_highlight_tweets: false
                    highlighted_tweets: ''
                    url: ''
                    ntab_unread_count: 0
                    dm_unread_count: 0
                    total_unread_count: 0
                    xchat_unread_count: 0
                    is_from_urt: false
                meta:
                  path: /api/v1/data-fetcher/user/elonmusk/info
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Invalid username
        '404':
          description: User not found
        '500':
          description: Failed to fetch user info
  /data-fetcher/tweet/{tweetId}/validate:
    get:
      tags:
      - Data
      summary: Validate tweet ID
      description: Check if a tweet ID exists and is valid
      parameters:
      - name: tweetId
        in: path
        required: true
        description: Twitter tweet ID to validate
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Validation completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - Success
                      tweet_id:
                        type: string
                      validation_result:
                        type: string
                        enum:
                        - Valid
                        - Invalid
                        - NotFound
                        - Protected
                        - Suspended
                      is_valid:
                        type: boolean
                  meta:
                    type: object
              example:
                success: true
                data:
                  status: Success
                  tweet_id: '1234567890123456789'
                  validation_result: Valid
                  is_valid: true
                meta:
                  path: /api/v1/data-fetcher/tweet/1234567890123456789/validate
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Invalid tweet ID
        '500':
          description: Failed to validate tweet
  /data-fetcher/tweet/{tweetId}/quotes:
    get:
      tags:
      - Data
      summary: Fetch quote tweets
      description: Get tweets that quote a specific tweet
      parameters:
      - name: tweetId
        in: path
        required: true
        description: Twitter tweet ID
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: Number of quote tweets to fetch
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Quote tweets retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - Success
                      tweet_id:
                        type: string
                      quotes_count:
                        type: integer
                      quotes:
                        type: array
                        items:
                          $ref: '#/components/schemas/TweetData'
                  meta:
                    type: object
              example:
                success: true
                data:
                  status: Success
                  tweet_id: '1234567890123456789'
                  quotes_count: 1
                  quotes:
                  - id: 9876543210987654321
                    text: This is a quote tweet
                    created_at: Wed Jan 08 14:00:00 +0000 2026
                    like_count: 25
                    retweet_count: 10
                    reply_count: 5
                    quote_count: 0
                    url: https://x.com/user/status/9876543210987654321
                    favorited: false
                    retweeted: false
                    author:
                      id: 12345678
                      name: Sample User
                      screen_name: sampleuser
                      profile_image_url: https://pbs.twimg.com/profile_images/default.jpg
                meta:
                  path: /api/v1/data-fetcher/tweet/1234567890123456789/quotes
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Invalid tweet ID or limit
        '500':
          description: Failed to fetch quote tweets
  /data-fetcher/cache/stats:
    get:
      tags:
      - Data
      summary: Get cache statistics
      description: Retrieve information about the data fetcher cache
      responses:
        '200':
          description: Cache statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      cache_size:
                        type: integer
                      cache_duration_seconds:
                        type: integer
                      cooldown_duration_seconds:
                        type: integer
                  meta:
                    type: object
              example:
                success: true
                data:
                  status: Success
                  cache_size: 150
                  cache_duration_seconds: 300
                  cooldown_duration_seconds: 60
                meta:
                  path: /api/v1/data-fetcher/cache/stats
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Failed to get cache stats
  /data-fetcher/cache/clear:
    post:
      tags:
      - Data
      summary: Clear cache
      description: Clear all cached data in the data fetcher
      responses:
        '200':
          description: Cache cleared successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      message:
                        type: string
                  meta:
                    type: object
              example:
                success: true
                data:
                  status: Success
                  message: Cache cleared successfully
                meta:
                  path: /api/v1/data-fetcher/cache/clear
                  timestamp: '2026-01-09T05:34:25.640Z'
        '400':
          description: Failed to clear cache
  /farming/start:
    post:
      tags:
      - Farming
      summary: Start farming for an account
      description: Start account farming with tweet engagement automation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              properties:
                account_id:
                  type: integer
                  description: Account ID to start farming for
                username:
                  type: string
                  description: Username as alternative to account_id
                config:
                  $ref: '#/components/schemas/FarmingConfig'
      responses:
        '200':
          description: Farming started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      account_id:
                        type: integer
                      username:
                        type: string
                      status:
                        type: string
        '400':
          description: Invalid configuration
        '404':
          description: Account not found
        '500':
          description: Server error
  /farming/stop:
    post:
      tags:
      - Farming
      summary: Stop farming for an account
      description: Stop active farming for an account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              properties:
                account_id:
                  type: integer
                  description: Account ID to stop farming for
      responses:
        '200':
          description: Farming stopped successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      account_id:
                        type: integer
                      status:
                        type: string
        '400':
          description: Bad request
        '500':
          description: Server error
  /farming/pause:
    post:
      tags:
      - Farming
      summary: Pause farming for an account
      description: Temporarily pause active farming
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              properties:
                account_id:
                  type: integer
                  description: Account ID to pause farming for
      responses:
        '200':
          description: Farming paused successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      account_id:
                        type: integer
                      status:
                        type: string
        '400':
          description: Bad request
        '500':
          description: Server error
  /farming/resume:
    post:
      tags:
      - Farming
      summary: Resume farming for an account
      description: Resume paused farming
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              properties:
                account_id:
                  type: integer
                  description: Account ID to resume farming for
      responses:
        '200':
          description: Farming resumed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      account_id:
                        type: integer
                      status:
                        type: string
        '400':
          description: Bad request
        '500':
          description: Server error
  /farming/status/{username}:
    get:
      tags:
      - Farming
      summary: Get farming session status
      description: Get current farming status for a specific account
      parameters:
      - name: username
        in: path
        required: true
        description: Twitter username
        schema:
          type: string
      responses:
        '200':
          description: Farming status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/FarmingSession'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
        '404':
          description: Session not found
        '500':
          description: Server error
  /farming/config:
    put:
      tags:
      - Farming
      summary: Update farming configuration
      description: Update the farming configuration for an active farming session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              - config
              properties:
                account_id:
                  type: integer
                  description: Account ID to update farming config for
                config:
                  $ref: '#/components/schemas/FarmingConfig'
      responses:
        '200':
          description: Farming configuration updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      account_id:
                        type: integer
                      config:
                        $ref: '#/components/schemas/FarmingConfig'
        '400':
          description: Invalid configuration
        '500':
          description: Server error
  /farming/sessions:
    get:
      tags:
      - Farming
      summary: Get all farming sessions
      description: Retrieve all active farming sessions with optional status filtering
      parameters:
      - name: status
        in: query
        description: Filter by farming status
        schema:
          type: string
          enum:
          - ACTIVE
          - PAUSED
          - STOPPED
      responses:
        '200':
          description: Farming sessions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      sessions:
                        type: array
                        items:
                          $ref: '#/components/schemas/FarmingSession'
                      total:
                        type: integer
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
        '500':
          description: Server error
  /proxies:
    get:
      tags:
      - Proxies
      summary: Get all proxies
      description: Retrieve list of proxy servers
      parameters:
      - name: status
        in: query
        description: Filter proxies by status
        schema:
          type: string
          enum:
          - NONE
          - CHECKING
          - WORKING
          - NOT_WORKING
      - name: type
        in: query
        description: Filter proxies by type
        schema:
          type: string
          enum:
          - HTTP
          - SOCKS5
      - name: search
        in: query
        description: Search filter for IP address or port
        schema:
          type: string
      - name: page
        in: query
        description: Page number for pagination (used with limit)
        schema:
          type: integer
          minimum: 1
      - name: limit
        in: query
        description: Number of proxies per page (used with page)
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: start
        in: query
        description: Start index for range pagination (alternative to page/limit)
        schema:
          type: integer
          minimum: 0
      - name: end
        in: query
        description: End index for range pagination (alternative to page/limit)
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: Proxies retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      proxies:
                        type: array
                        items:
                          $ref: '#/components/schemas/Proxy'
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          total_working:
                            type: integer
                          start:
                            type: integer
                          end:
                            type: integer
                          returned:
                            type: integer
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
    post:
      tags:
      - Proxies
      summary: Add new proxy
      description: Add proxy server to the pool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyRequest'
      responses:
        '201':
          description: Proxy added successfully
        '400':
          description: Invalid proxy configuration
  /proxies/bulk:
    post:
      tags:
      - Proxies
      summary: Bulk import proxies
      description: Import multiple proxies from text format
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - proxies
              properties:
                proxies:
                  type: array
                  items:
                    type: string
                  minItems: 1
              example:
                proxies:
                - user:pass@192.168.1.1:8888
                - 192.168.1.2:8888
      responses:
        '201':
          description: All proxies imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkProxyResponse'
        '207':
          description: Multi-Status - Some proxies imported, some failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkProxyResponse'
        '400':
          description: Bad request - All proxies failed to import
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkProxyResponse'
  /rss:
    get:
      tags:
      - RSS
      summary: Get all RSS feeds
      description: Returns RSS posting status for all accounts with active RSS sessions, including subscriptions and recent
        posts
      responses:
        '200':
          description: RSS feeds retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  active_sessions_count:
                    type: integer
                    description: Number of active RSS sessions
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        account_id:
                          type: integer
                        username:
                          type: string
                        status:
                          type: string
                          enum:
                          - ACTIVE
                          - PAUSED
                          - STOPPED
                        enabled:
                          type: boolean
                        started_at:
                          type: integer
                          format: int64
                          description: Unix timestamp
                        last_active_at:
                          type: integer
                          format: int64
                          description: Unix timestamp
                        last_post_at:
                          type: integer
                          format: int64
                          description: Unix timestamp
                        total_posts:
                          type: integer
                          description: Total tweets posted from RSS
                        total_errors:
                          type: integer
                        total_items_checked:
                          type: integer
                        last_error:
                          type: string
                        subscriptions:
                          type: array
                          description: Active RSS feed subscriptions
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                              feed_url:
                                type: string
                              feed_title:
                                type: string
                              last_checked:
                                type: integer
                                format: int64
                                description: Unix timestamp
                        recent_posts:
                          type: array
                          description: Last 10 tweets posted from RSS
                          items:
                            type: object
                            properties:
                              tweet_id:
                                type: string
                              title:
                                type: string
                              link:
                                type: string
                              posted_at:
                                type: integer
                                format: int64
                                description: Unix timestamp
                        config:
                          $ref: '#/components/schemas/RSSPostingConfig'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
        '500':
          description: Server error
  /rss/{account_id}:
    get:
      tags:
      - RSS
      summary: Get RSS feeds for specific account
      description: 'Returns all RSS feed subscriptions for an account and posting session details if active.


        **Important:** This endpoint shows RSS feeds even if posting is not started yet.

        - If RSS feeds exist but posting is not started: `session` will be `null`

        - If RSS posting is active: `session` will contain session details

        '
      parameters:
      - name: account_id
        in: path
        required: true
        description: Twitter account ID
        schema:
          type: integer
      responses:
        '200':
          description: RSS feeds retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  account_id:
                    type: integer
                  subscriptions:
                    type: array
                    description: RSS feed subscriptions for this account
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        feed_url:
                          type: string
                        feed_title:
                          type: string
                        enabled:
                          type: boolean
                        last_checked:
                          type: integer
                          format: int64
                          description: Unix timestamp
                        check_interval_seconds:
                          type: integer
                        last_error:
                          type: string
                  session:
                    nullable: true
                    description: RSS posting session details (null if not started)
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                        - ACTIVE
                        - PAUSED
                        - STOPPED
                      enabled:
                        type: boolean
                      started_at:
                        type: integer
                        format: int64
                        description: Unix timestamp
                      last_active_at:
                        type: integer
                        format: int64
                        description: Unix timestamp
                      last_post_at:
                        type: integer
                        format: int64
                        description: Unix timestamp
                      total_posts:
                        type: integer
                        description: Total tweets posted from RSS
                      total_errors:
                        type: integer
                      total_items_checked:
                        type: integer
                      last_error:
                        type: string
                      config:
                        $ref: '#/components/schemas/RSSPostingConfig'
                  recent_posts:
                    type: array
                    description: Last 10 tweets posted from RSS (empty if no session)
                    items:
                      type: object
                      properties:
                        tweet_id:
                          type: string
                        title:
                          type: string
                        link:
                          type: string
                        posted_at:
                          type: integer
                          format: int64
                          description: Unix timestamp
        '400':
          description: Bad request - Invalid account_id
        '404':
          description: No RSS feeds found for this account
        '500':
          description: Server error
  /rss/{subscription_id}:
    put:
      tags:
      - RSS
      summary: Edit RSS feed subscription
      description: Update RSS feed subscription properties (URL, title, interval, enabled status)
      parameters:
      - name: subscription_id
        in: path
        required: true
        description: RSS subscription ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                feed_url:
                  type: string
                  format: uri
                  description: RSS feed URL
                  example: https://example.com/feed.xml
                feed_title:
                  type: string
                  description: Feed title
                  example: Example Feed
                check_interval_seconds:
                  type: integer
                  description: Feed check interval in seconds
                  example: 300
                enabled:
                  type: boolean
                  description: Enable/disable subscription
                  example: true
      responses:
        '200':
          description: RSS feed updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  subscription_id:
                    type: integer
                  feed_url:
                    type: string
                  feed_title:
                    type: string
                  enabled:
                    type: boolean
        '400':
          description: Bad request - Invalid subscription_id or JSON
        '404':
          description: RSS feed not found
        '500':
          description: Server error
    delete:
      tags:
      - RSS
      summary: Delete RSS feed subscription
      description: Permanently delete an RSS feed subscription
      parameters:
      - name: subscription_id
        in: path
        required: true
        description: RSS subscription ID
        schema:
          type: integer
      responses:
        '200':
          description: RSS feed deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  subscription_id:
                    type: integer
                  feed_url:
                    type: string
        '400':
          description: Bad request - Invalid subscription_id
        '404':
          description: RSS feed not found
        '500':
          description: Server error
  /rss/config:
    post:
      tags:
      - RSS
      summary: Set RSS posting configuration
      description: 'Configure RSS-to-Twitter posting settings for an account.


        **Behavior:**

        - If RSS posting is already active: Updates the configuration immediately

        - If RSS posting is not started: Saves config to be used when starting


        **Note:** Use this endpoint before `/rss/start` to configure posting behavior

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - type: object
                required:
                - account_id
                properties:
                  account_id:
                    type: integer
                    description: Twitter account ID
              - $ref: '#/components/schemas/RSSPostingConfig'
            example:
              account_id: 1
              auto_post_enabled: true
              max_posts_per_hour: 5
              min_delay_between_posts: 300
              action_delay_min: 5
              action_delay_max: 15
              tweet_template: '{title}\n\n{link}'
              include_description: false
              max_description_length: 100
              keyword_filters: []
              exclude_keywords: []
              check_interval_seconds: 300
              enabled: true
      responses:
        '200':
          description: RSS config set successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  account_id:
                    type: integer
                  username:
                    type: string
                  config:
                    $ref: '#/components/schemas/RSSPostingConfig'
                  note:
                    type: string
                    description: Additional info (only if not started yet)
        '400':
          description: Bad request - Invalid config or missing account_id
        '404':
          description: Account not found
        '500':
          description: Server error
  /rss/add:
    post:
      tags:
      - RSS
      summary: Add RSS feed to account
      description: Add an RSS feed subscription to a Twitter account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              - feed_url
              properties:
                account_id:
                  type: integer
                  description: Twitter account ID
                feed_url:
                  type: string
                  format: uri
                  description: RSS feed URL
                  example: https://example.com/feed.xml
                feed_title:
                  type: string
                  description: Optional feed title
                  example: Example Feed
                check_interval_seconds:
                  type: integer
                  default: 300
                  description: Feed check interval in seconds (default 5 minutes)
                enabled:
                  type: boolean
                  default: true
                  description: Enable subscription
      responses:
        '200':
          description: RSS feed added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  subscription_id:
                    type: integer
                  account_id:
                    type: integer
                  username:
                    type: string
                  feed_url:
                    type: string
        '400':
          description: Bad request - Missing required fields
        '404':
          description: Account not found
        '500':
          description: Server error
  /rss/start:
    post:
      tags:
      - RSS
      summary: Start RSS posting for account
      description: 'Start automatic RSS-to-Twitter posting for an account.


        **Recommended workflow:**

        1. Use `/rss/config` to set configuration first

        2. Then use this endpoint with just `account_id` to start


        **Note:** Config can be passed inline, but it''s optional. If not provided, uses default or previously set config.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              properties:
                account_id:
                  type: integer
                  description: Twitter account ID
            examples:
              simple:
                summary: Simple start (recommended)
                value:
                  account_id: 1
              with_config:
                summary: Start with inline config
                value:
                  account_id: 1
                  auto_post_enabled: true
                  max_posts_per_hour: 5
                  action_delay_min: 5
                  action_delay_max: 15
      responses:
        '200':
          description: RSS posting started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  account_id:
                    type: integer
                  username:
                    type: string
                  config:
                    $ref: '#/components/schemas/RSSPostingConfig'
        '400':
          description: Bad request or already running
        '404':
          description: Account not found
        '500':
          description: Server error
  /rss/stop:
    post:
      tags:
      - RSS
      summary: Stop RSS posting for account
      description: Stop automatic RSS-to-Twitter posting for an account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - account_id
              properties:
                account_id:
                  type: integer
                  description: Twitter account ID
      responses:
        '200':
          description: RSS posting stopped successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  account_id:
                    type: integer
        '400':
          description: Bad request or not running
        '500':
          description: Server error
  /system/stats:
    get:
      tags:
      - System
      summary: Get system statistics
      responses:
        '200':
          description: System statistics
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/SystemStats'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
  /tasks:
    get:
      tags:
      - Tasks
      summary: Get all tasks
      description: Retrieve list of all tasks with optional filtering
      parameters:
      - name: status
        in: query
        description: Filter tasks by status
        schema:
          type: string
          enum:
          - PENDING
          - STARTED
          - COMPLETED
          - FAILED
          - CANCELLED
          - PAUSED
      - name: type
        in: query
        description: Filter tasks by type
        schema:
          type: string
          enum:
          - UNDEFINED
          - FOLLOW
          - LIKE
          - RETWEET
          - TWEET
          - QUOTE
          - REPLY
      - name: limit
        in: query
        description: Maximum number of tasks to return
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
      responses:
        '200':
          description: List of tasks retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      tasks:
                        type: array
                        items:
                          $ref: '#/components/schemas/Task'
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          total_active:
                            type: integer
                          start:
                            type: integer
                          end:
                            type: integer
                          returned:
                            type: integer
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
    post:
      tags:
      - Tasks
      summary: Create new task
      description: Create a new automation task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/FollowTaskRequest'
              - $ref: '#/components/schemas/LikeTaskRequest'
              - $ref: '#/components/schemas/QuoteTaskRequest'
              - $ref: '#/components/schemas/ReplyTaskRequest'
              - $ref: '#/components/schemas/TweetTaskRequest'
              - $ref: '#/components/schemas/RetweetTaskRequest'
              discriminator:
                propertyName: type
      responses:
        '201':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Invalid task configuration
        '500':
          description: Internal server error
  /tasks/{taskId}:
    delete:
      tags:
      - Tasks
      summary: Delete task
      description: Remove task from system
      parameters:
      - name: taskId
        in: path
        required: true
        description: Task unique identifier
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Task deleted successfully
        '404':
          description: Task not found
  /tasks/{taskId}/pause:
    post:
      tags:
      - Tasks
      summary: Pause task
      description: Pause task execution
      parameters:
      - name: taskId
        in: path
        required: true
        description: Task unique identifier
        schema:
          type: string
      responses:
        '200':
          description: Task paused successfully
        '404':
          description: Task not found
  /tasks/{taskId}/resume:
    post:
      tags:
      - Tasks
      summary: Resume task
      description: Resume paused task execution
      parameters:
      - name: taskId
        in: path
        required: true
        description: Task unique identifier
        schema:
          type: string
      responses:
        '200':
          description: Task resumed successfully
        '404':
          description: Task not found
  /api/v1/workflows:
    get:
      tags:
      - Workflows
      summary: List all workflows
      description: Retrieve a list of all registered workflows
      operationId: getWorkflows
      responses:
        '200':
          description: List of workflows
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
    post:
      tags:
      - Workflows
      summary: Create a new workflow
      description: Create a new workflow from JSON definition
      operationId: createWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowDefinition'
      responses:
        '201':
          description: Workflow created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          description: Invalid workflow definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/workflows/stats:
    get:
      tags:
      - Workflows
      summary: Get workflow engine statistics
      description: Get statistics about the workflow engine
      operationId: getWorkflowStats
      responses:
        '200':
          description: Workflow engine statistics
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalWorkflows:
                        type: integer
                        description: Total number of workflows
                      pendingWorkflows:
                        type: integer
                        description: Number of pending workflows
                      runningWorkflows:
                        type: integer
                        description: Number of running workflows
                      completedWorkflows:
                        type: integer
                        description: Number of completed workflows
                      failedWorkflows:
                        type: integer
                        description: Number of failed workflows
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
  /api/v1/workflows/{id}:
    get:
      tags:
      - Workflows
      summary: Get workflow by ID
      description: Retrieve a specific workflow by its ID
      operationId: getWorkflowById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                - meta
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Workflow'
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
    put:
      tags:
      - Workflows
      summary: Update workflow
      description: Update an existing workflow (not yet implemented)
      operationId: updateWorkflow
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowDefinition'
      responses:
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Workflows
      summary: Delete workflow
      description: Delete a workflow by ID
      operationId: deleteWorkflow
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: Workflow deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  id:
                    type: integer
        '400':
          description: Cannot delete (workflow may be running)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/workflows/{id}/start:
    post:
      tags:
      - Workflows
      summary: Start workflow
      description: Start execution of a workflow
      operationId: startWorkflow
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: Workflow started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /api/v1/workflows/{id}/pause:
    post:
      tags:
      - Workflows
      summary: Pause workflow
      description: Pause a running workflow
      operationId: pauseWorkflow
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: Workflow paused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /api/v1/workflows/{id}/resume:
    post:
      tags:
      - Workflows
      summary: Resume workflow
      description: Resume a paused workflow
      operationId: resumeWorkflow
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: Workflow resumed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /api/v1/workflows/{id}/cancel:
    post:
      tags:
      - Workflows
      summary: Cancel workflow
      description: Cancel a running or paused workflow
      operationId: cancelWorkflow
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: Workflow cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
  /api/v1/workflows/schedules:
    get:
      tags:
      - Workflow Schedules
      summary: List all schedules
      description: Retrieve all workflow schedules
      operationId: getAllSchedules
      responses:
        '200':
          description: List of schedules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
  /api/v1/workflows/{id}/schedules:
    get:
      tags:
      - Workflow Schedules
      summary: Get schedules for workflow
      description: Get all schedules for a specific workflow
      operationId: getWorkflowSchedules
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      responses:
        '200':
          description: List of schedules for the workflow
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
    post:
      tags:
      - Workflow Schedules
      summary: Add schedule to workflow
      description: Create a new schedule for a workflow
      operationId: addSchedule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Workflow ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cron_expression
              properties:
                cron_expression:
                  type: string
                  description: Cron expression (minute hour day month weekday)
                  example: 0 12 * * *
                name:
                  type: string
                  description: Optional schedule name
                  example: Daily at noon
                enabled:
                  type: boolean
                  default: true
                  description: Whether the schedule is enabled
      responses:
        '201':
          description: Schedule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '400':
          description: Invalid schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/workflows/schedules/{id}:
    put:
      tags:
      - Workflow Schedules
      summary: Update schedule
      description: Update an existing schedule
      operationId: updateSchedule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Schedule ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cron_expression:
                  type: string
                  description: Cron expression
                name:
                  type: string
                  description: Schedule name
                enabled:
                  type: boolean
                  description: Whether the schedule is enabled
      responses:
        '200':
          description: Schedule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Workflow Schedules
      summary: Delete schedule
      description: Delete a schedule
      operationId: deleteSchedule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Schedule ID
      responses:
        '200':
          description: Schedule deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  message:
                    type: string
  /api/v1/workflows/schedules/{id}/enable:
    post:
      tags:
      - Workflow Schedules
      summary: Enable schedule
      description: Enable a schedule
      operationId: enableSchedule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Schedule ID
      responses:
        '200':
          description: Schedule enabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  enabled:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/workflows/schedules/{id}/disable:
    post:
      tags:
      - Workflow Schedules
      summary: Disable schedule
      description: Disable a schedule
      operationId: disableSchedule
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Schedule ID
      responses:
        '200':
          description: Schedule disabled
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  enabled:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Schedule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Account:
      type: object
      properties:
        id:
          type: integer
          description: Account unique identifier
        username:
          type: string
          description: Twitter username
        email:
          type: string
          description: Account email address
        email_password:
          type: string
          description: Email password
        status:
          type: string
          enum:
          - Pending
          - Validating
          - Active
          - Suspended
          - AuthFailed
          - TwoFactorRequired
          - ProxyError
          - Failed
          description: Current account status
        proxy_id:
          type: integer
          description: ID of assigned proxy (0 if no proxy)
        farmingStatus:
          type: string
          enum:
          - NONE
          - ACTIVE
          - PAUSED
          - STOPPED
          description: Current farming status for this account
        tags:
          type: array
          items:
            type: string
          description: Account tags for categorization
        cookie:
          type: string
          description: Full session cookie string containing all Twitter session cookies
          example: auth_token=abc123; ct0=xyz789; guest_id=v1%3A...
        proxy:
          allOf:
          - $ref: '#/components/schemas/ProxyInfo'
          nullable: true
          description: Detailed proxy information (null if no proxy assigned)
        user:
          allOf:
          - $ref: '#/components/schemas/UserData'
          nullable: true
          description: Twitter user profile data (null if not fetched)
    AccountRequest:
      type: object
      required:
      - username
      properties:
        username:
          type: string
          description: Twitter username (required)
        password:
          type: string
          description: Account password
        email_password:
          type: string
          description: Email password
        email:
          type: string
          description: Account email address
        totp_code:
          type: string
          description: 2FA/TOTP code for account setup
        cookie:
          type: string
          description: 'Cookie string containing authentication tokens. Supports multiple formats:

            - **JSON**: `{"auth_token": "abc123", "ct0": "xyz789"}`

            - **Key-Value (semicolon)**: `auth_token=abc123; ct0=xyz789`

            - **Key-Value (ampersand)**: `auth_token=abc123&ct0=xyz789`


            **Required**: Only `auth_token` is required. `ct0` is optional and will be auto-generated if not provided.

            '
          example: auth_token=e60325c7c48ac45c8e297235ab1b392415987093
        proxy:
          description: Inline proxy configuration (alternative to proxy_id). Supports object or string.
          oneOf:
          - $ref: '#/components/schemas/ProxyRequest'
          - type: string
            description: 'Proxy string formats: ''ip:port:user:pass'', ''ip:port'', ''http://user:pass@ip:port'''
            example: 192.168.1.1:8080:user:pass
          nullable: true
        proxy_id:
          type: integer
          description: ID of proxy to assign to this account
        tags:
          type: array
          items:
            type: string
          description: Tags to categorize this account
        auto_assign_proxy:
          type: boolean
          default: false
          description: Automatically assign a free proxy to this account
        display_name:
          type: string
          description: Display name for the account
      description: "Create a new Twitter account. Either 'cookie' or 'password' is required.\n\n**Authentication Methods:**\n\
        - **Cookie-based**: Provide 'cookie' field with auth_token (ct0 optional)\n- **Password-based**: Provide 'password'\
        \ field\n\n**Cookie Formats (only auth_token REQUIRED):**\n- **JSON Format**: `{\"auth_token\":\"abc123\"}` or `{\"\
        auth_token\":\"abc123\",\"ct0\":\"xyz789\"}`\n  - Must be valid JSON object\n  - Only 'auth_token' is required\n \
        \ - ct0 will be auto-generated if not provided\n- **Key-Value Format (semicolon)**: `auth_token=abc123` or `auth_token=abc123;\
        \ ct0=xyz789`\n- **Key-Value Format (ampersand)**: `auth_token=abc123` or `auth_token=abc123&ct0=xyz789`\n  - Automatically\
        \ converted to JSON internally\n  - Keys are normalized to lowercase\n\n**Cookie Fields:**\n- `auth_token` - **Required**\
        \ for authentication\n- `ct0` - **Optional** CSRF token (auto-generated if not provided)\n\n**Proxy Assignment:**\n\
        - **Manual**: Set 'proxy_id' to existing proxy ID\n- **Inline**: Provide 'proxy' object to create new proxy\n- **Auto**:\
        \ Set 'auto_assign_proxy: true' to auto-assign free proxy\n"
    BulkAccountResponse:
      type: object
      properties:
        created:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Original array index of the account
              account:
                $ref: '#/components/schemas/Account'
        failed:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Original array index of the account
              error:
                type: string
                description: Error message
              username:
                type: string
                description: Username of failed account (if available)
        summary:
          type: object
          properties:
            total:
              type: integer
              description: Total number of accounts attempted
            success_count:
              type: integer
              description: Number of successfully created accounts
            failed_count:
              type: integer
              description: Number of failed account creations
    AccountConfiguration:
      type: object
      description: Account management configuration
      required:
      - auto_check_account
      - auto_replace_proxy
      properties:
        auto_check_account:
          type: boolean
          description: Automatically check account status
          example: true
        auto_replace_proxy:
          type: boolean
          description: Automatically replace failed proxies
          example: true
    AccountStats:
      type: object
      description: Account statistics snapshot for growth tracking
      properties:
        id:
          type: integer
          description: Stats record ID
          example: 1
        account_id:
          type: integer
          description: Account ID (foreign key)
          example: 1
        followers_count:
          type: integer
          description: Number of followers at collection time
          example: 1250
        following_count:
          type: integer
          description: Number of following at collection time
          example: 450
        tweet_count:
          type: integer
          description: Number of tweets at collection time
          example: 320
        favourites_count:
          type: integer
          description: Number of likes/favourites at collection time
          example: 1540
        collected_at:
          type: integer
          format: int64
          description: Unix timestamp when stats were collected
          example: 1704585600
    AccountGrowth:
      type: object
      description: Growth metrics calculated from two consecutive statistics snapshots
      properties:
        followers_diff:
          type: integer
          description: Change in follower count (positive = gained, negative = lost)
          example: 15
        following_diff:
          type: integer
          description: Change in following count
          example: 5
        tweet_diff:
          type: integer
          description: Change in tweet count
          example: 3
        favourites_diff:
          type: integer
          description: Change in favourites/likes count
          example: 12
        time_diff_seconds:
          type: integer
          format: int64
          description: Time difference between snapshots in seconds
          example: 3600
    AIConfiguration:
      type: object
      properties:
        endpoint:
          type: string
          format: uri
          description: OpenAI-compatible API endpoint URL
        api_key:
          type: string
          description: API key for the service
        model:
          type: string
          description: Model name to use for generation
        enabled:
          type: boolean
          description: Whether AI features are enabled
        max_tokens:
          type: integer
          description: Maximum number of tokens to generate
        temperature:
          type: number
          format: float
          description: Controls randomness in generation (0.0-1.0)
    SystemOverview:
      type: object
      description: System-wide analytics overview
      properties:
        total_accounts:
          type: integer
          description: Total number of accounts in the system
        active_accounts:
          type: integer
          description: Number of active accounts
        total_followers:
          type: integer
          format: int64
          description: Sum of all followers across all accounts
        growing_accounts:
          type: integer
          description: Number of accounts with positive growth
        declining_accounts:
          type: integer
          description: Number of accounts losing followers
        top_growers:
          type: array
          items:
            $ref: '#/GrowthRankItem'
    GrowthRankItem:
      type: object
      properties:
        id:
          type: integer
          description: Account ID in our system
        username:
          type: string
          description: Twitter username
        profile_image_url:
          type: string
          description: Profile image URL
        followers_count:
          type: integer
          description: Current follower count
        following_count:
          type: integer
          description: Current following count
        tweet_count:
          type: integer
          description: Total tweets posted
        growth:
          $ref: '#/GrowthPeriodData'
        trend:
          $ref: '#/TrendData'
        engagement_rate:
          type: number
          format: double
          description: Engagement rate percentage
    DeclineRankItem:
      type: object
      properties:
        id:
          type: integer
          description: Account ID in our system
        username:
          type: string
          description: Twitter username
        profile_image_url:
          type: string
          description: Profile image URL
        followers_count:
          type: integer
          description: Current follower count
        following_count:
          type: integer
          description: Current following count
        tweet_count:
          type: integer
          description: Total tweets posted
        growth:
          $ref: '#/GrowthPeriodData'
        trend:
          $ref: '#/TrendData'
        engagement_rate:
          type: number
          format: double
          description: Engagement rate percentage
    GrowthPeriodData:
      type: object
      description: Growth data for a specific period
      properties:
        followers_diff:
          type: integer
          description: Change in followers (can be negative)
        following_diff:
          type: integer
          description: Change in following count
        tweet_diff:
          type: integer
          description: Tweets posted in period
        period:
          type: string
          enum:
          - 24h
          - 7d
          - 30d
          description: Time period for the data
    TrendData:
      type: object
      nullable: true
      description: Trend analysis data
      properties:
        direction:
          type: string
          enum:
          - accelerating
          - stable
          - decelerating
          - declining
          description: Overall trend direction
        velocity_per_day:
          type: number
          format: double
          description: Average followers per day
        acceleration:
          type: number
          format: double
          description: Change in velocity
        projected_7d:
          type: integer
          description: Projected followers in 7 days
        projected_30d:
          type: integer
          description: Projected followers in 30 days
    AccountSnapshot:
      type: object
      description: Account state at a point in time
      properties:
        followers_count:
          type: integer
          description: Number of followers
        following_count:
          type: integer
          description: Number of accounts following
        tweet_count:
          type: integer
          description: Total tweets
        favourites_count:
          type: integer
          description: Total likes given
        collected_at:
          type: integer
          format: int64
          description: Unix timestamp when data was collected
        listed_count:
          type: integer
          description: Number of lists account is on
        media_count:
          type: integer
          description: Number of media items posted
        is_blue_verified:
          type: boolean
          description: Twitter Blue subscription status
        follow_ratio:
          type: number
          format: double
          description: followers_count / following_count
    AccountGrowthData:
      type: object
      description: Change in metrics over a period
      properties:
        followers_diff:
          type: integer
          description: Change in followers (can be negative)
        following_diff:
          type: integer
          description: Change in following count
        tweet_diff:
          type: integer
          description: Tweets posted in period
        favourites_diff:
          type: integer
          description: Likes given in period
        time_diff_seconds:
          type: integer
          format: int64
          description: Period duration in seconds
    TweetMetricsSnapshot:
      type: object
      description: Performance metrics from recent tweets
      properties:
        collected_at:
          type: integer
          format: int64
          description: Unix timestamp when data was collected
        sample_size:
          type: integer
          description: Number of tweets analyzed
        total_likes:
          type: integer
          format: int64
          description: Sum of all likes
        total_retweets:
          type: integer
          format: int64
          description: Sum of all retweets
        total_replies:
          type: integer
          format: int64
          description: Sum of all replies
        total_views:
          type: integer
          format: int64
          description: Sum of all views
        avg_likes:
          type: number
          format: double
          description: Average likes per tweet
        avg_retweets:
          type: number
          format: double
          description: Average retweets per tweet
        avg_replies:
          type: number
          format: double
          description: Average replies per tweet
        avg_views:
          type: number
          format: double
          description: Average views per tweet
        engagement_rate:
          type: number
          format: double
          description: (likes + retweets + replies) / views * 100
        best_tweet_id:
          type: integer
          format: int64
          description: Tweet ID with most likes
        worst_tweet_id:
          type: integer
          format: int64
          description: Tweet ID with least likes
        best_tweet_likes:
          type: integer
          format: int64
          description: Likes on best tweet
        worst_tweet_likes:
          type: integer
          format: int64
          description: Likes on worst tweet
    GrowthTrend:
      type: object
      description: Trend analysis and projections
      properties:
        direction:
          type: string
          enum:
          - accelerating
          - stable
          - decelerating
          - declining
          description: Overall trend direction
        velocity_7d:
          type: number
          format: double
          description: Average daily growth last 7 days
        velocity_prev_7d:
          type: number
          format: double
          description: Average daily growth previous 7 days
        acceleration:
          type: number
          format: double
          description: velocity_7d - velocity_prev_7d
        projected_7d:
          type: integer
          description: Projected followers in 7 days
        projected_30d:
          type: integer
          description: Projected followers in 30 days
    PeriodSummary:
      type: object
      description: Summary for a specific time period
      properties:
        period:
          type: string
          enum:
          - daily
          - weekly
          - monthly
          description: Period type
        period_start:
          type: integer
          format: int64
          description: Period start (Unix timestamp)
        period_end:
          type: integer
          format: int64
          description: Period end (Unix timestamp)
        start_followers:
          type: integer
          description: Followers at period start
        end_followers:
          type: integer
          description: Followers at period end
        followers_change:
          type: integer
          description: Net change
        followers_change_pct:
          type: number
          format: double
          description: Percentage change
        tweets_posted:
          type: integer
          description: Tweets posted in period
        avg_daily_growth:
          type: number
          format: double
          description: Average daily follower change
    HistoryPoint:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp
        followers:
          type: integer
          description: Follower count at this time
    AccountDashboard:
      type: object
      description: Complete analytics dashboard for an account
      properties:
        id:
          type: integer
          description: Account ID in our system
        username:
          type: string
          description: Current username
        profile_image_url:
          type: string
          description: Profile image URL
        generated_at:
          type: integer
          format: int64
          description: When dashboard was generated (Unix timestamp)
        current:
          $ref: '#/AccountSnapshot'
        growth_24h:
          $ref: '#/AccountGrowthData'
        growth_7d:
          $ref: '#/AccountGrowthData'
        growth_30d:
          $ref: '#/AccountGrowthData'
        today:
          $ref: '#/PeriodSummary'
        this_week:
          $ref: '#/PeriodSummary'
        this_month:
          $ref: '#/PeriodSummary'
        trend:
          $ref: '#/GrowthTrend'
        tweet_metrics:
          $ref: '#/TweetMetricsSnapshot'
        daily_history:
          type: array
          items:
            $ref: '#/HistoryPoint'
    ComparisonResult:
      type: object
      description: Result of comparing multiple accounts
      properties:
        accounts:
          type: array
          items:
            $ref: '#/AccountDashboard'
        best_grower_id:
          type: integer
          description: Account ID with best growth
        best_engagement_id:
          type: integer
          description: Account ID with best engagement
    AnalyticsAccountItem:
      type: object
      description: Account summary with detailed analytics data
      properties:
        id:
          type: integer
          description: Account ID in our system
        username:
          type: string
          description: Twitter username
        profile_image_url:
          type: string
          description: Profile image URL
        followers_count:
          type: integer
          description: Current follower count
        following_count:
          type: integer
          description: Current following count
        tweet_count:
          type: integer
          description: Total tweets posted by account
        growth:
          $ref: '#/GrowthPeriodData'
        trend:
          $ref: '#/TrendData'
        tweet_metrics:
          type: object
          nullable: true
          description: Tweet performance metrics (null if no data)
          properties:
            total_likes:
              type: integer
              format: int64
              description: Sum of all likes on recent tweets
            total_retweets:
              type: integer
              format: int64
              description: Sum of all retweets
            total_views:
              type: integer
              format: int64
              description: Sum of all views
            avg_likes:
              type: number
              format: double
              description: Average likes per tweet
            avg_retweets:
              type: number
              format: double
              description: Average retweets per tweet
            engagement_rate:
              type: number
              format: double
              description: Engagement rate percentage ((likes + retweets + replies) / views * 100)
            sample_size:
              type: integer
              description: Number of tweets analyzed
            best_tweet_id:
              type: integer
              format: int64
              description: Tweet ID with most likes
            best_tweet_likes:
              type: integer
              format: int64
              description: Like count of the best performing tweet
    AutoReplyRule:
      type: object
      properties:
        id:
          type: integer
          description: Unique rule ID
          example: 1
        name:
          type: string
          description: Rule name for identification
          example: Welcome Message
        trigger_type:
          type: integer
          description: Type of trigger (0=MENTION, 1=DM)
          enum:
          - 0
          - 1
          example: 1
        trigger_pattern:
          type: string
          description: Pattern to match (keyword, regex, etc.)
          example: hello|hi|hey
        response_template:
          type: string
          description: Response template with placeholders
          example: Hello {username}, thanks for reaching out!
        enabled:
          type: boolean
          description: Whether the rule is active
          default: true
        priority:
          type: integer
          description: Rule priority (higher = processed first)
          default: 0
        cooldown_seconds:
          type: integer
          description: Minimum seconds between responses to same user
          default: 3600
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when rule was created
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when rule was last updated
        match_mode:
          type: integer
          description: Match mode (0=CONTAINS, 1=EXACT, 2=REGEX)
          enum:
          - 0
          - 1
          - 2
          default: 0
        case_sensitive:
          type: boolean
          description: Whether matching is case-sensitive
          default: false
        trigger_keywords:
          type: array
          items:
            type: string
          description: List of keywords to match (OR logic)
          example:
          - hello
          - hi
          - hey
        response_variants:
          type: array
          items:
            type: string
          description: Alternative responses (randomly selected)
          example:
          - Hi there!
          - Hello!
          - Hey!
        ai_instruction:
          type: string
          description: Instruction for AI-generated responses
          example: Respond in a friendly, helpful manner
        mark_as_read:
          type: boolean
          description: Mark DM as read after processing
          default: true
        response_mode:
          type: integer
          description: Response mode (0=TEMPLATE, 1=AI, 2=HYBRID)
          enum:
          - 0
          - 1
          - 2
          default: 0
      description: 'Auto-reply rule defining trigger conditions and response behavior.


        **Trigger Types:**

        - 0 (MENTION): Reply to mentions

        - 1 (DM): Reply to direct messages


        **Match Modes:**

        - 0 (CONTAINS): Message contains the pattern

        - 1 (EXACT): Exact match

        - 2 (REGEX): Regular expression match


        **Response Modes:**

        - 0 (TEMPLATE): Use response_template with placeholders

        - 1 (AI): Use ai_instruction for AI generation

        - 2 (HYBRID): Template + AI enhancement'
    AutoReplyRuleRequest:
      type: object
      required:
      - name
      - trigger_type
      - response_template
      properties:
        name:
          type: string
          description: Rule name
        trigger_type:
          type: integer
          description: Type of trigger (0=MENTION, 1=DM)
        trigger_pattern:
          type: string
          description: Pattern to match
        response_template:
          type: string
          description: Response template with placeholders
        enabled:
          type: boolean
          default: true
        priority:
          type: integer
          default: 0
        cooldown_seconds:
          type: integer
          default: 3600
        match_mode:
          type: integer
          default: 0
        case_sensitive:
          type: boolean
          default: false
        trigger_keywords:
          type: array
          items:
            type: string
        response_variants:
          type: array
          items:
            type: string
        ai_instruction:
          type: string
        mark_as_read:
          type: boolean
          default: true
        response_mode:
          type: integer
          default: 0
    AutoReplyLog:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique log ID
        account_id:
          type: integer
          description: Account that processed the event
        event_type:
          type: string
          description: Type of event (mention_reply, dm_reply)
          enum:
          - mention_reply
          - dm_reply
        trigger_id:
          type: string
          description: Tweet ID or DM ID that triggered
        trigger_user:
          type: string
          description: Username who triggered
        trigger_text:
          type: string
          description: Original text that triggered
        rule_id:
          type: integer
          description: ID of the matched rule
        response_text:
          type: string
          description: Response that was sent
        status:
          type: string
          description: Result status
          enum:
          - success
          - failed
          - skipped
          - rate_limited
        error_message:
          type: string
          description: Error details if failed
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp of the event
    AutoReplyState:
      type: object
      properties:
        id:
          type: integer
          description: State record ID
        account_id:
          type: integer
          description: Associated account ID
        last_mention_id:
          type: string
          description: Last processed mention tweet ID
        last_dm_cursor:
          type: string
          description: DM inbox cursor for pagination
        last_poll_time:
          type: integer
          format: int64
          description: Last successful poll timestamp
        is_active:
          type: boolean
          description: Whether account is active in the bot
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
    AutoReplyStats:
      type: object
      properties:
        total_mentions_processed:
          type: integer
          description: Total mentions processed
          example: 150
        total_dms_processed:
          type: integer
          description: Total DMs processed
          example: 75
        total_replies_sent:
          type: integer
          description: Total replies sent
          example: 200
        total_errors:
          type: integer
          description: Total errors encountered
          example: 5
        last_activity:
          type: integer
          format: int64
          description: Timestamp of last activity
        is_running:
          type: boolean
          description: Whether the bot is currently running
    AutoReplyGlobalConfig:
      type: object
      properties:
        poll_interval_seconds:
          type: integer
          description: Interval between polls in seconds
          default: 60
          minimum: 10
          maximum: 3600
        max_accounts_per_poll:
          type: integer
          description: Maximum accounts to process in each poll cycle
          default: 10
          minimum: 1
          maximum: 100
        log_all_events:
          type: boolean
          description: Log all auto-reply events
          default: true
        max_log_entries:
          type: integer
          description: Maximum number of log entries to keep
          default: 10000
          minimum: 100
          maximum: 100000
      description: 'Global AutoReply bot configuration


        Controls overall bot behavior, polling intervals, and logging settings.'
    DMResponseMode:
      type: integer
      description: DM response mode
      enum:
      - 0
      - 1
      - 2
      - 3
      x-enum-descriptions:
        0: TEMPLATE - Use static response templates
        1: AI_ENHANCED - Template with AI enhancements
        2: FULL_AI - Fully AI-generated responses
        3: HYBRID - Mix of template and AI
    DMResponseConfig:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/DMResponseMode'
          default: 0
        ai_system_prompt:
          type: string
          description: Custom AI system prompt for DM responses
          example: You are a helpful assistant. Respond in a friendly and professional manner.
        max_response_length:
          type: integer
          description: Maximum response length in characters
          default: 280
          minimum: 10
          maximum: 10000
        maintain_conversation_tone:
          type: boolean
          description: Maintain tone of incoming message
          default: true
        use_emoji:
          type: boolean
          description: Include emojis in responses
          default: true
        language_override:
          type: string
          description: Force responses in specific language (ISO 639-1 code)
          example: en
        conversation_history_depth:
          type: integer
          description: Number of previous messages to include in context
          default: 5
          minimum: 0
          maximum: 50
      description: 'Configuration for DM response generation


        Controls how responses are generated (template vs AI), tone, length, and conversation context.'
    DMUserFilterConfig:
      type: object
      properties:
        whitelist_enabled:
          type: boolean
          description: Enable whitelist (only respond to whitelisted users)
          default: false
        whitelist_usernames:
          type: array
          items:
            type: string
          description: List of whitelisted usernames
          example:
          - trusted_user1
          - vip_user
        whitelist_user_ids:
          type: array
          items:
            type: integer
            format: int64
          description: List of whitelisted user IDs
          example:
          - 12345678
          - 87654321
        blacklist_usernames:
          type: array
          items:
            type: string
          description: List of blocked usernames
          example:
          - spam_user
          - blocked_user
        blacklist_user_ids:
          type: array
          items:
            type: integer
            format: int64
          description: List of blocked user IDs
          example:
          - 98765432
        blacklist_bio_keywords:
          type: array
          items:
            type: string
          description: Keywords in user bio that trigger blocking
          example:
          - bot
          - crypto
          - spam
        min_follower_count:
          type: integer
          description: Minimum follower count to respond to
          default: 0
          minimum: 0
        min_account_age_days:
          type: integer
          description: Minimum account age in days to respond to
          default: 0
          minimum: 0
        block_new_accounts:
          type: boolean
          description: Block responses to accounts created less than min_account_age_days
          default: false
        block_no_profile_pic:
          type: boolean
          description: Block responses to users without profile pictures
          default: false
        block_no_bio:
          type: boolean
          description: Block responses to users without bio
          default: false
        block_suspicious_usernames:
          type: boolean
          description: Block responses to users with suspicious username patterns
          default: false
        max_messages_per_user_per_day:
          type: integer
          description: Maximum messages to send to a single user per day
          default: 10
          minimum: 1
          maximum: 100
        block_repeated_messages:
          type: boolean
          description: Block responses to duplicate messages from same user
          default: true
      description: 'User filtering configuration for DMs


        Controls which users receive auto-replies based on whitelist/blacklist, account age, follower count, and suspicious
        indicators.'
    DMDelayConfig:
      type: object
      properties:
        min_typing_delay_ms:
          type: integer
          description: Minimum delay before sending (milliseconds)
          default: 500
          minimum: 0
          maximum: 60000
        max_typing_delay_ms:
          type: integer
          description: Maximum delay before sending (milliseconds)
          default: 3000
          minimum: 0
          maximum: 120000
        chars_per_second:
          type: integer
          description: Simulated typing speed (characters per second)
          default: 5
          minimum: 1
          maximum: 20
        simulate_typing_indicator:
          type: boolean
          description: Simulate typing indicator before sending
          default: true
        add_random_jitter:
          type: boolean
          description: Add random variation to delays
          default: true
        respect_quiet_hours:
          type: boolean
          description: Don't send during quiet hours
          default: true
        quiet_hours_start:
          type: integer
          description: Quiet hours start (hour in 24h format, 0-23)
          default: 23
          minimum: 0
          maximum: 23
        quiet_hours_end:
          type: integer
          description: Quiet hours end (hour in 24h format, 0-23)
          default: 8
          minimum: 0
          maximum: 23
        quiet_hours_delay_minutes:
          type: integer
          description: Additional delay when received during quiet hours (minutes)
          default: 30
          minimum: 0
          maximum: 720
      description: 'Delay configuration for DM responses


        Adds human-like delays, typing simulation, and respects quiet hours.


        **Quiet Hours:**

        Time range (in 24h format) when DMs are not auto-replied. Messages received during quiet hours will be delayed by
        quiet_hours_delay_minutes.'
    AutoReplyAccountConfig:
      type: object
      properties:
        account_id:
          type: integer
          description: Twitter account ID (0 = global default config)
          example: 123
        enabled:
          type: boolean
          description: Enable auto-reply for this account
          default: false
        max_replies_per_hour:
          type: integer
          description: Maximum replies per hour for this account
          default: 10
          minimum: 1
          maximum: 100
        cooldown_per_user_seconds:
          type: integer
          description: Cooldown period for same user (seconds)
          default: 3600
          minimum: 0
          maximum: 86400
        min_reply_delay_seconds:
          type: integer
          description: Minimum delay between replies (seconds)
          default: 3
          minimum: 0
          maximum: 300
        max_reply_delay_seconds:
          type: integer
          description: Maximum delay between replies (seconds)
          default: 5
          minimum: 0
          maximum: 300
        max_dm_messages_per_hour:
          type: integer
          description: Maximum DMs to process per hour
          default: 200
          minimum: 1
          maximum: 1000
        max_mentions_per_hour:
          type: integer
          description: Maximum mentions to process per hour
          default: 50
          minimum: 1
          maximum: 500
        dm_poll_interval_seconds:
          type: integer
          description: DM polling interval in seconds
          default: 10
          minimum: 5
          maximum: 300
        mention_poll_interval_seconds:
          type: integer
          description: Mention polling interval in seconds
          default: 10
          minimum: 5
          maximum: 300
        reply_to_mentions:
          type: boolean
          description: Enable mention auto-reply
          default: true
        reply_to_dms:
          type: boolean
          description: Enable DM auto-reply
          default: true
        require_rule_match:
          type: boolean
          description: Only reply if a rule matches (false = reply to all)
          default: true
        min_account_age_days:
          type: integer
          description: Minimum target account age in days
          default: 0
          minimum: 0
        skip_verified_accounts:
          type: boolean
          description: Skip auto-replying to verified accounts
          default: false
        skip_protected_accounts:
          type: boolean
          description: Skip auto-replying to protected accounts
          default: true
        dm_response_config:
          $ref: '#/components/schemas/DMResponseConfig'
        user_filter_config:
          $ref: '#/components/schemas/DMUserFilterConfig'
        delay_config:
          $ref: '#/components/schemas/DMDelayConfig'
        enable_ai_responses:
          type: boolean
          description: Enable AI-generated responses
          default: false
        default_ai_system_prompt:
          type: string
          description: Default AI system prompt for this account
          example: You are a customer support bot for our company. Be helpful and professional.
        ai_timeout_seconds:
          type: integer
          description: AI response generation timeout
          default: 30
          minimum: 5
          maximum: 120
        fallback_to_template_on_ai_error:
          type: boolean
          description: Use template response if AI generation fails
          default: true
        max_conversation_context_messages:
          type: integer
          description: Maximum number of messages to include in conversation context
          default: 10
          minimum: 0
          maximum: 100
        track_conversation_state:
          type: boolean
          description: Track conversation state for context-aware responses
          default: true
        conversation_timeout_hours:
          type: integer
          description: Hours of inactivity before conversation is considered stale
          default: 24
          minimum: 1
          maximum: 168
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when config was created
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when config was last updated
      required:
      - account_id
      description: 'Per-account AutoReply configuration


        Each account can have its own configuration for rate limiting, response modes, AI settings, user filtering, and delays.
        All fields except account_id are optional and will inherit from global config if not set.'
    PendingDMMessage:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique message queue ID
        account_id:
          type: integer
          description: Account processing this message
        message_id:
          type: string
          description: Twitter DM message ID
        conversation_id:
          type: string
          description: Twitter conversation ID
        sender_id:
          type: string
          description: Sender user ID (as string)
        sender_username:
          type: string
          description: Sender username
        text:
          type: string
          description: Message text content
        received_at:
          type: integer
          format: int64
          description: When message was received (timestamp)
        created_at:
          type: integer
          format: int64
          description: When added to queue (timestamp)
        status:
          type: integer
          description: Processing status (0=PENDING, 1=PROCESSING, 2=COMPLETED, 3=FAILED, 4=SKIPPED)
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
        error_message:
          type: string
          description: Error message if failed
        retry_count:
          type: integer
          description: Number of retry attempts
          default: 0
      description: 'Pending DM message in the processing queue.


        **Status Values:**

        - 0 (PENDING): Waiting to be processed

        - 1 (PROCESSING): Currently being processed

        - 2 (COMPLETED): Successfully replied

        - 3 (FAILED): Failed after max retries

        - 4 (SKIPPED): Skipped (no rule match, cooldown, etc.)'
    BatchOperation:
      type: object
      description: Batch operation summary
      properties:
        id:
          type: integer
          description: Database ID
        batch_id:
          type: integer
          description: Unique batch operation ID
        operation_type:
          type: string
          enum:
          - ADD_TAG
          - REMOVE_TAG
          - CHANGE_PROXY
          - DELETE_ACCOUNTS
          - UNLOCK_ACCOUNT
          - UPDATE_PROFILE
          - FOLLOW_USER
          - UNFOLLOW_USER
          - LIKE_TWEET
          - UNLIKE_TWEET
          - RETWEET
          - UNRETWEET
          - TWEET
          - QUOTE_TWEET
          - REPLY_TWEET
          - TWEET_COMMUNITY
          - JOIN_COMMUNITY
          - LEAVE_COMMUNITY
          - START_FARMING
          - STOP_FARMING
          - REPORT_USER
          - SET_PROTECTED
          - SET_LANGUAGES
          - SEND_MESSAGE
          description: Type of batch operation
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - CANCELLED
          description: Current status of the batch operation
        total_count:
          type: integer
          description: Total number of accounts in the batch
        completed_count:
          type: integer
          description: Number of successfully processed accounts
        failed_count:
          type: integer
          description: Number of failed account operations
        data:
          type: object
          description: Operation-specific parameters
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update
    BatchOperationRequest:
      type: object
      required:
      - operation
      properties:
        operation:
          type: string
          enum:
          - ADD_TAG
          - REMOVE_TAG
          - CHANGE_PROXY
          - DELETE_ACCOUNTS
          - UNLOCK_ACCOUNT
          - UPDATE_PROFILE
          - FOLLOW_USER
          - UNFOLLOW_USER
          - LIKE_TWEET
          - UNLIKE_TWEET
          - RETWEET
          - UNRETWEET
          - TWEET
          - QUOTE_TWEET
          - REPLY_TWEET
          - TWEET_COMMUNITY
          - JOIN_COMMUNITY
          - LEAVE_COMMUNITY
          - START_FARMING
          - STOP_FARMING
          - REPORT_USER
          - SET_PROTECTED
          - SET_LANGUAGES
          - SEND_MESSAGE
          description: Type of operation to perform
        account_ids:
          type: array
          items:
            type: integer
          description: List of account IDs to process (required if select_all is false or missing)
        select_all:
          type: boolean
          default: false
          description: If true, selects all accounts (can be filtered using 'filters' object).
        excluded_ids:
          type: array
          items:
            type: integer
          description: List of account IDs to exclude when select_all is true.
        filters:
          type: object
          description: Account filter criteria (only used when select_all is true). Same filters as GET /accounts endpoint.
          properties:
            filter:
              type: string
              description: Text search filter for username or email
            status:
              type: string
              enum:
              - Active
              - LoginRequired
              - Locked
              - Suspended
              - Invalid
              description: Filter by account status
            tags:
              type: string
              description: Comma-separated list of tags to filter by (OR logic)
            min_followers:
              type: integer
              description: Minimum follower count
            max_followers:
              type: integer
              description: Maximum follower count
            min_following:
              type: integer
              description: Minimum following count
            max_following:
              type: integer
              description: Maximum following count
            min_tweets:
              type: integer
              description: Minimum tweet count
            max_tweets:
              type: integer
              description: Maximum tweet count
            min_account_age:
              type: integer
              description: Minimum account age in days
            is_verified:
              type: boolean
              description: Filter by verified status
            has_profile_pic:
              type: boolean
              description: Filter by whether account has custom profile picture
            has_bio:
              type: boolean
              description: Filter by whether account has bio
        data:
          type: object
          description: 'Operation-specific data:

            - ADD_TAG/REMOVE_TAG: { "tag": "string" }

            - CHANGE_PROXY: { "proxy": "user:pass@host:port" }


            - DELETE_ACCOUNTS: {}

            - UNLOCK_ACCOUNT: {}

            - UPDATE_PROFILE: { "name": "string", "bio": "string", "location": "string", "website": "string", "avatar": "base64_string",
            "banner": "base64_string" }

            - FOLLOW_USER/UNFOLLOW_USER: { "user_id": "string (username or numeric user ID)" }

            - LIKE_TWEET/UNLIKE_TWEET/RETWEET/UNRETWEET: { "tweet_id": "string" }

            - TWEET: { "text": "string" }

            - QUOTE_TWEET: { "text": "string", "tweet_id": "string" }

            - REPLY_TWEET: { "text": "string", "tweet_id": "string" }

            - TWEET_COMMUNITY: { "text": "string", "community_id": "string" }

            - JOIN_COMMUNITY/LEAVE_COMMUNITY: { "community_id": "string" }

            - START_FARMING: { "config": { ...FarmingConfig object... } }

            - STOP_FARMING: {}

            - SET_PROTECTED: { "protected": boolean }

            - SET_LANGUAGES: { "languages": ["en", "tr"], "primary_language": "en" (optional) }

            - SEND_MESSAGE: { "user_id": "string" OR "username": "string", "text": "string", "media_id": "string" (optional)
            } '
        delay_ms:
          type: integer
          minimum: 0
          default: 0
          description: Delay in milliseconds between each operation. Default is 0 (no delay). Useful for rate limiting and
            avoiding detection.
    BatchOperationResponse:
      type: object
      properties:
        batch_id:
          type: integer
          description: Unique batch operation ID
        status:
          type: string
          description: Current status
        total:
          type: integer
          description: Total number of items
        completed:
          type: integer
          description: Number of completed items
        failed:
          type: integer
          description: Number of failed items
        message:
          type: string
          description: Response message
    BatchOperationDetail:
      type: object
      description: Detailed batch operation information with results
      properties:
        batch_id:
          type: integer
          description: Unique batch operation ID
        operation_type:
          type: string
          enum:
          - ADD_TAG
          - REMOVE_TAG
          - CHANGE_PROXY
          - DELETE_ACCOUNTS
          - UNLOCK_ACCOUNT
          - UPDATE_PROFILE
          - FOLLOW_USER
          - UNFOLLOW_USER
          - LIKE_TWEET
          - UNLIKE_TWEET
          - RETWEET
          - UNRETWEET
          - TWEET
          - QUOTE_TWEET
          - REPLY_TWEET
          - TWEET_COMMUNITY
          - JOIN_COMMUNITY
          - LEAVE_COMMUNITY
          - START_FARMING
          - STOP_FARMING
          - REPORT_USER
          - SET_PROTECTED
          - SET_LANGUAGES
          - SEND_MESSAGE
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - CANCELLED
        total_count:
          type: integer
        completed_count:
          type: integer
        failed_count:
          type: integer
        data:
          type: object
          description: Operation parameters
        result:
          type: object
          description: Per-account operation results
          properties:
            completed:
              type: array
              items:
                type: integer
              description: List of account IDs that completed successfully
            failed:
              type: object
              additionalProperties:
                type: string
              description: 'Map of failed account IDs to error messages (e.g. {"123": "Rate limited"})'
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
    StandardSuccessResponse:
      type: object
      description: Standard success response wrapper
      required:
      - success
      - data
      - meta
      properties:
        success:
          type: boolean
          description: Indicates successful operation
          example: true
        data:
          type: object
          description: Response data payload
          additionalProperties: true
        meta:
          $ref: '#/components/schemas/ApiMeta'
        pagination:
          $ref: '#/components/schemas/ApiPagination'
    StandardErrorResponse:
      type: object
      description: Standard error response wrapper
      required:
      - success
      - error
      - meta
      properties:
        success:
          type: boolean
          description: Always false for errors
          example: false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              enum:
              - VALIDATION_ERROR
              - INVALID_PARAMETER
              - MISSING_REQUIRED_FIELD
              - INVALID_FORMAT
              - UNAUTHORIZED
              - TOKEN_EXPIRED
              - TOKEN_INVALID
              - FORBIDDEN
              - INSUFFICIENT_PERMISSIONS
              - RESOURCE_NOT_FOUND
              - ACCOUNT_NOT_FOUND
              - TASK_NOT_FOUND
              - WORKFLOW_NOT_FOUND
              - PROXY_NOT_FOUND
              - TWEET_NOT_FOUND
              - CONFLICT
              - RESOURCE_ALREADY_EXISTS
              - RESOURCE_IN_USE
              - RATE_LIMIT_EXCEEDED
              - INTERNAL_ERROR
              - DATABASE_ERROR
              - EXTERNAL_SERVICE_ERROR
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human-readable error message
              example: Invalid user ID
            details:
              type: array
              description: Additional error details (field-level errors, etc.)
              items:
                type: object
                additionalProperties: true
        meta:
          $ref: '#/components/schemas/ApiMeta'
    ApiMeta:
      type: object
      description: Response metadata
      required:
      - timestamp
      - path
      properties:
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of response
          example: '2025-12-21T03:04:00.123Z'
        path:
          type: string
          description: Request path
          example: /api/v1/data-fetcher/user/123/following
    ApiPagination:
      type: object
      description: Pagination metadata
      properties:
        page:
          type: integer
          description: Current page number (1-indexed)
          minimum: 1
          example: 1
        limit:
          type: integer
          description: Items per page
          minimum: 1
          example: 20
        total:
          type: integer
          description: Total number of items
          minimum: 0
          example: 150
        totalPages:
          type: integer
          description: Total number of pages
          minimum: 0
          example: 8
        hasNext:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPrevious:
          type: boolean
          description: Whether there is a previous page
          example: false
    RateLimit:
      type: object
      properties:
        individual_delay_ms:
          type: integer
          minimum: 0
          description: Delay between individual operations (ms)
        individual_delay_variance_ms:
          type: integer
          minimum: 0
          description: Variance for individual delay randomization (ms)
        bulk_size:
          type: integer
          minimum: 1
          description: Number of operations per bulk
        bulk_delay_ms:
          type: integer
          minimum: 0
          description: Delay between bulks (ms)
        bulk_delay_variance_ms:
          type: integer
          minimum: 0
          description: Variance for bulk delay randomization (ms)
        max_tasks_per_window:
          type: integer
          minimum: 1
          description: Maximum tasks per time window
        time_window_seconds:
          type: integer
          minimum: 1
          description: Time window size (seconds)
    DataFetcherResponse:
      type: object
      description: Data fetcher response wrapper
      properties:
        status:
          type: string
          enum:
          - Success
          - Failed
          - NotFound
          - Protected
          description: Fetch operation status
        tweets_count:
          type: integer
          description: Number of tweets returned
        error_message:
          type: string
          description: Error description (if status is not Success)
        tweets:
          type: array
          items:
            $ref: '#/components/schemas/TweetData'
          description: Array of tweet data (only present if status is Success)
    MessageInboxResponse:
      type: object
      description: Direct message inbox or conversation response
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Array of messages
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
          description: Array of conversations
        users:
          type: array
          items:
            $ref: '#/components/schemas/MessageUser'
          description: Array of users involved in messages
    Message:
      type: object
      description: Direct message data
      properties:
        id:
          type: string
          description: Message unique identifier
        conversation_id:
          type: string
          description: Conversation ID this message belongs to
        time:
          type: integer
          format: int64
          description: Unix timestamp when message was sent
        sender_id:
          type: integer
          format: int64
          description: Sender user ID
        recipient_id:
          type: integer
          format: int64
          description: Recipient user ID
        text:
          type: string
          description: Message text content
        affects_sort:
          type: boolean
          description: Whether this message affects conversation sort order
        request_id:
          type: string
          description: Request ID for tracking
        edit_count:
          type: integer
          description: Number of times message was edited
        attachment:
          $ref: '#/components/schemas/MessageAttachment'
          description: Message attachment (photo, video, etc.)
    MessageAttachment:
      type: object
      description: Message attachment data
      properties:
        photo:
          $ref: '#/components/schemas/MessagePhoto'
          description: Photo attachment
    MessagePhoto:
      type: object
      description: Photo attachment in a message
      properties:
        id:
          type: string
          description: Photo media ID
        id_str:
          type: string
          description: Photo media ID as string
        media_url:
          type: string
          description: HTTP media URL
        media_url_https:
          type: string
          description: HTTPS media URL
        url:
          type: string
          description: Display URL
        display_url:
          type: string
          description: Display URL text
        expanded_url:
          type: string
          description: Expanded URL
        type:
          type: string
          description: Media type (photo, video, etc.)
        original_info:
          $ref: '#/components/schemas/OriginalInfo'
          description: Original image information
        sizes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PhotoSize'
          description: Available size variants (thumb, small, medium, large)
    OriginalInfo:
      type: object
      description: Original image dimensions
      properties:
        width:
          type: integer
          description: Original image width
        height:
          type: integer
          description: Original image height
    PhotoSize:
      type: object
      description: Photo size variant information
      properties:
        w:
          type: integer
          description: Width of this size variant
        h:
          type: integer
          description: Height of this size variant
        resize:
          type: string
          description: Resize method (fit, crop, etc.)
    Conversation:
      type: object
      description: Direct message conversation data
      properties:
        conversation_id:
          type: string
          description: Conversation unique identifier (format recipientId-currentUserId)
        type:
          type: string
          description: Conversation type (ONE_TO_ONE, GROUP_DM, etc.)
        last_message_time:
          type: integer
          format: int64
          description: Unix timestamp of last message
        sort_timestamp:
          type: integer
          format: int64
          description: Timestamp used for sorting conversations
        read_only:
          type: boolean
          description: Whether conversation is read-only
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ConversationParticipant'
          description: Conversation participants
    ConversationParticipant:
      type: object
      description: Participant in a conversation
      properties:
        user_id:
          type: integer
          format: int64
          description: User ID
        last_read_message_id:
          type: string
          description: ID of last message read by this user
    SendMessageResult:
      type: object
      description: Result of sending a direct message
      properties:
        success:
          type: boolean
          description: Whether message was sent successfully
        message_id:
          type: string
          description: ID of sent message
        conversation_id:
          type: string
          description: Conversation ID (format recipientId-currentUserId)
        time:
          type: integer
          format: int64
          description: Unix timestamp when message was sent
        error_message:
          type: string
          description: Error message if send failed
    HttpServerConfiguration:
      type: object
      description: HTTP server configuration
      required:
      - port
      - host
      - cors_enabled
      properties:
        port:
          type: integer
          description: Server listening port
          example: 8080
        host:
          type: string
          description: Server host address
          example: 0.0.0.0
        cors_enabled:
          type: boolean
          description: Whether CORS is enabled
          example: true
        auth_enabled:
          type: boolean
          description: Whether authentication is required
          example: false
        auth_token:
          type: string
          description: Authentication token (if auth enabled)
          example: your-secret-token
    Configuration:
      type: object
      description: Generic configuration wrapper
      properties:
        name:
          type: string
          description: Configuration name/key
          example: proxy
        data:
          type: object
          description: Configuration data (JSON object)
          additionalProperties: true
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when configuration was created
          example: 1704585600
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when configuration was last updated
          example: 1704672000
    Community:
      type: object
      description: Twitter Community information
      properties:
        id:
          type: string
          description: Community unique identifier (rest_id)
          example: '1875614919212556724'
        name:
          type: string
          description: Community name
          example: Tech Enthusiasts
        description:
          type: string
          description: Community description
          example: A community for technology lovers
        role:
          type: string
          description: User's role in community (member, admin, moderator)
          example: member
        is_member:
          type: boolean
          description: Whether current user is a member
          example: true
        member_count:
          type: integer
          description: Total number of community members
          example: 15000
        join_policy:
          type: string
          description: Community join policy (open, request, closed)
          example: open
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when community was created
          example: 1704585600
        is_nsfw:
          type: boolean
          description: Whether community contains NSFW content
          example: false
        primary_topic:
          type: string
          description: Primary topic/category of community
          example: Technology
        creator:
          type: object
          description: Community creator information
          properties:
            user_id:
              type: string
              example: '123456789'
            screen_name:
              type: string
              example: techcreator
        rules:
          type: array
          description: Community rules
          items:
            type: object
            properties:
              name:
                type: string
                example: Be respectful
              description:
                type: string
                example: Treat all members with respect
        trending_hashtags:
          type: array
          description: Trending hashtags in community
          items:
            type: string
            example: '#technology'
        custom_banner_url:
          type: string
          description: URL of custom community banner
          example: https://pbs.twimg.com/...
        default_banner_url:
          type: string
          description: URL of default community banner
          example: https://pbs.twimg.com/...
    UserData:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        screen_name:
          type: string
        name:
          type: string
        bio:
          type: string
        description:
          type: string
        followers_count:
          type: integer
        following_count:
          type: integer
        tweet_count:
          type: integer
        profile_image_url:
          type: string
        profile_banner_url:
          type: string
        following:
          type: boolean
        followed_by:
          type: boolean
        created_at:
          type: string
        location:
          type: string
        is_blue_verified:
          type: boolean
        verified:
          type: boolean
        protected_account:
          type: boolean
        default_profile:
          type: boolean
        default_profile_image:
          type: boolean
        favourites_count:
          type: integer
        listed_count:
          type: integer
        media_count:
          type: integer
        possibly_sensitive:
          type: boolean
        profile_image_shape:
          type: string
        can_dm:
          type: boolean
        can_media_tag:
          type: boolean
        pinned_tweet_ids:
          type: array
          items:
            type: string
        birth_day:
          type: integer
        birth_month:
          type: integer
        birth_year:
          type: integer
        birth_visibility:
          type: string
        birth_year_visibility:
          type: string
        is_identity_verified:
          type: boolean
        can_highlight_tweets:
          type: boolean
        highlighted_tweets:
          type: string
        url:
          type: string
        ntab_unread_count:
          type: integer
        dm_unread_count:
          type: integer
        total_unread_count:
          type: integer
        xchat_unread_count:
          type: integer
        is_from_urt:
          type: boolean
    TweetData:
      type: object
      description: Twitter tweet data structure
      properties:
        id:
          type: string
          description: Tweet unique identifier
        text:
          type: string
          description: Tweet text content
        created_at:
          type: string
          description: Tweet creation timestamp string
        retweet_count:
          type: integer
          description: Number of retweets
        like_count:
          type: integer
          description: Number of likes on the tweet
        reply_count:
          type: integer
          description: Number of replies
        quote_count:
          type: integer
          description: Number of quote tweets
        view_count:
          type: integer
          description: Number of views
        is_retweet:
          type: boolean
          description: Whether this is a retweet
        is_quote:
          type: boolean
          description: Whether this is a quote tweet
        is_reply:
          type: boolean
          description: Whether this is a reply
        quoted_tweet_id:
          type: string
          nullable: true
          description: ID of quoted tweet (null if not a quote)
        replied_to_tweet_id:
          type: string
          nullable: true
          description: ID of tweet being replied to (null if not a reply)
        retweeted_tweet_id:
          type: string
          nullable: true
          description: ID of retweeted tweet (null if not a retweet)
        hashtags:
          type: array
          items:
            type: string
          description: Hashtags in the tweet
        mentions:
          type: array
          items:
            type: string
          description: User mentions in the tweet
        lang:
          type: string
          description: Tweet language code
        source:
          type: string
          description: Source application
        retweeted:
          type: boolean
          description: Whether current user retweeted this tweet
        favorited:
          type: boolean
          description: Whether current user favorited this tweet
        url:
          type: string
          description: URL to the tweet
        author:
          type: object
          nullable: true
          description: Tweet author information
          properties:
            id:
              type: integer
              format: int64
              description: Author user ID
            username:
              type: string
              description: Author username
            screen_name:
              type: string
              description: Author screen name
            name:
              type: string
              description: Author display name
            bio:
              type: string
              description: Author bio
            followers_count:
              type: integer
              description: Author followers count
            following_count:
              type: integer
              description: Author following count
            profile_image_url:
              type: string
              description: Author profile image URL
            is_blue_verified:
              type: boolean
              description: Whether author has blue verification
    MessageUser:
      type: object
      description: User information in DM context
      properties:
        id:
          type: integer
          format: int64
          description: User ID
        screen_name:
          type: string
          description: Username
        name:
          type: string
          description: Display name
        profile_image_url:
          type: string
          description: Profile image URL
        verified:
          type: boolean
          description: Whether user is verified
        is_blue_verified:
          type: boolean
          description: Whether user has blue verification
        protected:
          type: boolean
          description: Whether user account is protected
    MessageUserSearchResponse:
      type: object
      description: User search results for messaging
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/MessageUser'
          description: Array of users matching search query
        num_results:
          type: integer
          description: Number of results returned
    FarmingConfig:
      type: object
      properties:
        likesPerHour:
          type: integer
          description: Number of likes to perform per hour
          default: 10
          minimum: 0
          maximum: 1000
          example: 10
        followsPerHour:
          type: integer
          description: Number of follows to perform per hour
          default: 5
          minimum: 0
          maximum: 1000
          example: 5
        retweetsPerHour:
          type: integer
          description: Number of retweets to perform per hour
          default: 8
          minimum: 0
          maximum: 1000
          example: 8
        suggestedFollowsPerHour:
          type: integer
          description: Number of suggested user follows to perform per hour (from ConnectTab)
          default: 2
          minimum: 0
          maximum: 1000
          example: 2
        aiRepliesPerHour:
          type: integer
          description: Number of AI-powered replies to perform per hour
          default: 3
          minimum: 0
          maximum: 1000
          example: 3
        aiQuotesPerHour:
          type: integer
          description: Number of AI-powered quotes to perform per hour
          default: 2
          minimum: 0
          maximum: 1000
          example: 2
        timelineIntervalMinutes:
          type: integer
          description: Timeline fetch interval in minutes
          default: 10
          minimum: 1
          maximum: 1440
          example: 10
        likesEnabled:
          type: boolean
          description: Enable/disable like actions
          default: true
          example: true
        followsEnabled:
          type: boolean
          description: Enable/disable follow actions
          default: false
          example: false
        retweetsEnabled:
          type: boolean
          description: Enable/disable retweet actions
          default: true
          example: true
        suggestedFollowsEnabled:
          type: boolean
          description: Enable/disable suggested user follows from ConnectTab (Who to follow)
          default: true
          example: true
        aiRepliesEnabled:
          type: boolean
          description: Enable/disable AI-powered replies (requires AI configuration)
          default: false
          example: false
        aiQuotesEnabled:
          type: boolean
          description: Enable/disable AI-powered quotes (requires AI configuration)
          default: false
          example: false
        minActionDelaySeconds:
          type: integer
          description: Minimum delay between actions in seconds
          default: 2
          minimum: 0
          example: 2
        maxActionDelaySeconds:
          type: integer
          description: Maximum delay between actions in seconds
          default: 8
          minimum: 0
          example: 8
        aiReplyInstruction:
          type: string
          description: AI instruction template for generating reply text
          default: Write a thoughtful reply to this tweet
          example: Write a thoughtful reply to this tweet
        aiQuoteInstruction:
          type: string
          description: AI instruction template for generating quote text
          default: Write an engaging quote for this tweet
          example: Write an engaging quote for this tweet
        sleepEnabled:
          type: boolean
          description: Enable sleep/offline hours to simulate real user behavior
          default: true
          example: true
        activeStartHour:
          type: integer
          minimum: 0
          maximum: 23
          description: Hour when account becomes active (0-23, 24h format). Daily random variation will be applied.
          default: 7
          example: 7
        activeEndHour:
          type: integer
          minimum: 0
          maximum: 23
          description: Hour when account becomes inactive (0-23, 24h format). Daily random variation will be applied.
          default: 23
          example: 23
        activeStartMinuteVariation:
          type: integer
          minimum: 0
          maximum: 60
          description: Random minute variation for start time (±X minutes). New random value calculated daily.
          default: 30
          example: 30
        activeEndMinuteVariation:
          type: integer
          minimum: 0
          maximum: 60
          description: Random minute variation for end time (±X minutes). New random value calculated daily.
          default: 30
          example: 30
        keywordFilters:
          type: array
          items:
            type: string
          description: Include tweets containing at least one of these keywords (OR logic, case-insensitive)
          example:
          - bitcoin
          - crypto
          - blockchain
        excludeKeywords:
          type: array
          items:
            type: string
          description: Exclude tweets containing any of these keywords (case-insensitive)
          example:
          - scam
          - airdrop
          - giveaway
        languageFilters:
          type: array
          items:
            type: string
          description: Only interact with tweets in these languages (ISO 639-1 codes). Empty array = all languages
          example:
          - tr
          - en
        requiredHashtags:
          type: array
          items:
            type: string
          description: Tweet must contain ALL of these hashtags (AND logic, case-insensitive)
          example:
          - crypto
        excludedHashtags:
          type: array
          items:
            type: string
          description: Exclude tweets containing any of these hashtags (case-insensitive)
          example:
          - spam
          - bot
        minLikeCount:
          type: integer
          minimum: 0
          description: Minimum number of likes (0 = disabled)
          default: 0
          example: 10
        maxLikeCount:
          type: integer
          minimum: 0
          description: Maximum number of likes (0 = unlimited)
          default: 0
          example: 10000
        minRetweetCount:
          type: integer
          minimum: 0
          description: Minimum number of retweets (0 = disabled)
          default: 0
          example: 5
        maxRetweetCount:
          type: integer
          minimum: 0
          description: Maximum number of retweets (0 = unlimited)
          default: 0
          example: 5000
        minReplyCount:
          type: integer
          minimum: 0
          description: Minimum number of replies (0 = disabled)
          default: 0
          example: 2
        onlyVerifiedUsers:
          type: boolean
          description: Only interact with verified users
          default: false
          example: false
        minFollowerCount:
          type: integer
          minimum: 0
          description: Minimum follower count of tweet author (0 = disabled)
          default: 0
          example: 100
        maxFollowerCount:
          type: integer
          minimum: 0
          description: Maximum follower count of tweet author (0 = unlimited)
          default: 0
          example: 1000000
        requireMedia:
          type: boolean
          description: Only interact with tweets containing media (photos, videos, GIFs)
          default: false
          example: false
        textOnlyTweets:
          type: boolean
          description: Only interact with text-only tweets (no media)
          default: false
          example: false
        maxTweetAgeHours:
          type: integer
          minimum: 0
          description: Maximum tweet age in hours (0 = unlimited)
          default: 0
          example: 24
        skipReplies:
          type: boolean
          description: Skip reply tweets in search results (adds -filter:replies to search query)
          default: false
          example: false
        enableSearchFallback:
          type: boolean
          description: Automatically search Twitter when timeline has no suitable tweets
          default: true
          example: true
        searchFallbackMinKeywords:
          type: integer
          minimum: 1
          description: Minimum number of keywords required for search fallback
          default: 1
          example: 1
        enabled:
          type: boolean
          description: Master enable/disable for farming
          default: true
          example: true
      description: "Farming configuration controls automated engagement activities.\n\n**Rate Limits:**\n- All per-hour values\
        \ must be between 0 and 1000\n- Timeline interval must be between 1 and 1440 minutes (24 hours)\n\n**Action Delays:**\n\
        - minActionDelaySeconds must be less than or equal to maxActionDelaySeconds\n- Random delay between actions will be\
        \ chosen from this range\n\n**Enable/Disable:**\n- Individual actions can be toggled with *Enabled flags\n- Master\
        \ 'enabled' flag controls entire farming system\n\n**AI Features:**\n- AI replies and quotes require AI to be configured\
        \ first\n- Use aiReplyInstruction and aiQuoteInstruction to customize AI behavior\n- AI will generate text in the\
        \ same language as the original tweet\n- Generated text follows strict rules: no hashtags, emojis, symbols, or @ mentions\n\
        - Text length is between 80-200 characters\n\n**Tweet Filtering System:**\nAll filters use AND logic - tweets must\
        \ pass ALL enabled filters to be selected for interaction.\n\n- **Language Filter**: Only interact with tweets in\
        \ specified languages (ISO 639-1: \"tr\", \"en\", etc.)\n- **Keyword Filter**: Include tweets with at least ONE keyword\
        \ (OR), exclude tweets with ANY exclude keyword\n- **Hashtag Filter**: Include tweets with ALL required hashtags (AND),\
        \ exclude tweets with ANY forbidden hashtag\n- **Engagement Filter**: Filter by like/retweet/reply counts (min/max\
        \ ranges)\n- **Author Filter**: Filter by author verification status and follower count ranges\n- **Content Filter**:\
        \ Filter by media presence and tweet age\n- **Search Fallback**: Automatically search Twitter when no suitable tweets\
        \ in timeline\n  - Uses keyword rotation to vary search queries\n  - Only works if keywordFilters is not empty\n\n\
        **Filter Tips:**\n- Empty arrays/0 values = filter disabled\n- Case-insensitive matching for keywords and hashtags\n\
        - Follower count range: use minFollowerCount=100, maxFollowerCount=100000 for mid-tier accounts\n- Language filter\
        \ examples: [\"tr\"] for Turkish only, [\"tr\",\"en\"] for Turkish or English\n- Keyword rotation: Multiple keywords\
        \ will be used in rotation for search fallback\n"
    FarmingSession:
      type: object
      properties:
        id:
          type: integer
          description: Unique session ID
          example: 1
        account_id:
          type: integer
          description: Associated account ID
          example: 1
        username:
          type: string
          description: Twitter account username
          example: exampleuser
        config:
          $ref: '#/components/schemas/FarmingConfig'
        status:
          type: string
          enum:
          - ACTIVE
          - PAUSED
          - STOPPED
          description: Current farming session status
          example: ACTIVE
        started_at:
          type: integer
          format: int64
          description: Unix timestamp when session started
          example: 1704067200
        last_active_at:
          type: integer
          format: int64
          description: Unix timestamp of last activity
          example: 1704070800
        total_duration_seconds:
          type: integer
          description: Total session duration in seconds
          example: 3600
        total_likes:
          type: integer
          description: Total likes performed in this session
          example: 15
        total_follows:
          type: integer
          description: Total follows performed in this session
          example: 8
        total_retweets:
          type: integer
          description: Total retweets performed in this session
          example: 12
        total_replies:
          type: integer
          description: Total AI replies performed in this session
          example: 5
        total_quotes:
          type: integer
          description: Total AI quotes performed in this session
          example: 3
        total_scrolls:
          type: integer
          description: Total timeline scrolls/fetches in this session
          example: 20
        error_count:
          type: integer
          description: Number of errors encountered
          example: 0
        last_error:
          type: string
          description: Last error message (if any)
          example: ''
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when session was created
          example: 1704067200
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when session was last updated
          example: 1704070800
      description: 'Farming session represents an active, paused, or stopped farming instance for an account.


        **Status Values:**

        - **ACTIVE**: Farming is actively running

        - **PAUSED**: Farming is temporarily paused

        - **STOPPED**: Farming has been stopped


        **Statistics:**

        - All counter fields track cumulative totals for the session

        - Counters are persisted to database and survive application restarts

        '
    ProxyInfo:
      type: object
      description: Simplified proxy information for account responses
      properties:
        id:
          type: integer
          description: Proxy unique identifier
        ip:
          type: string
          description: Proxy IP address
        port:
          type: integer
          description: Proxy port number
        type:
          type: string
          enum:
          - HTTP
          - SOCKS5
          description: Proxy protocol type
        status:
          type: string
          enum:
          - NONE
          - CHECKING
          - WORKING
          - NOT_WORKING
          description: Current proxy status
        country:
          type: string
          description: Proxy country name
        country_code:
          type: string
          description: ISO country code
        last_check:
          type: integer
          format: int64
          description: Unix timestamp of last health check
    Proxy:
      type: object
      properties:
        id:
          type: integer
          description: Proxy unique identifier
        username:
          type: string
          description: Proxy authentication username
        password:
          type: string
          description: Proxy authentication password
        ip:
          type: string
          description: Proxy IP address
        port:
          type: integer
          description: Proxy port number
        type:
          type: string
          enum:
          - HTTP
          - SOCKS5
          description: Proxy protocol type
        status:
          type: string
          enum:
          - NONE
          - CHECKING
          - WORKING
          - NOT_WORKING
          description: Current proxy status
        last_check:
          type: integer
          format: int64
          description: Unix timestamp of last health check
        country:
          type: string
          description: Proxy country name
        country_code:
          type: string
          description: ISO country code
        active_accounts:
          type: integer
          description: Number of accounts currently using this proxy
        account_history:
          type: array
          items:
            type: object
            properties:
              username:
                type: string
                description: Account username that used this proxy
              last_used:
                type: integer
                format: int64
                description: Unix timestamp when account last used this proxy
          description: History of accounts that used this proxy
    ProxyRequest:
      type: object
      properties:
        ip:
          type: string
          description: Proxy IP address
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: Proxy port number
        type:
          type: string
          enum:
          - HTTP
          - SOCKS5
          description: Proxy protocol type
        username:
          type: string
          description: Proxy authentication username (optional)
        password:
          type: string
          description: Proxy authentication password (optional)
      required:
      - ip
      - port
      - type
    ProxyConfiguration:
      type: object
      description: Proxy pool management configuration
      required:
      - check_interval
      - max_account_per_proxy
      properties:
        check_interval:
          type: integer
          description: Proxy health check interval in minutes
          example: 30
        max_account_per_proxy:
          type: integer
          description: Maximum accounts per proxy
          example: 5
    RSSPostingConfig:
      type: object
      properties:
        autoPostEnabled:
          type: boolean
          default: false
          description: Enable automatic posting from RSS feeds
        maxPostsPerHour:
          type: integer
          default: 5
          minimum: 0
          maximum: 100
          description: Maximum posts per hour (rate limit)
        minDelayBetweenPosts:
          type: integer
          default: 300
          minimum: 0
          description: Minimum delay between posts in seconds (default 5 minutes)
        actionDelayMin:
          type: integer
          default: 5
          minimum: 0
          description: Minimum action delay in seconds (between multiple RSS fetches)
        actionDelayMax:
          type: integer
          default: 15
          minimum: 0
          description: Maximum action delay in seconds (between multiple RSS fetches)
        tweetTemplate:
          type: string
          default: '{title}


            {link}'
          description: Tweet template with placeholders {title}, {link}, {description}
          example: '{title}


            {link}'
        includeDescription:
          type: boolean
          default: false
          description: Include RSS item description in tweet
        maxDescriptionLength:
          type: integer
          default: 100
          minimum: 0
          maximum: 500
          description: Maximum description length in characters
        shortenLinks:
          type: boolean
          default: false
          description: Shorten links using URL shortener (future feature)
        keywordFilters:
          type: array
          items:
            type: string
          description: Post only items containing these keywords (empty array = post all)
          example:
          - tech
          - AI
          - programming
        excludeKeywords:
          type: array
          items:
            type: string
          description: Skip items containing these keywords
          example:
          - spam
          - ad
        downloadMedia:
          type: boolean
          default: false
          description: Download media from RSS feed (enclosure/media:content)
        attachMedia:
          type: boolean
          default: false
          description: Attach downloaded media to tweets
        checkIntervalSeconds:
          type: integer
          default: 300
          minimum: 60
          description: Feed check interval in seconds (minimum 1 minute)
        enabled:
          type: boolean
          default: true
          description: Enable this configuration
      description: 'RSS Posting Configuration controls automatic RSS-to-Twitter posting behavior.


        **Rate Limits:**

        - maxPostsPerHour must be between 0 and 100

        - minDelayBetweenPosts controls minimum time between consecutive posts


        **Action Delays:**

        - actionDelayMin and actionDelayMax control delays between processing multiple RSS items

        - Random delay is chosen between min and max for natural behavior

        - Applied when multiple RSS feeds are fetched simultaneously


        **Tweet Formatting:**

        - tweetTemplate supports placeholders: {title}, {link}, {description}

        - Tweets are automatically truncated to 280 characters

        - Description can be included and limited by maxDescriptionLength


        **Content Filtering:**

        - keywordFilters: whitelist - only post items with these keywords (empty = all)

        - excludeKeywords: blacklist - skip items with these keywords

        - Filters apply to title, description, and content fields

        '
    SystemStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - healthy
          - warning
          - error
        uptime:
          type: integer
          description: System uptime in seconds
        version:
          type: string
        active_tasks:
          type: integer
        total_accounts:
          type: integer
        working_accounts:
          type: integer
        active_proxies:
          type: integer
        memory_usage:
          type: object
          properties:
            used_mb:
              type: number
            total_mb:
              type: number
    SystemStats:
      type: object
      description: Complete system statistics and health information
      properties:
        proxy:
          type: object
          properties:
            total:
              type: integer
              description: Total number of proxies
            working:
              type: integer
              description: Number of working proxies
            percentage:
              type: number
              format: float
              description: Percentage of working proxies
        account:
          type: object
          properties:
            total:
              type: integer
              description: Total number of accounts
            working:
              type: integer
              description: Number of working accounts
            suspended:
              type: integer
              description: Number of suspended accounts
            invalid:
              type: integer
              description: Number of invalid accounts
            percentage:
              type: number
              format: float
              description: Percentage of working accounts
        tasks:
          type: object
          properties:
            total:
              type: integer
              description: Total number of tasks
            none:
              type: integer
              description: Number of pending tasks
            started:
              type: integer
              description: Number of started tasks
            completed:
              type: integer
              description: Number of completed tasks
            failed:
              type: integer
              description: Number of failed tasks
            cancelled:
              type: integer
              description: Number of cancelled tasks
            paused:
              type: integer
              description: Number of paused tasks
            active:
              type: integer
              description: Number of active tasks (started + paused)
            finished:
              type: integer
              description: Number of finished tasks (completed + failed + cancelled)
        system:
          type: object
          properties:
            healthy:
              type: boolean
              description: Overall system health (working proxies and accounts available)
            proxyHealth:
              type: boolean
              description: Proxy subsystem health
            accountHealth:
              type: boolean
              description: Account subsystem health
            taskHealth:
              type: boolean
              description: Task subsystem health (has running tasks)
        working:
          type: object
          properties:
            proxies:
              type: integer
              description: Number of working proxies
            accounts:
              type: integer
              description: Number of working accounts
            tasks:
              type: integer
              description: Number of active tasks
            systemHealthy:
              type: boolean
              description: Complete system health check
        metadata:
          type: object
          properties:
            timestamp:
              type: integer
              format: int64
              description: Unix timestamp when stats were generated
            version:
              type: string
              description: System version
    Task:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique task identifier
        type:
          type: string
          enum:
          - UNDEFINED
          - FOLLOW
          - LIKE
          - RETWEET
          - TWEET
          - QUOTE
          - REPLY
          description: Task type
        status:
          type: string
          enum:
          - PENDING
          - STARTED
          - COMPLETED
          - FAILED
          - CANCELLED
          - PAUSED
          description: Current task status
        progress:
          type: object
          description: Detailed task progress information
          properties:
            percentage:
              type: number
              format: float
              minimum: 0
              maximum: 100
              description: Task completion percentage (completed + failed / total * 100)
            completed:
              type: integer
              minimum: 0
              description: Number of successfully completed operations
            failed:
              type: integer
              minimum: 0
              description: Number of failed operations
            total:
              type: integer
              minimum: 0
              description: Total number of target operations
        data:
          type: object
          description: Complete task configuration and runtime data (includes all task-specific fields, user management, rate
            limiting, etc.)
        created_at:
          type: integer
          format: int64
          description: Unix timestamp when task was created
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp when task was last updated
      example:
        id: 12345
        type: FOLLOW
        status: STARTED
        progress:
          percentage: 75.5
          completed: 151
          failed: 25
          total: 200
        created_at: 1640995200
        updated_at: 1640998800
        data:
          config:
            mode: USERNAMES
            usernames:
            - user1
            - user2
            - user3
            maxFollowPerTarget: 2
    FollowTaskRequest:
      title: Follow Task
      type: object
      properties:
        type:
          type: string
          enum:
          - FOLLOW
        config:
          type: object
          properties:
            mode:
              type: string
              enum:
              - USERNAMES
              - QUERY
              description: Follow mode - USERNAMES for specific users, QUERY for search results
            usernames:
              type: array
              items:
                type: string
              description: Required for USERNAMES mode - list of usernames to follow
            maxFollowPerTarget:
              type: integer
              minimum: 1
              default: 2
              description: Maximum follows per username target
            searchQuery:
              type: string
              description: Required for QUERY mode - search query to find users
            searchProduct:
              type: string
              enum:
              - Latest
              - Top
              default: Latest
              description: Search product type for QUERY mode
            totalFollowTarget:
              type: integer
              minimum: 1
              default: 50
              description: Total follow target for QUERY mode
        tags:
          type: array
          items:
            type: string
          description: Optional tags for account filtering
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    LikeTaskRequest:
      title: Like Task
      type: object
      properties:
        type:
          type: string
          enum:
          - LIKE
        config:
          type: object
          properties:
            mode:
              type: string
              enum:
              - TWEET_IDS
              - QUERY
              description: Like mode - TWEET_IDS for specific tweets, QUERY for search results
            tweetIds:
              type: array
              items:
                type: string
              description: Required for TWEET_IDS mode - Tweet IDs or URLs
            searchQuery:
              type: string
              description: Required for QUERY mode - search query to find tweets
            searchProduct:
              type: string
              enum:
              - Latest
              - Top
              default: Latest
              description: Search product type for QUERY mode
            likesPerTweet:
              type: integer
              minimum: 1
              default: 1
              description: Number of likes per tweet
            totalLikes:
              type: integer
              minimum: 1
              default: 50
              description: Total likes for QUERY mode
        tags:
          type: array
          items:
            type: string
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    QuoteTaskRequest:
      title: Quote Task
      type: object
      properties:
        type:
          type: string
          enum:
          - QUOTE
        config:
          type: object
          properties:
            mode:
              type: string
              enum:
              - URLS
              - QUERY
              description: Quote mode - URLS for specific tweets, QUERY for search results
            tweetUrls:
              type: array
              items:
                type: string
              description: Required for URLS mode - Tweet URLs or IDs
            searchQuery:
              type: string
              description: Required for QUERY mode - search query to find tweets
            searchProduct:
              type: string
              enum:
              - Latest
              - Top
              default: Latest
              description: Search product type for QUERY mode
            quotesPerTweet:
              type: integer
              minimum: 1
              default: 1
              description: Number of quotes per tweet
            totalQuotes:
              type: integer
              minimum: 1
              default: 50
              description: Total quotes for QUERY mode
            textManager:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      text:
                        type: string
                        description: Quote text content
                      count:
                        type: integer
                        minimum: 1
                        description: Number of times to use this quote text
                  description: Text items for quotes
              description: Text management configuration
        tags:
          type: array
          items:
            type: string
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    ReplyTaskRequest:
      title: Reply Task
      type: object
      properties:
        type:
          type: string
          enum:
          - REPLY
        config:
          type: object
          properties:
            mode:
              type: string
              enum:
              - URLS
              - SEARCH
              description: Reply mode - URLS for specific tweets, SEARCH for search results
            tweetUrls:
              type: array
              items:
                type: string
              description: Required for URLS mode - Tweet URLs or IDs to reply to
            repliesPerTweet:
              type: integer
              minimum: 1
              default: 1
              description: Number of replies per tweet for URLS mode
            searchQuery:
              type: string
              description: Required for SEARCH mode - search query to find tweets
            searchProduct:
              type: string
              enum:
              - Latest
              - Top
              default: Latest
              description: Search product type for SEARCH mode
            maxRepliesPerTweet:
              type: integer
              minimum: 1
              default: 1
              description: Maximum replies per tweet for SEARCH mode
            textManager:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      text:
                        type: string
                        description: Reply text content
                      count:
                        type: integer
                        minimum: 1
                        description: Number of times to use this reply text
                  description: Text items for replies
              description: Text management configuration
            aiEnabled:
              type: boolean
              default: false
              description: Enable AI reply generation
            aiInstruction:
              type: string
              description: AI instruction for reply generation
            aiCount:
              type: integer
              minimum: 1
              default: 1
              description: Number of AI-generated replies per instruction
        tags:
          type: array
          items:
            type: string
          description: Optional tags for account filtering
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    TweetTaskRequest:
      title: Tweet Task
      type: object
      properties:
        type:
          type: string
          enum:
          - TWEET
        config:
          type: object
          properties:
            textManager:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      text:
                        type: string
                        maxLength: 280
                        description: Tweet text content
                      count:
                        type: integer
                        minimum: 1
                        description: Number of times to tweet this text
                  description: Text items for tweets
              description: Text management configuration
            aiEnabled:
              type: boolean
              default: false
              description: Enable AI text generation
            aiInstruction:
              type: string
              description: AI instruction for text generation
            aiCount:
              type: integer
              minimum: 1
              default: 1
              description: Number of AI-generated tweets per instruction
        tags:
          type: array
          items:
            type: string
          description: Optional tags for account filtering
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    RetweetTaskRequest:
      title: Retweet Task
      type: object
      properties:
        type:
          type: string
          enum:
          - RETWEET
        config:
          type: object
          properties:
            mode:
              type: string
              enum:
              - TWEET_IDS
              - QUERY
              description: Retweet mode - TWEET_IDS for specific tweets, QUERY for search results
            tweetIds:
              type: array
              items:
                type: string
              description: Required for TWEET_IDS mode - Tweet IDs or URLs to retweet
            retweetsPerTweet:
              type: integer
              minimum: 1
              default: 1
              description: Number of retweets per tweet
            searchQuery:
              type: string
              description: Required for QUERY mode - search query to find tweets
            searchProduct:
              type: string
              enum:
              - Latest
              - Top
              default: Latest
              description: Search product type for QUERY mode
            totalRetweets:
              type: integer
              minimum: 1
              default: 50
              description: Total retweets for QUERY mode
        tags:
          type: array
          items:
            type: string
          description: Optional tags for account filtering
        rate_limit:
          $ref: '#/components/schemas/RateLimit'
    Workflow:
      type: object
      properties:
        id:
          type: integer
          description: Workflow ID
        name:
          type: string
          description: Workflow name
        description:
          type: string
          description: Workflow description
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - PAUSED
          - COMPLETED
          - FAILED
          - CANCELLED
          description: Current workflow status
        currentStep:
          type: integer
          description: Current step index
        totalSteps:
          type: integer
          description: Total number of steps
        createdAt:
          type: string
          format: date-time
          description: Created timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last updated timestamp
        steps:
          type: array
          description: Workflow steps
          items:
            $ref: '#/components/schemas/WorkflowStep'
    WorkflowStep:
      type: object
      properties:
        type:
          type: string
          enum:
          - DATA_INGEST
          - GET_CLIENT
          - ACTION_EXECUTE
          - CONDITION
          - DELAY
          - ITERATOR
          - AI_GENERATE
          - FETCHER
          - LOGIC_CONTROLLER
          description: Step type
        config:
          type: object
          description: Step-specific configuration
    WorkflowDefinition:
      type: object
      required:
      - name
      - steps
      properties:
        name:
          type: string
          description: Workflow name
        description:
          type: string
          description: Workflow description
        tags:
          type: array
          items:
            type: string
          description: Workflow tags
        steps:
          type: array
          description: Workflow steps
          items:
            type: object
            required:
            - type
            properties:
              type:
                type: string
                description: Step type
              config:
                type: object
                description: Step configuration
      example:
        name: Auto Tweet Workflow
        description: Tweet every 30 minutes
        steps:
        - type: GET_CLIENT
          config:
            selection: RANDOM
            tag: active
        - type: AI_GENERATE
          config:
            type: TWEET
            prompt: Generate an engaging tweet about technology
        - type: ACTION_EXECUTE
          config:
            action: TWEET
            text: '{{ai_generated_text}}'
        - type: DELAY
          config:
            duration_ms: 1800000
    Schedule:
      type: object
      properties:
        id:
          type: integer
          description: Schedule ID
        workflow_id:
          type: integer
          description: Associated workflow ID
        cron_expression:
          type: string
          description: Cron expression (minute hour day month weekday)
          example: 0 12 * * *
        name:
          type: string
          description: Schedule name
        enabled:
          type: boolean
          description: Whether the schedule is enabled
        created_at:
          type: integer
          description: Created timestamp (Unix epoch)
        last_run_at:
          type: integer
          description: Last run timestamp (Unix epoch)
        next_run_at:
          type: integer
          description: Next scheduled run timestamp (Unix epoch)
        run_count:
          type: integer
          description: Number of times this schedule has run
        fail_count:
          type: integer
          description: Number of failed runs