Skip to main content

​
Execution Model

Phonefarm exposes a process-oriented public API, but the underlying runtime is a layered system.

​
The Public Model

For callers, the lifecycle is:
  1. Submit a request.
  2. Receive an accepted response.
  3. Observe process.updated callbacks.
  4. Poll the process record for current state.
  5. Cancel with a process-aware endpoint if needed.

​
The Internal Flow

Under the hood, the flow is: 
public request
  -> capability request row
  -> planned actions
  -> child queue items
  -> claimed work on a phone
  -> isolated run container
  -> executor action(s)
  -> process sync
  -> callback + pollable state

​
Key Objects

TermMeaning
ProcessThe public execution object returned to callers. Backed by capability_requests.
CapabilityA higher-level unit of work such as keyword_warmup or maintenance.
Queue itemAn internal execution record that the worker can claim and run.
Run containerAn isolated worker container for one claimed queue item on one phone.
CallbackA best-effort push notification with normalized process state.

​
Primary Public Entrypoints

Use these for new integrations:
  • POST /capability-requests/enqueue
  • POST /maintenance/requests
  • GET /processes/{process_id}
  • POST /processes/{process_id}/cancel

​
Compatibility Entrypoints

These older endpoints work directly with queue items:
  • POST /ingest
  • POST /cancel
Use them only if you need direct post-video queue-item behavior.

​
Routing Modes

Capability requests accept a target with one routing mode:
Routing modeMeaning
directTarget a specific phone_id and account_id for immediate direct execution readiness.
queueCreate work that will be materialized and claimed later.
groupFan out across explicit phone_ids and or account_ids.
Not every capability supports every routing mode. See Capability Registry.

​
Run Modes

Run modeMeaning
manualAllowed for all currently implemented public capabilities.
unattendedAllowed only for capabilities that are both permitted and live verified.
Important: fyp_warmup is implemented, but the current code still blocks it for unattended usage because it is manual_only, not live_verified.

​
Callbacks Versus Polling

Callbacks are useful for event-driven systems, but they are not the source of truth:
  • callbacks are best-effort
  • callback failure does not fail the originating API request
  • polling GET /processes/{process_id} is the authoritative view