# Web Fetch API

Витягуйте вміст вебсторінок як HTML, текст або Markdown із параметрами селектора й readability.

Ця сторінка документує наявні `/v2` Felo APIs, які використовують **права облікового запису Felo та правила Pro-кредитів**. Чи будуть списані кредити, залежить від [операції](https://openapi.felo.ai/uk/docs/faq/billing-and-credits.md#v2). Для викликів із балансу платформи обирайте підтримувану [кінцеву точку Felo OpenAPI](https://openapi.felo.ai/uk/docs/api-reference/openapi/overview.md); форми запиту й відповіді можуть відрізнятися.

Web Fetch API витягує вміст із цільового URL і повертає результат у форматі, який легше обробляти агентам, системам RAG і робочим процесам контенту. Він може повертати HTML, звичайний текст або Markdown, а також підтримує селектори, параметри readability, керування кешем, користувацькі user agent і cookies запиту.

## Кінцева точка

```http
POST https://openapi.felo.ai/v2/web/extract
```

## Автентифікація

Надішліть свій API key у заголовку `Authorization`:

```http
Authorization: Bearer YOUR_API_KEY
```

Докладніше про створення та керування API keys дивіться в [Посібнику з автентифікації](https://openapi.felo.ai/uk/docs/authentication.md).

## Використання з AI Agents

Встановіть повний пакет `felo-ai`, якщо хочете, щоб Agent витягував вебсторінки разом з усіма іншими доступними Felo Skills. Інсталятор динамічно виявляє кожен каталог пакета, що містить `SKILL.md`, тому він ніколи не спирається на фіксований список. Встановлюйте всі виявлені Skills у Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills` або Hermes Agent `~/.hermes/skills`. Використовуйте [посібник із ручного налаштування AI Agent](https://openapi.felo.ai/uk/docs/felo-skills.md) для безпечного встановлення й кроків із API key для кожної платформи.

## Запит

### Заголовки

| Заголовок | Обов’язковий | Опис |
|--------|----------|-------------|
| `Authorization` | Так | Ваш API key у форматі `Bearer YOUR_API_KEY` |
| `Content-Type` | Так | Має бути `application/json` |

### Параметри тіла

| Параметр | Тип | Обов’язковий | За замовчуванням | Опис |
|-----------|------|----------|---------|-------------|
| `url` | string | Так | - | URL вебсторінки для витягування. |
| `crawl_mode` | string | Ні | `fast` | Режим витягування. Використовуйте `fast` для швидшого отримання або `fine` для точнішого обходу, який може краще обробляти складніші сторінки. |
| `output_format` | string | Ні | `html` | Формат виводу. Підтримувані значення: `html`, `text`, `markdown`. |
| `with_readability` | boolean or string | Ні | - | Увімкнути обробку readability, щоб зосередитися на основному вмісті й зменшити шум сторінки. |
| `with_links_summary` | boolean | Ні | - | Додати підсумок посилань, коли це підтримується downstream-витягувачем. |
| `with_images_summary` | boolean | Ні | - | Додати підсумок зображень, коли це підтримується. |
| `with_images_readability` | boolean | Ні | - | Застосувати обробку readability до витягування зображень, коли це підтримується. |
| `with_images` | boolean | Ні | - | Додати інформацію про зображення до витягнутого результату. |
| `with_links` | boolean | Ні | - | Додати інформацію про посилання до витягнутого результату. |
| `ignore_empty_text_image` | boolean | Ні | - | Ігнорувати зображення, які не містять корисного тексту, коли це підтримується. |
| `target_selector` | string | Ні | - | CSS-селектор цільового елемента для витягування, наприклад `article.main-content`. |
| `wait_for_selector` | string | Ні | - | Чекати, доки з’явиться CSS-селектор, перед витягуванням. Корисно для сторінок із динамічним рендерингом. |
| `set_cookies` | array | Ні | - | Cookies, які слід надіслати разом із запитом на витягування. |
| `user_agent` | string | Ні | - | Користувацький рядок User-Agent для запиту на витягування. |
| `timeout` | integer | Ні | - | Тайм-аут запиту в мілісекундах. |
| `with_cache` | boolean | Ні | `true` | Чи може downstream-витягувач використовувати кеш. |
| `with_stypes` | boolean | Ні | `false` | Додати метадані типів стилів, коли це підтримується. |

## Відповідь

### Успішна відповідь

Відповідь використовує прозорий дизайн pass-through. Точні поля всередині `data` можуть відрізнятися залежно від `output_format` та інших параметрів витягування.

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "example-request-id",
  "data": {
    "content": "# Example Article\n\nExtracted article content..."
  }
}
```

### Поля відповіді

| Поле | Тип | Опис |
|-------|------|-------------|
| `status` | integer | Статус у стилі HTTP, `200` при успіху. |
| `code` | string | `OK` при успіху. |
| `message` | string or null | Додаткове повідомлення. Зазвичай `null` для успішних запитів. |
| `data` | object | Витягнутий вміст і метадані, повернуті downstream-сервісом витягування. |
| `data.content` | string or object | Витягнутий вміст. Форма залежить від `output_format` і вибраних параметрів. |

## Відповіді з помилками

| HTTP-статус | Код помилки | Опис | Рекомендована дія |
|-------------|------------|-------------|------------------|
| 400 | `WEB_EXTRACT_FAILED` | Не пройшла перевірка запиту, URL недійсний або downstream-витягувач повернув помилку клієнтського рівня. | Перевірте `url`, селектори та параметри запиту. |
| 401 | `UNAUTHORIZED` | API key відсутній, недійсний або відкликаний. | Перевірте API key і заголовок авторизації. |
| 500 | `WEB_EXTRACT_FAILED` | Внутрішня помилка сервісу. | Повторіть запит. Якщо проблема зберігається, зверніться до підтримки. |

## Приклади

### Базове витягування

```bash
curl -X POST https://openapi.felo.ai/v2/web/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'
```

### Витягування Markdown з Readability

```bash
curl -X POST https://openapi.felo.ai/v2/web/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "output_format": "markdown",
    "with_readability": true
  }'
```

### Витягування конкретного CSS-селектора

```bash
curl -X POST https://openapi.felo.ai/v2/web/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "target_selector": "article.main-content",
    "output_format": "text"
  }'
```

### Очікування динамічного вмісту

```bash
curl -X POST https://openapi.felo.ai/v2/web/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/app",
    "crawl_mode": "fine",
    "wait_for_selector": "#loaded-content",
    "output_format": "markdown",
    "timeout": 30000
  }'
```

## Випадки використання

- Надати агенту контекст вебсторінки перед відповіддю на запитання.
- Витягнути текст статті для завантаження в RAG або створення бази знань.
- Перетворити вебсторінки на Markdown для архівування чи документаційних робочих процесів.
- Витягти сфокусований вміст зі сторінки за допомогою CSS-селекторів.
- Зменшити шум сторінки за допомогою обробки readability перед downstream AI-аналізом.

## Примітки

- API обробляє один URL на запит.
- `data` передається від downstream-сервісу витягування, тому з часом можуть з’являтися додаткові поля.
- Режим `fine` може бути повільнішим за `fast`, але може бути корисним, коли сторінка потребує складнішої поведінки рендерингу.
- Деякі сторінки можуть блокувати витягування, вимагати cookies або користувацький `user_agent`.
