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

# Quickstart

> Send your first process request, verify callbacks, and poll for status.

# 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

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

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

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

```json theme={null}
{
  "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](./guides/webhooks) for verification examples.

## 4. Poll for Source-of-Truth Status

```bash theme={null}
curl "$PHONEFARM_BASE_URL/processes/3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY"
```

Example response:

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

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

## Read Next

* [Execution Model](./concepts/execution-model)
* [Process Lifecycle](./concepts/process-lifecycle)
* [Capability Requests](./api/capability-requests)