> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tweet-catcher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Task

> Creates a new monitoring task for the authenticated account

Set **`start: true`** to activate the task immediately after creation
Omitting it (or passing `false`) leaves the task in a stopped state, you can start it later with `/start-task`

The `module` field defaults to `twitter` when omitted
For keyword monitoring use `module: "twitter_keyword"` and supply a `keyword` instead of a `user`



## OpenAPI

````yaml /api-specification.yaml post /add-task
openapi: 3.0.3
info:
  title: Tweet Catcher Monitor API
  description: API for managing Tweet Catcher monitoring tasks and user data
  version: 1.0.0
  contact:
    name: Tweet Catcher
    url: https://dashboard.tweet-catcher.com/support
servers:
  - url: https://monitor-api.tweet-catcher.com/pro
    description: Production server
security:
  - ApiKeyToken: []
tags:
  - name: Manage Tasks
    description: Operations for managing Tweet Catcher monitoring tasks
  - name: User Data
    description: Operations for retrieving user-related data and history
paths:
  /add-task:
    post:
      tags:
        - Manage Tasks
      summary: Add Task
      description: >-
        Creates a new monitoring task for the authenticated account


        Set **`start: true`** to activate the task immediately after creation

        Omitting it (or passing `false`) leaves the task in a stopped state, you
        can start it later with `/start-task`


        The `module` field defaults to `twitter` when omitted

        For keyword monitoring use `module: "twitter_keyword"` and supply a
        `keyword` instead of a `user`
      operationId: addTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                module:
                  type: string
                  enum:
                    - twitter
                    - truth_social
                    - twitter_keyword
                  default: twitter
                  description: Platform module to monitor
                  example: twitter
                user:
                  type: string
                  description: Username to monitor (not applicable for keyword tasks)
                  example: Gioppooo
                keyword:
                  type: string
                  description: Keyword to monitor (used by twitter_keyword module)
                  example: bitcoin
                group:
                  type: string
                  description: Task group for organization
                  example: influencers
                options:
                  type: array
                  items:
                    type: string
                    enum:
                      - posts
                      - retweets
                      - replies
                      - deletion
                      - following
                      - unfollow
                      - userUpdates
                      - ocr
                      - subscriptions
                      - private
                    description: Monitoring option
                    example: posts
                  default:
                    - posts
                  description: Monitoring options
                  example:
                    - ocr
                    - posts
                    - retweets
                    - replies
                notification:
                  type: string
                  enum:
                    - discord
                    - telegram
                    - webhook
                    - websocket
                  default: discord
                  description: Notification method
                  example: discord
                differentWebhooks:
                  type: boolean
                  default: false
                  description: >-
                    Whether to use different webhooks/chat IDs per monitoring
                    option
                  example: false
                webhook:
                  type: string
                  description: Discord webhook URL or custom webhook URL
                  example: https://discord.com/api/webhooks/...
                webhook-posts:
                  type: string
                  description: Webhook for posts (if differentWebhooks is true)
                webhook-following:
                  type: string
                  description: Webhook for following updates (if differentWebhooks is true)
                webhook-unfollow:
                  type: string
                  description: Webhook for unfollow updates (if differentWebhooks is true)
                webhook-userUpdates:
                  type: string
                  description: Webhook for user updates (if differentWebhooks is true)
                webhook-deletion:
                  type: string
                  description: Webhook for deletion updates (if differentWebhooks is true)
                chatId:
                  type: string
                  description: Telegram chat ID
                  example: '123456789'
                chatId-posts:
                  type: string
                  description: Telegram chat ID for posts (if differentWebhooks is true)
                chatId-following:
                  type: string
                  description: >-
                    Telegram chat ID for following updates (if differentWebhooks
                    is true)
                chatId-unfollow:
                  type: string
                  description: >-
                    Telegram chat ID for unfollow updates (if differentWebhooks
                    is true)
                chatId-userUpdates:
                  type: string
                  description: >-
                    Telegram chat ID for user updates (if differentWebhooks is
                    true)
                chatId-deletion:
                  type: string
                  description: >-
                    Telegram chat ID for deletion updates (if differentWebhooks
                    is true)
                pingKeywords:
                  type: object
                  properties:
                    'n':
                      type: array
                      items:
                        type: string
                      default: []
                      description: Negative keywords that suppress pings
                      example:
                        - raffle
                    p:
                      type: array
                      items:
                        type: string
                      default: []
                      description: Positive keywords that trigger pings
                      example:
                        - mint
                        - launch
                    regex:
                      type: string
                      description: Regex pattern used for ping matching
                      example: (mint|launch)
                    isRegex:
                      type: boolean
                      default: false
                      description: Whether regex matching is enabled
                      example: false
                  description: Keywords or regex configuration used for selective pinging
                  example:
                    'n':
                      - test
                    p:
                      - alpha
                    isRegex: false
                useRegex:
                  type: boolean
                  default: false
                  description: Whether to use regex for ping keywords
                  example: false
                ping:
                  type: string
                  enum:
                    - everyone
                    - here
                    - role
                    - none
                  default: none
                  description: Discord ping option
                  example: everyone
                roleId:
                  type: string
                  description: Discord role ID to ping (required if ping is role)
                  example: '123456789012345678'
                note:
                  type: string
                  description: Task note shown in notifications
                  example: high priority profile
                quickLink:
                  type: string
                  description: Custom quick link included in notifications
                  example: https://x.com/Gioppooo
                ignoreImages:
                  type: boolean
                  default: false
                  description: Whether to ignore images in notifications
                  example: false
                ignoreVideos:
                  type: boolean
                  default: false
                  description: Whether to ignore videos in notifications
                  example: false
                followingFilters:
                  type: object
                  properties:
                    followingMinPosts:
                      type: number
                      nullable: true
                      description: Minimum posts count filter
                      example: 10
                    followingMaxPosts:
                      type: number
                      nullable: true
                      description: Maximum posts count filter
                      example: 50000
                    followingMinFollowers:
                      type: number
                      nullable: true
                      description: Minimum followers count filter
                      example: 500
                    followingMaxFollowers:
                      type: number
                      nullable: true
                      description: Maximum followers count filter
                      example: 1000000
                    followingMinFollowing:
                      type: number
                      nullable: true
                      description: Minimum following count filter
                      example: 10
                    followingMaxFollowing:
                      type: number
                      nullable: true
                      description: Maximum following count filter
                      example: 10000
                  description: >-
                    Filters for following notifications (typically used with
                    Discord and Telegram notifications)
                userUpdatesOptions:
                  type: object
                  properties:
                    disableUsernameUpdate:
                      type: boolean
                      default: false
                      description: Disable username change notifications
                      example: false
                    disableNameUpdate:
                      type: boolean
                      default: false
                      description: Disable display name change notifications
                      example: false
                    disableAvatarUpdate:
                      type: boolean
                      default: false
                      description: Disable avatar change notifications
                      example: false
                    disableBannerUpdate:
                      type: boolean
                      default: false
                      description: Disable banner change notifications
                      example: false
                    disableLocationUpdate:
                      type: boolean
                      default: false
                      description: Disable location change notifications
                      example: false
                    disableDescriptionUpdate:
                      type: boolean
                      default: false
                      description: Disable bio/description change notifications
                      example: false
                    disableWebsiteUpdate:
                      type: boolean
                      default: false
                      description: Disable website change notifications
                      example: false
                    disablePinnedTweetUpdate:
                      type: boolean
                      default: false
                      description: Disable pinned tweet change notifications
                      example: false
                    disableVerificationUpdate:
                      type: boolean
                      default: false
                      description: Disable verification badge change notifications
                      example: false
                  description: >-
                    Options for user update notifications (typically used with
                    Discord and Telegram notifications)
                start:
                  type: boolean
                  description: Whether to automatically start the task after creation
                  example: true
            examples:
              discord_task:
                summary: Discord notification task
                value:
                  user: gioppooo
                  options:
                    - posts
                    - retweets
                  notification: discord
                  webhook: https://discord.com/api/webhooks/...
                  ping: everyone
                  start: true
              websocket_task:
                summary: WebSocket notification task
                value:
                  user: gioppooo
                  options:
                    - following
                  notification: websocket
                  start: true
              telegram_task:
                summary: Telegram notification task
                value:
                  user: username
                  options:
                    - posts
                    - replies
                  notification: telegram
                  chatId: '123456789'
                  start: false
              keyword_task:
                summary: Keyword monitoring task
                value:
                  module: twitter_keyword
                  keyword: bitcoin
                  notification: websocket
                  start: true
      responses:
        '200':
          description: Task created successfully, the response includes the new task ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                    example: false
                    description: Whether an error occurred
                  id:
                    type: number
                    example: 932
                    description: Created task ID
                required:
                  - error
                  - id
              example:
                error: false
                id: 932
        '400':
          description: >-
            Invalid or incomplete request body (e.g. missing `user`/`keyword`,
            unknown module, task limit reached)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                    example: true
                    description: Whether an error occurred
                  message:
                    type: string
                    example: Error message
                    description: The error message
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      email:
                        - Invalid module
                    description: The errors
                required:
                  - error
                  - message
              example:
                error: true
                message: Invalid request parameters
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                    example: true
                    description: Whether an error occurred
                  message:
                    type: string
                    example: Error message
                    description: The error message
                required:
                  - error
                  - message
              example:
                error: true
                message: Invalid or missing authorization token
        '500':
          description: Unexpected server error
      security:
        - ApiKeyToken: []
components:
  securitySchemes:
    ApiKeyToken:
      type: apiKey
      in: header
      name: Authorization
      description: Api key for application authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.