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

# Create capability request

> Create a public process for a supported Phonefarm capability. Omit platform for TikTok; set platform to instagram for Instagram parity actions.



## OpenAPI

````yaml /openapi.json post /capability-requests/enqueue
openapi: 3.1.0
info:
  title: Phonefarm Public API
  description: >-
    Process-first public API for externally triggered Phonefarm execution across
    TikTok and Instagram.
  version: '2026-05-09'
servers:
  - url: https://phonefarm.withmithras.com
security:
  - bearerAuth: []
paths:
  /capability-requests/enqueue:
    post:
      tags:
        - Processes
      summary: Create capability request
      description: >-
        Create a public process for a supported Phonefarm capability. Omit
        platform for TikTok; set platform to instagram for Instagram parity
        actions.
      operationId: createCapabilityRequest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapabilityRequest'
      responses:
        '200':
          description: Duplicate request; existing process returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DuplicateProcess'
        '202':
          description: Process accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedProcess'
        '401':
          description: Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected runtime, environment, or database failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CapabilityRequest:
      oneOf:
        - $ref: '#/components/schemas/AccountCreateCapabilityRequest'
        - $ref: '#/components/schemas/AccountLoginCapabilityRequest'
        - $ref: '#/components/schemas/AccountHealthCheckCapabilityRequest'
        - $ref: '#/components/schemas/AccountDeleteCapabilityRequest'
        - $ref: '#/components/schemas/MaintenanceCapabilityRequest'
        - $ref: '#/components/schemas/KeywordWarmupCapabilityRequest'
        - $ref: '#/components/schemas/FypWarmupCapabilityRequest'
        - $ref: '#/components/schemas/FypCommentGrowthCapabilityRequest'
        - $ref: '#/components/schemas/TargetVideoCommentCapabilityRequest'
        - $ref: '#/components/schemas/TargetAccountLatestCommentCapabilityRequest'
        - $ref: '#/components/schemas/CommentOnVideoCapabilityRequest'
        - $ref: '#/components/schemas/PostVideoCapabilityRequest'
        - e184f027-d965-4991-93c0-ab12e589f8a6
        - $ref: '#/components/schemas/PostStoryCapabilityRequest'
        - $ref: '#/components/schemas/PostHealthCheckCapabilityRequest'
        - $ref: '#/components/schemas/DmSendCapabilityRequest'
        - $ref: '#/components/schemas/DmThreadManageCapabilityRequest'
        - $ref: '#/components/schemas/NotificationTriageCapabilityRequest'
        - $ref: '#/components/schemas/RecoveryCleanupCapabilityRequest'
      discriminator:
        propertyName: capability
        mapping:
          account_create:
            $ref: '#/components/schemas/AccountCreateCapabilityRequest'
          account_login:
            $ref: '#/components/schemas/AccountLoginCapabilityRequest'
          account_health_check:
            $ref: '#/components/schemas/AccountHealthCheckCapabilityRequest'
          account_delete:
            $ref: '#/components/schemas/AccountDeleteCapabilityRequest'
          maintenance:
            $ref: '#/components/schemas/MaintenanceCapabilityRequest'
          keyword_warmup:
            $ref: '#/components/schemas/KeywordWarmupCapabilityRequest'
          fyp_warmup:
            $ref: '#/components/schemas/FypWarmupCapabilityRequest'
          fyp_comment_growth:
            $ref: '#/components/schemas/FypCommentGrowthCapabilityRequest'
          target_video_comment:
            $ref: '#/components/schemas/TargetVideoCommentCapabilityRequest'
          target_account_latest_comment:
            $ref: '#/components/schemas/TargetAccountLatestCommentCapabilityRequest'
          comment_on_video:
            $ref: '#/components/schemas/CommentOnVideoCapabilityRequest'
          post_video:
            $ref: '#/components/schemas/PostVideoCapabilityRequest'
          post_slideshow: '#/components/schemas/PostSlideshowCapabilityRequest'
          post_story:
            $ref: '#/components/schemas/PostStoryCapabilityRequest'
          post_health_check:
            $ref: '#/components/schemas/PostHealthCheckCapabilityRequest'
          dm_send:
            $ref: '#/components/schemas/DmSendCapabilityRequest'
          dm_thread_manage:
            $ref: '#/components/schemas/DmThreadManageCapabilityRequest'
          notification_triage:
            $ref: '#/components/schemas/NotificationTriageCapabilityRequest'
          recovery_cleanup:
            $ref: '#/components/schemas/RecoveryCleanupCapabilityRequest'
      x-phonefarm-platform-support:
        account_create:
          tiktok:
            verification_status: live_verified
            unattended_allowed: true
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        account_login:
          tiktok:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        account_health_check:
          tiktok:
            verification_status: live_verified
            unattended_allowed: true
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        account_delete:
          tiktok:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        maintenance:
          tiktok:
            verification_status: live_verified
            unattended_allowed: true
            supports_direct: false
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: false
            supports_queue: true
            supports_groups: false
        keyword_warmup:
          tiktok:
            verification_status: live_verified
            unattended_allowed: true
            supports_direct: true
            supports_queue: true
            supports_groups: true
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: true
        fyp_warmup:
          tiktok:
            verification_status: live_verified
            unattended_allowed: true
            supports_direct: true
            supports_queue: true
            supports_groups: true
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: true
        fyp_comment_growth:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        target_video_comment:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        target_account_latest_comment:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        comment_on_video:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        post_video:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: true
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: true
        post_slideshow:
          tiktok:
            verification_status: live_verified
            unattended_allowed: true
            supports_direct: true
            supports_queue: true
            supports_groups: false
        post_story:
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        post_health_check:
          tiktok:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        dm_send:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        dm_thread_manage:
          tiktok:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        notification_triage:
          tiktok:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: manual_only
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
        recovery_cleanup:
          tiktok:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
          instagram:
            verification_status: unverified
            unattended_allowed: false
            supports_direct: true
            supports_queue: true
            supports_groups: false
      x-phonefarm-capability-schemas:
        account_create: AccountCreateInputs
        account_login: AccountLoginInputs
        account_health_check: AccountHealthCheckInputs
        account_delete: AccountDeleteInputs
        maintenance: MaintenanceInputs
        keyword_warmup: KeywordWarmupInputs
        fyp_warmup: FypWarmupInputs
        fyp_comment_growth: FypCommentGrowthInputs
        target_video_comment: TargetVideoCommentInputs
        target_account_latest_comment: TargetAccountLatestCommentInputs
        comment_on_video: CommentOnVideoInputs
        post_video: PostVideoInputs
        post_story: PostStoryInputs
        post_health_check: PostHealthCheckInputs
        dm_send: DmSendInputs
        dm_thread_manage: DmThreadManageInputs
        notification_triage: NotificationTriageInputs
        recovery_cleanup: RecoveryCleanupInputs
    DuplicateProcess:
      allOf:
        - $ref: '#/components/schemas/AcceptedProcess'
        - type: object
          properties:
            duplicate:
              type: boolean
              const: true
            process_status:
              $ref: '#/components/schemas/PublicProcessStatus'
          required:
            - duplicate
            - process_status
    AcceptedProcess:
      type: object
      properties:
        status:
          type: string
          const: accepted
        process_id:
          type: string
          format: uuid
        request_id:
          type: string
        process_type:
          type: string
        platform:
          type: string
          enum:
            - tiktok
            - instagram
      required:
        - status
        - process_id
        - request_id
        - process_type
        - platform
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties: true
      required:
        - error
    AccountCreateCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: account_create
            inputs:
              $ref: '#/components/schemas/AccountCreateInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-account-create-2026-06-24-001
          platform: instagram
          capability: account_create
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            desired_account_id: desired_instagram_actor
            workspace_id: workspace_123
            email_alias_env: PHONEFARM_INSTAGRAM_ACCOUNT_CREATE_EMAIL_ALIAS
            password_env: PHONEFARM_INSTAGRAM_ACCOUNT_CREATE_PASSWORD
            email_code_source: auto
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    AccountLoginCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: account_login
            inputs:
              $ref: '#/components/schemas/AccountLoginInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-account-login-2026-06-24-001
          platform: instagram
          capability: account_login
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            login_identifier_env: PHONEFARM_INSTAGRAM_LOGIN_IDENTIFIER
            password_env: PHONEFARM_INSTAGRAM_LOGIN_PASSWORD
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    AccountHealthCheckCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: account_health_check
            inputs:
              $ref: '#/components/schemas/AccountHealthCheckInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-account-health-check-2026-06-24-001
          platform: instagram
          capability: account_health_check
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            checks:
              - session
              - profile
            expected_username: controlled_actor
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    AccountDeleteCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: account_delete
            inputs:
              $ref: '#/components/schemas/AccountDeleteInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-account-delete-2026-06-24-001
          platform: instagram
          capability: account_delete
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            expected_username: controlled_actor
            operation_id: op-delete
            confirm_delete: false
            probe_only: true
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    MaintenanceCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: maintenance
            inputs:
              $ref: '#/components/schemas/MaintenanceInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-maintenance-2026-06-24-001
          platform: instagram
          capability: maintenance
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs: {}
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    KeywordWarmupCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: keyword_warmup
            inputs:
              $ref: '#/components/schemas/KeywordWarmupInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-keyword-warmup-2026-06-24-001
          platform: instagram
          capability: keyword_warmup
          mode: manual
          target:
            routing: direct
            phone_id: phone_01
            account_id: account_instagram_actor
          inputs:
            keywords:
              - healthy dinner ideas
            comment_probability: 0
            dismiss_app_on_finish: true
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    FypWarmupCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: fyp_warmup
            inputs:
              $ref: '#/components/schemas/FypWarmupInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-fyp-warmup-2026-06-24-001
          platform: instagram
          capability: fyp_warmup
          mode: manual
          target:
            routing: direct
            phone_id: phone_01
            account_id: account_instagram_actor
          inputs:
            good_quota: 1
            bad_quota: 1
            max_scans: 4
            like_probability: 0
            save_probability: 0
            comment_probability: 0
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    FypCommentGrowthCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: fyp_comment_growth
            inputs:
              $ref: '#/components/schemas/FypCommentGrowthInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-fyp-comment-growth-2026-06-24-001
          platform: instagram
          capability: fyp_comment_growth
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            target_comment_count: 3
            max_scans: 30
            placement: top_level
            comment_pack:
              - useful
            dynamic_comment_policy: high_fit_only
            dedupe_key: ig:fyp-growth:1
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    TargetVideoCommentCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: target_video_comment
            inputs:
              $ref: '#/components/schemas/TargetVideoCommentInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-target-video-comment-2026-06-24-001
          platform: instagram
          capability: target_video_comment
          mode: manual
          target:
            routing: direct
            phone_id: phone_01
            account_id: account_instagram_actor
          inputs:
            target_video_url: https://www.instagram.com/reel/CONTROLLED/
            text: controlled validation comment
            dedupe_key: ig:reel:controlled
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    TargetAccountLatestCommentCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: target_account_latest_comment
            inputs:
              $ref: '#/components/schemas/TargetAccountLatestCommentInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-target-account-latest-comment-2026-06-24-001
          platform: instagram
          capability: target_account_latest_comment
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            target_account: controlled_target
            text: controlled validation comment
            dedupe_key: ig:latest:controlled
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    CommentOnVideoCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: comment_on_video
            inputs:
              $ref: '#/components/schemas/CommentOnVideoInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-comment-on-video-2026-06-24-001
          platform: instagram
          capability: comment_on_video
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            placement: top_level
            text: controlled validation comment
            dedupe_key: ig:current:controlled
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    PostVideoCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: post_video
            inputs:
              $ref: '#/components/schemas/PostVideoInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-post-video-2026-06-24-001
          platform: instagram
          capability: post_video
          mode: manual
          target:
            routing: direct
            phone_id: phone_01
            account_id: account_instagram_actor
          inputs:
            asset_url: https://assets.example.com/controlled.mp4
            caption: controlled validation caption
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    PostStoryCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: post_story
            inputs:
              $ref: '#/components/schemas/PostStoryInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-post-story-2026-06-24-001
          platform: instagram
          capability: post_story
          mode: manual
          target:
            routing: direct
            phone_id: phone_01
            account_id: account_instagram_actor
          inputs:
            asset_url: https://assets.example.com/controlled-story.jpg
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    PostHealthCheckCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: post_health_check
            inputs:
              $ref: '#/components/schemas/PostHealthCheckInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-post-health-check-2026-06-24-001
          platform: instagram
          capability: post_health_check
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            operation_id: op-post
            expected_caption: controlled validation caption
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    DmSendCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: dm_send
            inputs:
              $ref: '#/components/schemas/DmSendInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-dm-send-2026-06-24-001
          platform: instagram
          capability: dm_send
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            target_handle: controlled_target
            message_text: controlled validation message
            approved_by: ugc-tracker
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    DmThreadManageCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: dm_thread_manage
            inputs:
              $ref: '#/components/schemas/DmThreadManageInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-dm-thread-manage-2026-06-24-001
          platform: instagram
          capability: dm_thread_manage
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            target_handle: controlled_target
            poll_inbox: false
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    NotificationTriageCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: notification_triage
            inputs:
              $ref: '#/components/schemas/NotificationTriageInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-notification-triage-2026-06-24-001
          platform: instagram
          capability: notification_triage
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            surfaces:
              - notifications
            max_items: 20
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    RecoveryCleanupCapabilityRequest:
      allOf:
        - $ref: '#/components/schemas/CapabilityRequestBase'
        - type: object
          properties:
            capability:
              type: string
              const: recovery_cleanup
            inputs:
              $ref: '#/components/schemas/RecoveryCleanupInputs'
          required:
            - capability
            - inputs
      examples:
        - request_id: instagram-recovery-cleanup-2026-06-24-001
          platform: instagram
          capability: recovery_cleanup
          mode: manual
          target:
            routing: queue
            account_id: account_instagram_actor
          inputs:
            cleanup_kind: generic
            expected_account_id: account_instagram_actor
          callback:
            url: https://ugc-tracker.example.com/phonefarm/process-updates
            metadata: {}
          requested_by:
            system: ugc-tracker
            user: operator@example.com
            metadata: {}
    PublicProcessStatus:
      type: string
      enum:
        - queued
        - executing
        - retrying
        - completed
        - failed_terminal
        - cancelled
    CapabilityRequestBase:
      type: object
      properties:
        request_id:
          type: string
          minLength: 1
        platform:
          type: string
          enum:
            - tiktok
            - instagram
          default: tiktok
        mode:
          type: string
          enum:
            - manual
            - unattended
          default: manual
        target:
          $ref: '#/components/schemas/CapabilityTarget'
        callback:
          $ref: '#/components/schemas/Callback'
        requested_by:
          $ref: '#/components/schemas/RequestedBy'
      required:
        - request_id
        - target
        - callback
        - requested_by
    AccountCreateInputs:
      type: object
      properties:
        capability:
          type: string
          const: account_create
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        desired_account_id:
          type: string
          description: Desired-account row or caller id.
        workspace_id:
          type: string
          description: Workspace id for account-create bookkeeping.
        operation_id:
          type: string
          description: Optional linked operation id.
        email_alias:
          type: string
          description: >-
            Controlled signup email alias. Use env refs for Instagram public
            requests.
        email_alias_env:
          type: string
          description: Worker env var that contains the controlled signup email alias.
        username:
          type: string
          description: Requested username when supported by the platform.
        display_name:
          type: string
          description: Requested profile display name.
        password:
          type: string
          description: >-
            Controlled account password. Use password_env for Instagram public
            requests.
        password_env:
          type: string
          description: Worker env var that contains the controlled account password.
        birthdate:
          type: string
          description: Birthdate string accepted by the platform-specific signup runner.
        email_code_source:
          type: string
          description: Verification-code source.
          enum:
            - auto
            - manual
            - gmail
            - composio
        record_state:
          type: boolean
          description: Whether the worker should persist account-create state.
        dry_run:
          type: boolean
          description: Plan without touching the phone.
      required:
        - desired_account_id
        - workspace_id
      additionalProperties: true
      examples:
        - desired_account_id: desired_instagram_actor
          workspace_id: workspace_123
          email_alias_env: PHONEFARM_INSTAGRAM_ACCOUNT_CREATE_EMAIL_ALIAS
          password_env: PHONEFARM_INSTAGRAM_ACCOUNT_CREATE_PASSWORD
          email_code_source: auto
    AccountLoginInputs:
      type: object
      properties:
        capability:
          type: string
          const: account_login
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        login_identifier:
          type: string
          description: >-
            Login email, phone, or username. Use env refs for Instagram public
            requests.
        login_identifier_env:
          type: string
          description: Worker env var that contains the login identifier.
        password:
          type: string
          description: Raw password for non-Instagram local/manual paths.
        password_env:
          type: string
          description: Worker env var that contains the password.
        dry_run:
          type: boolean
          description: Plan without touching the phone.
      additionalProperties: true
      examples:
        - login_identifier_env: PHONEFARM_INSTAGRAM_LOGIN_IDENTIFIER
          password_env: PHONEFARM_INSTAGRAM_LOGIN_PASSWORD
    AccountHealthCheckInputs:
      type: object
      properties:
        capability:
          type: string
          const: account_health_check
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        checks:
          type: array
          items:
            type: string
        signals:
          type: object
          additionalProperties: true
        expected_username:
          type: string
          description: >-
            Optional expected active profile username for Instagram health
            proof.
        dry_run:
          type: boolean
          description: Plan without touching the phone.
      additionalProperties: true
      examples:
        - checks:
            - session
            - profile
          expected_username: controlled_actor
    AccountDeleteInputs:
      type: object
      properties:
        capability:
          type: string
          const: account_delete
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        expected_username:
          type: string
          description: Expected active account before probing/deleting.
        operation_id:
          type: string
          description: Optional linked operation id.
        confirm_delete:
          type: boolean
          description: Must be explicitly true before a destructive delete attempt.
        probe_only:
          type: boolean
          description: Stop at delete entrypoint/checkpoint without deleting.
        record_state:
          type: boolean
          description: Whether the worker should persist account-delete state.
        email_alias:
          type: string
          description: Optional alias for verification-code lookup.
        email_started_after:
          type: string
          description: Optional lower-bound timestamp for verification-code lookup.
        dry_run:
          type: boolean
          description: Plan without touching the phone.
      additionalProperties: true
      examples:
        - expected_username: controlled_actor
          operation_id: op-delete
          confirm_delete: false
          probe_only: true
    MaintenanceInputs:
      type: object
      properties:
        steps:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/MaintenanceStep'
        metadata:
          type: object
          additionalProperties: true
      required:
        - steps
    KeywordWarmupInputs:
      type: object
      properties:
        capability:
          type: string
          const: keyword_warmup
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        keyword:
          type: string
          description: Single search keyword.
        keywords:
          type: array
          items:
            type: string
        videos_per_keyword:
          oneOf:
            - type: integer
              minimum: 1
            - type: array
              items:
                type: integer
                minimum: 1
        videos_min:
          type: integer
          minimum: 0
        videos_max:
          type: integer
          minimum: 1
        interaction_mode:
          type: string
          enum:
            - light
            - smart
            - engaged
        like_probability:
          type: number
          minimum: 0
          maximum: 1
        save_probability:
          type: number
          minimum: 0
          maximum: 1
        comment_probability:
          type: number
          minimum: 0
          maximum: 1
        comment_plan:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        keyword_comment_plan_prompt:
          $ref: '#/components/schemas/PromptObject'
        dismiss_app_on_finish:
          type: boolean
      additionalProperties: true
      examples:
        - keywords:
            - healthy dinner ideas
          comment_probability: 0
          dismiss_app_on_finish: true
    FypWarmupInputs:
      type: object
      properties:
        capability:
          type: string
          const: fyp_warmup
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        good_quota:
          type: integer
          minimum: 0
        bad_quota:
          type: integer
          minimum: 0
        max_scans:
          type: integer
          minimum: 1
        comment_pool:
          type: array
          items:
            type: string
        fyp_profile_override:
          type: object
          additionalProperties: true
        fyp_judge_prompt:
          $ref: '#/components/schemas/PromptObject'
        fyp_comment_pool_prompt:
          $ref: '#/components/schemas/PromptObject'
        like_probability:
          type: number
          minimum: 0
          maximum: 1
        save_probability:
          type: number
          minimum: 0
          maximum: 1
        comment_probability:
          type: number
          minimum: 0
          maximum: 1
        stop_policy:
          type: object
          additionalProperties: true
        dismiss_app_on_finish:
          type: boolean
      required:
        - fyp_judge_prompt
      additionalProperties: true
      examples:
        - good_quota: 1
          bad_quota: 1
          max_scans: 4
          like_probability: 0
          save_probability: 0
          comment_probability: 0
    FypCommentGrowthInputs:
      type: object
      properties:
        capability:
          type: string
          const: fyp_comment_growth
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        target_comment_count:
          type: integer
          minimum: 1
        max_scans:
          type: integer
          minimum: 1
        placement:
          type: string
          enum:
            - top_level
        comment_pack:
          type: array
          items:
            type: string
        fyp_profile_override:
          type: object
          additionalProperties: true
        fyp_judge_prompt:
          $ref: '#/components/schemas/PromptObject'
        fyp_comment_prompt:
          $ref: '#/components/schemas/PromptObject'
        dynamic_comment_policy:
          type: string
          enum:
            - high_fit_only
            - every_good_video
            - pack_only
        dedupe_key:
          type: string
          description: Caller-owned dedupe key for comment attempts.
      required:
        - fyp_judge_prompt
      additionalProperties: true
      examples:
        - target_comment_count: 3
          max_scans: 30
          placement: top_level
          comment_pack:
            - useful
          dynamic_comment_policy: high_fit_only
          dedupe_key: ig:fyp-growth:1
    TargetVideoCommentInputs:
      type: object
      properties:
        capability:
          type: string
          const: target_video_comment
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        target_video_url:
          type: string
          description: Exact TikTok video or Instagram reel/post URL.
        target_url:
          type: string
          description: Alias for target_video_url.
        placement:
          type: string
          enum:
            - top_level
            - reply
        text:
          type: string
          description: Approved comment text.
        comment_pack:
          type: array
          items:
            type: string
        comment_prompt:
          $ref: '#/components/schemas/PromptObject'
        dedupe_key:
          type: string
          description: Caller-owned comment dedupe key.
        reply_target_strategy:
          type: string
          enum:
            - first_visible_reply_button
      required:
        - dedupe_key
      additionalProperties: true
      examples:
        - target_video_url: https://www.instagram.com/reel/CONTROLLED/
          text: controlled validation comment
          dedupe_key: ig:reel:controlled
    TargetAccountLatestCommentInputs:
      type: object
      properties:
        capability:
          type: string
          const: target_account_latest_comment
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        target_account:
          type: string
          description: Target account/handle.
        target:
          type: string
          description: Alias for target_account.
        placement:
          type: string
          enum:
            - top_level
            - reply
        text:
          type: string
          description: Approved comment text.
        comment_pack:
          type: array
          items:
            type: string
        comment_prompt:
          $ref: '#/components/schemas/PromptObject'
        dedupe_key:
          type: string
          description: Caller-owned comment dedupe key.
      required:
        - dedupe_key
      additionalProperties: true
      examples:
        - target_account: controlled_target
          text: controlled validation comment
          dedupe_key: ig:latest:controlled
    CommentOnVideoInputs:
      type: object
      properties:
        capability:
          type: string
          const: comment_on_video
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        placement:
          type: string
          enum:
            - top_level
            - reply
        text:
          type: string
          description: Approved comment text.
        comment_pack:
          type: array
          items:
            type: string
        comment_prompt:
          $ref: '#/components/schemas/PromptObject'
        strategy:
          type: string
        dedupe_key:
          type: string
          description: Caller-owned comment dedupe key.
        close_sheet:
          type: boolean
      required:
        - dedupe_key
      additionalProperties: true
      examples:
        - placement: top_level
          text: controlled validation comment
          dedupe_key: ig:current:controlled
    PostVideoInputs:
      type: object
      properties:
        capability:
          type: string
          const: post_video
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        video:
          type: string
          description: Local path or downloaded asset URL.
        video_path:
          type: string
          description: Alias for video.
        asset_url:
          type: string
          description: HTTP(S) asset URL.
        source_url:
          type: string
          description: Alias for asset_url.
        caption:
          type: string
          description: Caption text.
        dry_run:
          type: boolean
      required:
        - caption
      additionalProperties: true
      examples:
        - asset_url: https://assets.example.com/controlled.mp4
          caption: controlled validation caption
    PostStoryInputs:
      type: object
      properties:
        capability:
          type: string
          const: post_story
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        media:
          type: string
          description: Local path or downloaded media URL.
        video:
          type: string
          description: Video path/URL alias.
        image:
          type: string
          description: Image path/URL alias.
        asset_url:
          type: string
          description: HTTP(S) asset URL.
        source_url:
          type: string
          description: Alias for asset_url.
        dry_run:
          type: boolean
      additionalProperties: true
      examples:
        - asset_url: https://assets.example.com/controlled-story.jpg
    PostHealthCheckInputs:
      type: object
      properties:
        capability:
          type: string
          const: post_health_check
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        check_id:
          type: string
          description: Post-health check row id.
        operation_id:
          type: string
          description: Linked operation id.
        expected_caption:
          type: string
        expected_content_id:
          type: string
        check_after:
          type: string
        dry_run:
          type: boolean
      additionalProperties: true
      examples:
        - operation_id: op-post
          expected_caption: controlled validation caption
    DmSendInputs:
      type: object
      properties:
        capability:
          type: string
          const: dm_send
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        target_handle:
          type: string
          description: Recipient handle.
        message_text:
          type: string
          description: Approved message text.
        display_name:
          type: string
        thread_id:
          type: string
        operation_id:
          type: string
        approval_ref:
          type: object
          additionalProperties: true
        approved_by:
          type: string
        variables:
          type: object
          additionalProperties: true
        dry_run:
          type: boolean
      required:
        - target_handle
        - message_text
      additionalProperties: true
      examples:
        - target_handle: controlled_target
          message_text: controlled validation message
          approved_by: ugc-tracker
    DmThreadManageInputs:
      type: object
      properties:
        capability:
          type: string
          const: dm_thread_manage
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        target_handle:
          type: string
        thread_id:
          type: string
        poll_inbox:
          type: boolean
        reply_operation_id:
          type: string
        inbox_candidate_label:
          type: string
        dry_run:
          type: boolean
      additionalProperties: true
      examples:
        - target_handle: controlled_target
          poll_inbox: false
    NotificationTriageInputs:
      type: object
      properties:
        capability:
          type: string
          const: notification_triage
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        surfaces:
          type: array
          items:
            type: string
        max_items:
          type: integer
          minimum: 1
        target_ref:
          type: object
          additionalProperties: true
        dry_run:
          type: boolean
      additionalProperties: true
      examples:
        - surfaces:
            - notifications
          max_items: 20
    RecoveryCleanupInputs:
      type: object
      properties:
        capability:
          type: string
          const: recovery_cleanup
          description: >-
            Optional documentation hint; request capability remains the source
            of truth.
        cleanup_kind:
          type: string
          enum:
            - generic
            - upload
            - comment_sheet
            - dm_composer
            - wrong_account
        surface:
          type: string
        expected_account_id:
          type: string
        dry_run:
          type: boolean
      additionalProperties: true
      examples:
        - cleanup_kind: generic
          expected_account_id: account_instagram_actor
    CapabilityTarget:
      type: object
      properties:
        routing:
          type: string
          enum:
            - direct
            - queue
            - group
          default: direct
        phone_id:
          type:
            - string
            - 'null'
        account_id:
          type:
            - string
            - 'null'
        phone_group:
          type:
            - string
            - 'null'
        account_group:
          type:
            - string
            - 'null'
        phone_ids:
          type: array
          items:
            type: string
        account_ids:
          type: array
          items:
            type: string
      required:
        - routing
    Callback:
      type: object
      properties:
        url:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties: true
      required:
        - url
    RequestedBy:
      type: object
      properties:
        system:
          type: string
          minLength: 1
        user:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
      required:
        - system
    MaintenanceStep:
      type: object
      properties:
        action:
          type: string
          enum:
            - edit_profile
        params:
          type: object
          additionalProperties: true
      required:
        - action
        - params
    PromptObject:
      type: object
      properties:
        prompt_id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        system_prompt:
          type: string
          minLength: 1
        task_prompt:
          type: string
          minLength: 1
        output_contract:
          type: object
          additionalProperties: true
        examples:
          type: array
          items: {}
        metadata:
          type: object
          additionalProperties: true
      required:
        - prompt_id
        - name
        - version
        - system_prompt
        - task_prompt
        - output_contract
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-default: PHONEFARM_API_KEY

````