Capability Requests

Use POST /capability-requests/enqueue to create a public process for a supported capability.

POST /capability-requests/enqueue

When To Use It

Use this endpoint when you want the process-oriented public API for:

account_create
account_login
account_health_check
account_delete
maintenance
keyword_warmup
fyp_warmup
fyp_comment_growth
target_video_comment
target_account_latest_comment
comment_on_video
post_video
post_slideshow
post_story
post_health_check
dm_send
dm_thread_manage
notification_triage
recovery_cleanup

For the primary public maintenance path, use POST /maintenance/requests. Omit platform for the default TikTok execution path. Set "platform": "instagram" to request Instagram parity; the Edge planner preserves TikTok action names and prefixes planned Instagram executor actions with instagram_.

Request Example

curl -X POST "$PHONEFARM_BASE_URL/capability-requests/enqueue" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "warmup-2026-03-22-001",
    "platform": "instagram",
    "capability": "keyword_warmup",
    "mode": "manual",
    "target": {
      "routing": "direct",
      "phone_id": "phone_01",
      "account_id": "account_user095916355"
    },
    "inputs": {
      "keywords": ["healthy dinner ideas", "meal prep"],
      "videos_per_keyword": 2,
      "interaction_mode": "smart",
      "comment_probability": 0,
      "dismiss_app_on_finish": true
    },
    "callback": {
      "url": "https://ugc-tracker.example.com/phonefarm/process-updates",
      "metadata": {
        "environment": "production"
      }
    },
    "requested_by": {
      "system": "ugc-tracker",
      "user": "operator@example.com",
      "metadata": {}
    }
  }'

Accepted Response

{
  "status": "accepted",
  "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
  "request_id": "warmup-2026-03-22-001",
  "process_type": "keyword_warmup",
  "platform": "instagram"
}

For queued Instagram login, pass executor-side env var names instead of raw credentials. The worker resolves these immediately before invoking instagram_account_login; request and queue rows store the env var names plus non-secret metadata, not the password value. Queued Instagram account_login and account_create requests with raw password, login_identifier, or email_alias values are rejected before persistence.

{
  "request_id": "instagram-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": {}
  }
}

Duplicate Response

{
  "status": "accepted",
  "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
  "request_id": "warmup-2026-03-22-001",
  "process_type": "keyword_warmup",
  "platform": "instagram",
  "duplicate": true,
  "process_status": "queued"
}

Request Fields

Field	Type	Required	Notes
`request_id`	string	yes	Caller-generated idempotency key component.
`platform`	string	no	`tiktok` or `instagram`. Defaults to `tiktok` for backward compatibility.
`capability`	string	yes	Public Edge API accepts the capabilities listed above.
`mode`	string	yes	`manual` or `unattended`.
`target`	object	yes	Routing and execution target configuration.
`inputs`	object	yes	Capability-specific payload.
`callback`	object	yes	Outbound callback target and metadata.
`requested_by`	object	yes	Caller identity and metadata.

Shared Objects

`target`

Field	Type	Required	Notes
`routing`	string	yes	`direct`, `queue`, or `group`.
`phone_id`	string or null	no	Used for direct targeting.
`account_id`	string or null	no	Used for direct targeting.
`phone_group`	string or null	no	Reserved target grouping field.
`account_group`	string or null	no	Reserved target grouping field.
`phone_ids`	string[]	no	Required by current `group` routing behavior when used.
`account_ids`	string[]	no	Required by current `group` routing behavior when used.

At least one target identifier must be present.

`callback`

Field	Type	Required	Notes
`url`	string	yes	Must be a valid `http(s)` URL.
`metadata`	object	no	Free-form caller metadata. Defaults to `{}`.

`requested_by`

Field	Type	Required	Notes
`system`	string	yes	Stable caller system identifier.
`user`	string or null	no	Operator or user identifier.
`metadata`	object	no	Free-form caller metadata. Defaults to `{}`.

Supported Modes and Routing

Capability	Manual	Unattended	Direct	Queue	Group

| account_create | yes | yes | yes | yes | no | | account_login | yes | no | yes | yes | no | | account_health_check | yes | yes | yes | yes | no | | account_delete | yes | no | yes | yes | no | | maintenance | yes | yes | no | yes | no | | keyword_warmup | yes | yes | yes | yes | yes | | fyp_warmup | yes | yes | yes | yes | yes | | fyp_comment_growth | yes | no | yes | yes | no | | target_video_comment | yes | no | yes | yes | no | | target_account_latest_comment | yes | no | yes | yes | no | | comment_on_video | yes | no | yes | yes | no | | post_video | yes | no | yes | yes | yes | | post_slideshow | yes | yes | yes | yes | no | | post_health_check | yes | no | yes | yes | no | | dm_send | yes | no | yes | yes | no | | dm_thread_manage | yes | no | yes | yes | no | | notification_triage | yes | no | yes | yes | no | | recovery_cleanup | yes | no | yes | yes | no | The table shows default TikTok routing. For platform: "instagram", keyword_warmup and fyp_warmup currently remain manual-only and are blocked for unattended execution until the Instagram wrappers are live-verified on the OnePlus validation path.

