> ## 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.

# Capability Requests

> Create public process records for supported Phonefarm capabilities.

# Capability Requests

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

```http theme={null}
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`](./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

```bash theme={null}
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

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

## Instagram Login Example

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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```text theme={null}
(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:

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

## Read Next

* [Get Process](./processes-get)
* [Keyword Warmup Guide](../guides/keyword-warmup)
* [FYP Warmup Guide](../guides/fyp-warmup)
* [FYP Comment Growth Guide](../guides/fyp-comment-growth)