# PUT /api/v1/progress

Сохранить прогресс одного урока: хотя бы одно из positionSec, completed, homework.

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

## Описание

Сохранить прогресс одного урока: хотя бы одно из `positionSec`, `completed`, `homework`. `completed: true` ставит отметку и сохраняет первую дату завершения при повторе; `false` и отсутствие поля сохраняют отметку. Завершение монотонно. Для закрытого урока нужна анкета. `positionSec` сохраняется с округлением вниз через `Math.floor`: например, `312.5` → `312`.

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

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

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

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

| Поле          | Тип                               | Обязательно | Ограничения  |
| ------------- | --------------------------------- | ----------- | ------------ |
| `lessonId`    | `LessonCode`                      | да          | –            |
| `positionSec` | `number`                          | нет         | ≥ 0; ≤ 86400 |
| `completed`   | `boolean`                         | нет         | true / false |
| `homework`    | `{ text: string, sent: boolean }` | нет         | –            |

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

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

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

Пример JSON с целочисленной сохранённой позицией; значения демонстрационные.

```json
{
  "completed": [
    "pre.1"
  ],
  "positions": {
    "1.1": 312
  },
  "homework": {
    "pre.1": {
      "text": "Создал папку проекта и README.",
      "sent": true
    }
  },
  "milestonesDone": []
}
```

**Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `404 NOT_FOUND`, `403 ONBOARDING_REQUIRED`, `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
{
  "lessonId": "1.1",
  "positionSec": 312.5
}
```

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

```bash
curl -sS -i -X PUT https://aos.edgelab.space/api/v1/progress \
  -H 'Authorization: Bearer aos_live_...' \
  -H 'Origin: https://aos.edgelab.space' \
  -H 'Content-Type: application/json' \
  -d '{"lessonId":"1.1","positionSec":312.5}'
```

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

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

| Статус | Тип | Схема | Описание |
| --- | --- | --- | --- |
| 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, ONBOARDING_REQUIRED |

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