# Обзор Data API

Вызывайте сторонние endpoint'ы через общий префикс, сохраняя единообразную аутентификацию и обработку запросов.

Data API включает Felo и сторонних поставщиков в одном каталоге, в существующих категориях. Вызовы используют баланс платформы; существующие Felo APIs в `/v2` используют кредиты Pro. Общий префикс ниже применяется к сторонним поставщикам; см. [настройка Felo](https://openapi.felo.ai/ru/docs/api-reference/openapi/overview.md) для путей и примеров Felo.
## Общий префикс

```text
https://openapi.felo.ai/v1/beta
```

В справке каждая конечная точка показана как полный путь, начинающийся с `/v1/beta`. Используйте этот путь как есть на хосте; не добавляйте общий префикс повторно. Например, конечная точка поиска Tavily:

```text
POST https://openapi.felo.ai/v1/beta/tavily/search
```

## Найдите конечную точку

- Просматривайте [API directory](https://openapi.felo.ai/ru/apis) по поставщику.
- Откройте [Data API reference](https://openapi.felo.ai/ru/docs/data-api) для полного списка конечных точек, параметров и схем ответов.
- Используйте теги справки для перехода между поставщиками.

У каждого поставщика своя форма запроса. Общий слой стандартизирует аутентификацию и маршрутизацию, а не полезную нагрузку. Перед отправкой запроса прочитайте схему конечной точки.

## Аутентификация

Используйте любой из заголовков:

```http
Authorization: Bearer $FELO_API_KEY
```

или:

```http
X-API-Key: $FELO_API_KEY
```

Отправляйте `Content-Type: application/json` для JSON-тел.

## Пример запроса

```bash
curl https://openapi.felo.ai/v1/beta/tavily/search \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Felo AI?",
    "max_results": 3
  }'
```

Форма ответа задается поставщиком. Такие поля, как результаты, курсоры пагинации и метаданные, не унифицируются между поставщиками.

## Соглашения

| Тема | Чего ожидать |
|-------|----------------|
| Полезная нагрузка | JSON, специфичный для поставщика; следуйте схеме конечной точки |
| Пагинация | Имена полей и стили курсоров различаются в зависимости от конечной точки |
| Ошибки | JSON с `status`, `code`, `message` и `request_id`; детали поставщика могут появляться в сообщении |
| Ограничения частоты | Зависит от конечной точки и поставщика; при нагрузке ожидайте 429 |
| Биллинг | За каждый вызов, из того же баланса сервисных кредитов, что и Model API |

## Обработка ошибок

Сбой аутентификации возвращает ту же оболочку, что и остальная платформа:

```json
{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "..."
}
```

Для сбоя на уровне поставщика читайте HTTP-статус и сообщение. Логируйте метод, полный путь, форму тела запроса и `request_id`. Не логируйте полный API key.

## Повторы

Повторяйте ответы 429 и 5xx с backoff. Не повторяйте 400 или 401 без изменений. Некоторые операции поставщиков небезопасно повторять; проверьте конечную точку перед повтором записи.

## Когда вместо этого использовать Felo API

Используйте Data API, когда вам нужен конкретный сторонний источник данных. Используйте Felo API, когда вам нужен собственный рабочий процесс Felo:

- Ответы с опорой на поиск и цитатами: [Chat API](https://openapi.felo.ai/ru/docs/api-reference/chat.md)
- Генерация слайдов: [PPT Task API](https://openapi.felo.ai/ru/docs/api-reference/ppt-tasks.md)
- Лендинги: [Landing Page Task API](https://openapi.felo.ai/ru/docs/api-reference/landing-page.md)
- Базы знаний и извлечение: [LiveDoc API](https://openapi.felo.ai/ru/docs/api-reference/livedocs.md)
- Разговоры агента с потоковой передачей: [SuperAgent API](https://openapi.felo.ai/ru/docs/api-reference/superagent.md)

## Связанное

- [API directory](https://openapi.felo.ai/ru/apis)
- [Data API reference](https://openapi.felo.ai/ru/docs/data-api)
- [Аутентификация](https://openapi.felo.ai/ru/docs/authentication.md)
- [Ошибки, лимиты и повторы](https://openapi.felo.ai/ru/docs/guides/errors-and-limits.md)
