# PUT /api/v1/plan/milestones

Заменить набор выполненных шагов плана.

| Поле | Значение |
| --- | --- |
| URL | `PUT https://aos.edgelab.space/api/v1/plan/milestones` |
| Доступ | Cookie кабинета · Mini App (TMA) · API-ключ / OAuth |
| Scope для ключей | `progress:write` |
| operationId | `planMilestonesPut` |

## Описание

Заменить весь набор отметок опубликованного плана. Повтор идемпотентен. Индексы от нуля, уникальны, должны существовать в текущем плане; без опубликованного плана – 404. Отметки привязаны к версии плана: при новой версии набор пустой. `expectedVersion` – положительная версия из GET plan. Несовпадение проверяется под lock публикации до записи → 409 VERSION_CONFLICT, текущий план не меняется. REST и MCP используют общий обработчик.

**Auth:** сессия кабинета (cookie) / TMA bearer / API-ключ или OAuth access token. **Scope:** `progress:write` (для ключей).

**Path:** параметров нет.

**Query:** нет объявленных полей.

**Body:** `application/json`, [PlanMilestonesUpdateRequest](/docs/schemas#planmilestonesupdaterequest). Все вложенные поля и варианты – по ссылке.

| Поле             | Тип           | Обязательно | Ограничения |
| ---------------- | ------------- | ----------- | ----------- |
| `expectedVersion` | `integer` | да | > 0; просмотренная версия плана |
| `milestonesDone` | `(integer)[]` | да          | –           |

**Ответ · статус и структура**

**Ответ:** 200 `application/json`, [Progress](/docs/schemas#progress).

Краткая форма: `{ completed: (LessonCode)[], positions: Record<string, number>, homework: Record<string, object>, milestonesDone: (integer)[] }`.

**Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `404 NOT_FOUND`, `409 VERSION_CONFLICT`, `403 CREDENTIAL_NOT_ALLOWED`, `403 INSUFFICIENT_SCOPE`; [общие ошибки](/docs/errors).

**Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student.

**Запрос · JSON**

```json
{
  "expectedVersion": 1,
  "milestonesDone": [
    0,
    1
  ]
}
```

**Пример · curl**

```bash
curl -sS -i -X PUT https://aos.edgelab.space/api/v1/plan/milestones \
  -H 'Authorization: Bearer aos_live_...' \
  -H 'Origin: https://aos.edgelab.space' \
  -H 'Content-Type: application/json' \
  -d '{"milestonesDone":[0,1],"expectedVersion":1}'
```

## Ответы по контракту

Тело запроса: [PlanMilestonesUpdateRequest](/docs/schemas#planmilestonesupdaterequest).

| Статус | Тип | Схема | Описание |
| --- | --- | --- | --- |
| 200 | application/json | [Progress](/docs/schemas#progress) | Успех |
| ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, NOT_FOUND, VERSION_CONFLICT |

Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `planMilestonesPut`.
