Skip to main content

​
Runtime Snapshots

Use POST /runtime-snapshots/upsert to synchronize account runtime-strategy state into Phonefarm. 
POST /runtime-snapshots/upsert
This is a configuration-sync endpoint, not an execution-dispatch endpoint.

​
Request Example

curl -X POST "$PHONEFARM_BASE_URL/runtime-snapshots/upsert" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "account_user095916355",
    "ugc_account_id": "ugc_123",
    "snapshot_id": "snapshot-2026-03-22-001",
    "strategy_version": 7,
    "content_hash": "sha256:abc123",
    "strategy_synced_at": "2026-03-22T08:30:00.000Z",
    "stage": "warmup",
    "active_action": "keyword_warmup",
    "active_skills": ["warmup", "commenting"],
    "personality": {
      "comment_style": "casual, validating",
      "interests": ["healthy recipes", "meal prep"]
    }
  }'

​
Success Responses

Applied update: 
{
  "status": "upserted",
  "account_id": "account_user095916355",
  "snapshot_id": "snapshot-2026-03-22-001",
  "strategy_version": 7,
  "strategy_synced_at": "2026-03-22T08:30:00.000Z"
}
Ignored stale update: 
{
  "status": "ignored_stale",
  "account_id": "account_user095916355",
  "snapshot_id": "snapshot-2026-03-22-001",
  "strategy_version": 6
}

​
Request Fields

FieldTypeRequiredNotes
account_idstringyesActive Phonefarm account id.
ugc_account_idstringyesUpstream UGC Tracker account id.
snapshot_idstringyesUpstream snapshot id.
strategy_versionintegeryesPositive integer strategy version.
content_hashstringyesCaller-provided content hash.
strategy_synced_atstringyesISO-8601 timestamp.
stagestring or nullnoFree-form current stage label.
active_actionstring or nullnoFree-form current action label.
active_skillsstring[]noOptional active skills list.
personalityobjectyesStrategy/personality object.

​
Stale Update Rules

Phonefarm ignores incoming snapshots when:
  • stored strategy_version is greater than the incoming version
  • or versions match and stored strategy_synced_at is newer than the incoming timestamp

​
Failure Modes

Status codeMeaning
401Missing or invalid bearer token.
404Account not found or inactive.
422Invalid payload or timestamp format.
500Unexpected update failure.