Skip to main content

​
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:
  • keyword_warmup
  • fyp_warmup
  • advanced compatibility use of maintenance
For the primary public maintenance path, use POST /maintenance/requests.

​
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",
    "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"
}

​
Duplicate Response

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

​
Request Fields

FieldTypeRequiredNotes
request_idstringyesCaller-generated idempotency key component.
capabilitystringyeskeyword_warmup, fyp_warmup, or maintenance.
modestringyesmanual or unattended.
targetobjectyesRouting and execution target configuration.
inputsobjectyesCapability-specific payload.
callbackobjectyesOutbound callback target and metadata.
requested_byobjectyesCaller identity and metadata.

​
Shared Objects

​
target

FieldTypeRequiredNotes
routingstringyesdirect, queue, or group.
phone_idstring or nullnoUsed for direct targeting.
account_idstring or nullnoUsed for direct targeting.
phone_groupstring or nullnoReserved target grouping field.
account_groupstring or nullnoReserved target grouping field.
phone_idsstring[]noRequired by current group routing behavior when used.
account_idsstring[]noRequired by current group routing behavior when used.
At least one target identifier must be present.

​
callback

FieldTypeRequiredNotes
urlstringyesMust be a valid http(s) URL.
metadataobjectnoFree-form caller metadata. Defaults to {}.

​
requested_by

FieldTypeRequiredNotes
systemstringyesStable caller system identifier.
userstring or nullnoOperator or user identifier.
metadataobjectnoFree-form caller metadata. Defaults to {}.

​
Supported Modes and Routing

CapabilityManualUnattendedDirectQueueGroup
keyword_warmupyesyesyesyesyes
fyp_warmupyesnoyesyesyes
maintenanceyesnonoyesno

​
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: 
(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
  • unsupported routing mode for a capability
  • unattended mode blocked for that capability
  • 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.