Instagram Modes and Routing

Capability	Manual	Unattended	Direct	Queue	Group

| account_create | yes | no | yes | yes | no | | account_login | yes | no | yes | yes | no | | account_health_check | yes | no | yes | yes | no | | account_delete | yes | no | yes | yes | no | | maintenance | yes | no | no | yes | no | | keyword_warmup | yes | no | yes | yes | yes | | fyp_warmup | yes | no | yes | yes | yes | | fyp_comment_growth | yes | no | yes | yes | no | | target_video_comment | yes | no | yes | yes | no | | target_account_latest_comment | yes | no | yes | yes | no | | comment_on_video | yes | no | yes | yes | no | | post_video | yes | no | yes | yes | yes | | post_story | yes | no | yes | yes | no | | post_health_check | yes | no | yes | yes | no | | dm_send | yes | no | yes | yes | no | | dm_thread_manage | yes | no | yes | yes | no | | notification_triage | yes | no | yes | yes | no | | recovery_cleanup | yes | no | yes | yes | no |

FYP Comment Growth Inputs

fyp_comment_growth scans the For You feed, judges video fit with the supplied prompt, and posts strict top-level comments on selected videos.

{
  "target_comment_count": 3,
  "max_scans": 30,
  "placement": "top_level",
  "comment_pack": ["this is worth noticing"],
  "fyp_judge_prompt": {
    "prompt_id": "ugc.fyp.judge.relationship.v1",
    "name": "FYP Judge Relationship V1",
    "version": "1",
    "system_prompt": "You are judging TikTok FYP fit.",
    "task_prompt": "Return a strict yes/no fit judgement.",
    "output_contract": {
      "type": "json_object"
    }
  },
  "dynamic_comment_policy": "high_fit_only"
}

Required behavior today:

placement must be top_level; reply placement is rejected.
fyp_judge_prompt is required.
Comment text must come from either comment_pack or fyp_comment_prompt.
dynamic_comment_policy must be high_fit_only, every_good_video, or pack_only.
mode: "unattended" is rejected until the capability is live verified.

Comment wrappers such as comment_on_video, target_account_latest_comment, and target_video_comment are now accepted public capabilities for manual execution.

Prompt Object Shape

Warmup capabilities use structured prompt objects when runtime reasoning is needed.

{
  "prompt_id": "ugc.fyp.judge.relationship.v1",
  "name": "FYP Judge Relationship V1",
  "version": "1",
  "system_prompt": "You are judging TikTok FYP warmup fit.",
  "task_prompt": "Return yes only for target-fit content ...",
  "output_contract": {
    "type": "json_object"
  },
  "examples": [],
  "metadata": {
    "source": "ugc_tracker"
  }
}

Required fields:

prompt_id
name
version
system_prompt
task_prompt
output_contract

Idempotency

Idempotency key:

(platform, process_type, requested_by.system, request_id)

If the same key is reused, Phonefarm returns the existing process instead of creating a new one.

Failure Modes

Typical validation failures include:

unknown capability
unknown platform
unsupported routing mode for a capability
unattended mode blocked for that capability
unattended FYP warmup engagement probability missing or nonzero
missing required prompt objects
invalid target shape

The current implementation uses string-based validation messages. Treat them as descriptive errors, not as a versioned error-code contract unless your integration explicitly pins to them.

What Happens Next

After acceptance:

Phonefarm persists a public process row.
Phonefarm attempts an immediate process.updated callback with milestone accepted.
Worker orchestration materializes planned actions into queue items.
You poll GET /processes/{process_id} for source-of-truth state.

Getting Started

Concepts

API

OpenAPI Reference

Guides

Reference

Capability Requests

Capability Requests

When To Use It

Request Example

Accepted Response

Duplicate Response

Request Fields

Shared Objects

`target`

`callback`

`requested_by`

Supported Modes and Routing

Instagram Modes and Routing

FYP Comment Growth Inputs

Prompt Object Shape

Idempotency

Failure Modes

What Happens Next

Read Next

​Capability Requests

​When To Use It

​Request Example

​Accepted Response

​Instagram Login Example

​Duplicate Response

​Request Fields

​Shared Objects

​target

​callback

​requested_by

​Supported Modes and Routing

​Instagram Modes and Routing

​FYP Comment Growth Inputs

​Prompt Object Shape

​Idempotency

​Failure Modes

​What Happens Next

​Read Next

Capability Requests

When To Use It

Request Example

Accepted Response

Instagram Login Example

Duplicate Response

Request Fields

Shared Objects

`target`

`callback`

`requested_by`

Supported Modes and Routing

Instagram Modes and Routing

FYP Comment Growth Inputs

Prompt Object Shape

Idempotency

Failure Modes

What Happens Next

Read Next