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

# Maintenance Requests

> Create account-first maintenance processes.

# Maintenance Requests

Use `POST /maintenance/requests` to create a maintenance process targeted at a specific account. Omit `platform` for the default TikTok path, or set `"platform": "instagram"` for Instagram profile maintenance.

```http theme={null}
POST /maintenance/requests
```

## When To Use It

Use this endpoint when you need account maintenance work such as profile editing.

This is the recommended public maintenance entrypoint.

## Current Supported Step

The current implementation supports one maintenance action:

* `edit_profile`

## Request Example

```bash theme={null}
curl -X POST "$PHONEFARM_BASE_URL/maintenance/requests" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "maint-2026-03-22-001",
    "platform": "instagram",
    "account_id": "account_user095916355",
    "inputs": {
      "steps": [
        {
          "action": "edit_profile",
          "params": {
            "display_name": "weekday meals",
            "bio": "quick dinners and meal prep",
            "mutation_kind": "operator_requested",
            "randomized": false
          }
        }
      ],
      "metadata": {
        "source": "ugc-tracker"
      }
    },
    "callback": {
      "url": "https://ugc-tracker.example.com/phonefarm/process-updates",
      "metadata": {
        "environment": "production"
      }
    },
    "requested_by": {
      "system": "ugc-tracker",
      "user": "operator@example.com",
      "metadata": {}
    }
  }'
```

## Accepted Response

```json theme={null}
{
  "status": "accepted",
  "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
  "request_id": "maint-2026-03-22-001",
  "process_type": "maintenance",
  "platform": "instagram"
}
```

## Request Fields

| Field          | Type   | Required | Notes                                                                     |
| -------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `request_id`   | string | yes      | Caller-generated idempotency key component.                               |
| `platform`     | string | no       | `tiktok` or `instagram`. Defaults to `tiktok` for backward compatibility. |
| `account_id`   | string | yes      | Target account id. Must resolve to an active account.                     |
| `inputs`       | object | yes      | Contains `steps` and optional metadata.                                   |
| `callback`     | object | yes      | Callback destination and metadata.                                        |
| `requested_by` | object | yes      | Caller identity.                                                          |

## `inputs.steps[]`

| Field    | Type   | Required | Notes                                             |
| -------- | ------ | -------- | ------------------------------------------------- |
| `action` | string | yes      | Must currently be `edit_profile`.                 |
| `params` | object | yes      | At least one supported profile field is required. |

Supported `edit_profile.params` fields:

* `display_name`
* `bio`
* `username`
* `mutation_kind`
* `randomized`

At least one of `display_name`, `bio`, or `username` must be present.

## Idempotency

Idempotency key:

```text theme={null}
(platform, process_type, requested_by.system, request_id)
```

Duplicate requests return the existing process.

## Advanced Compatibility Note

The lower-level capability contract also knows about a `maintenance` capability. Public docs treat `POST /maintenance/requests` as the canonical maintenance route.

## Failure Modes

| Status code | Meaning                                                |
| ----------- | ------------------------------------------------------ |
| `401`       | Missing or invalid bearer token.                       |
| `404`       | Account not found or inactive.                         |
| `422`       | Invalid request structure or unsupported step payload. |
| `500`       | Unexpected enqueue failure.                            |

## Read Next

* [Maintenance Guide](../guides/maintenance)
* [Get Process](./processes-get)
* [Cancel Process](./processes-cancel)