Skip to main content

​
Quickstart

This guide uses the process-first public API. It creates a keyword_warmup request, receives a signed callback, and polls the normalized process record.

​
Before You Start

You need:
  • A shared bearer secret configured in Phonefarm as INGEST_SECRET.
  • A reachable callback URL if you want push updates.
  • A valid account_id and phone_id or another valid routing target.

​
1. Set Environment Variables

export PHONEFARM_BASE_URL="https://phonefarm.withmithras.com"
export PHONEFARM_API_KEY="<shared bearer secret>"
export CALLBACK_URL="https://ugc-tracker.example.com/phonefarm/process-updates"

​
2. Create a Process

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": {}
    }
  }'
Expected response: 
{
  "status": "accepted",
  "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
  "request_id": "warmup-2026-03-22-001",
  "process_type": "keyword_warmup"
}

​
3. Verify the Accepted Callback

Phonefarm immediately attempts a process.updated callback with milestone accepted. Callback payload shape: 
{
  "event_type": "process.updated",
  "milestone": "accepted",
  "emitted_at": "2026-03-22T08:30:00.000Z",
  "process": {
    "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
    "process_type": "keyword_warmup",
    "request_id": "warmup-2026-03-22-001",
    "status": "queued"
  }
}
If PHONE_FARM_WEBHOOK_SECRET is configured, Phonefarm signs the callback with:
  • X-PhoneFarm-Timestamp
  • X-PhoneFarm-Signature
See Webhooks for verification examples.

​
4. Poll for Source-of-Truth Status

curl "$PHONEFARM_BASE_URL/processes/3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY"
Example response: 
{
  "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
  "process_type": "keyword_warmup",
  "request_id": "warmup-2026-03-22-001",
  "status": "executing",
  "target": {
    "account_id": "account_user095916355",
    "phone_id": "phone_01"
  },
  "requested_by": {
    "system": "ugc-tracker",
    "user": "operator@example.com",
    "metadata": {}
  },
  "callback": {
    "url": "https://ugc-tracker.example.com/phonefarm/process-updates",
    "metadata": {
      "environment": "production"
    }
  },
  "result": {},
  "error": null,
  "timestamps": {
    "created_at": "2026-03-22T08:30:00.000Z",
    "accepted_at": "2026-03-22T08:30:00.000Z",
    "queued_at": "2026-03-22T08:30:00.000Z",
    "executing_at": "2026-03-22T08:31:10.000Z",
    "retrying_at": null,
    "cancel_requested_at": null,
    "finished_at": null
  },
  "linked_ids": {
    "queue_item_ids": ["7c1a07f6-1d55-4f79-a403-8a8420f1b62b"],
    "completed_queue_item_ids": []
  },
  "partial_progress": {}
}

​
5. Cancel If Needed

curl -X POST "$PHONEFARM_BASE_URL/processes/3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870/cancel" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "operator requested stop",
    "strategy": "soft_then_force",
    "force_after_seconds": 10,
    "requested_by": {
      "system": "ugc-tracker",
      "user": "operator@example.com",
      "metadata": {}
    }
  }'