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

# Runtime Snapshots

> Sync account runtime and strategy state from an upstream system.

# Runtime Snapshots

Use `POST /runtime-snapshots/upsert` to synchronize account runtime-strategy state into Phonefarm.

```http theme={null}
POST /runtime-snapshots/upsert
```

This is a configuration-sync endpoint, not an execution-dispatch endpoint.

## Request Example

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

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

```json theme={null}
{
  "status": "ignored_stale",
  "account_id": "account_user095916355",
  "snapshot_id": "snapshot-2026-03-22-001",
  "strategy_version": 6
}
```

## Request Fields

| Field                | Type           | Required | Notes                              |
| -------------------- | -------------- | -------- | ---------------------------------- |
| `account_id`         | string         | yes      | Active Phonefarm account id.       |
| `ugc_account_id`     | string         | yes      | Upstream UGC Tracker account id.   |
| `snapshot_id`        | string         | yes      | Upstream snapshot id.              |
| `strategy_version`   | integer        | yes      | Positive integer strategy version. |
| `content_hash`       | string         | yes      | Caller-provided content hash.      |
| `strategy_synced_at` | string         | yes      | ISO-8601 timestamp.                |
| `stage`              | string or null | no       | Free-form current stage label.     |
| `active_action`      | string or null | no       | Free-form current action label.    |
| `active_skills`      | string\[]      | no       | Optional active skills list.       |
| `personality`        | object         | yes      | Strategy/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 code | Meaning                              |
| ----------- | ------------------------------------ |
| `401`       | Missing or invalid bearer token.     |
| `404`       | Account not found or inactive.       |
| `422`       | Invalid payload or timestamp format. |
| `500`       | Unexpected update failure.           |

## Read Next

* [Capability Requests](./capability-requests)
* [Execution Model](../concepts/execution-model)