# GET /api/v1/search

Полнотекстовый поиск по транскриптам и таймкодам уроков/эфиров с применением gating.

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

## Описание

Полнотекстовый поиск по транскриптам и таймкодам уроков/эфиров с применением gating. `q` 2–200 символов после trim, `limit` 1–20 (default 10); результаты содержат источники/таймкоды. Конспекты уроков в поиск не входят.

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

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

**Query:**

| Поле    | Тип       | Обязательно | Ограничения            |
| ------- | --------- | ----------- | ---------------------- |
| `q`     | `string`  | да          | длина ≥ 2; длина ≤ 200 |
| `limit` | `integer` | нет         | ≥ 1; ≤ 20              |

**Body:** не требуется.

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

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

Краткая форма: `{ query: string, results: (object)[] }`.

Пример JSON; значения демонстрационные.

```json
{
  "query": "тьютор",
  "results": [
    {
      "label": "Урок 1.1 · 05:10",
      "lesson": "1.1",
      "seconds": 310,
      "title": "Тестовый урок: как устроен кабинет и тьютор",
      "snippet": "Тьютор отвечает по материалам курса и ставит ссылку на минуту урока."
    }
  ]
}
```

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

**Лимиты:** Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода.

```bash
curl -sS -i 'https://aos.edgelab.space/api/v1/search?q=MCP&limit=5' \
  -H 'Authorization: Bearer aos_live_...'
```

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

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

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