> ## Documentation Index
> Fetch the complete documentation index at: https://web2md.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Программное преобразование любого URL или HTML в Markdown

## Обзор

REST API Web2MD позволяет программно преобразовывать любую веб-страницу или необработанный HTML в чистый Markdown. Используйте его для построения пайплайнов, автоматизации сбора контента или интеграции Web2MD в собственные инструменты.

<Note>
  Для использования REST API требуется тариф **PRO**. Создайте API-ключ в [панели управления Web2MD](https://web2md.org/dashboard/api-keys).
</Note>

### Машиночитаемые спецификации

| Ресурс                   | URL                                                                            | Описание                                               |
| ------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
| Спецификация OpenAPI 3.1 | [`/api/v1/openapi.json`](https://web2md.org/api/v1/openapi.json)               | Полная схема API для генерации кода и инструментов     |
| Манифест AI-плагина      | [`/.well-known/ai-plugin.json`](https://web2md.org/.well-known/ai-plugin.json) | Обнаружение агентами (ChatGPT Plugins / AI-ассистенты) |

Используйте спецификацию OpenAPI для автоматической генерации клиентских SDK или импорта в такие инструменты, как Postman, Swagger UI или фреймворки AI-агентов.

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

Каждый запрос должен содержать ваш API-ключ в заголовке `Authorization`:

```
Authorization: Bearer w2m_your_key_here
```

API-ключи начинаются с префикса `w2m_` и привязаны к вашему аккаунту.

## Эндпоинт

<Card>
  <strong>POST</strong> `https://web2md.org/api/v1/convert`
</Card>

### Тело запроса

| Поле      | Тип      | Обязательность           | Описание                                      |
| --------- | -------- | ------------------------ | --------------------------------------------- |
| `url`     | `string` | Одно из `url` или `html` | URL страницы для преобразования               |
| `html`    | `string` | Одно из `url` или `html` | Необработанная HTML-строка для преобразования |
| `options` | `object` | Нет                      | Параметры преобразования (см. ниже)           |

<Warning>
  Указывайте либо `url`, либо `html`, но не оба одновременно. Запрос завершится ошибкой `400`, если указаны оба поля или ни одно из них.
</Warning>

### Параметры

| Поле            | Тип       | По умолчанию | Описание                                                           |
| --------------- | --------- | ------------ | ------------------------------------------------------------------ |
| `includeImages` | `boolean` | `true`       | Включать ссылки на изображения в результат                         |
| `includeLinks`  | `boolean` | `true`       | Сохранять гиперссылки в результате                                 |
| `includeMeta`   | `boolean` | `true`       | Добавлять метаданные страницы в начало в формате YAML front matter |

### Ответ

Успешный ответ возвращает:

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "# Page Title\n\nConverted content...",
    "metadata": {
      "title": "Page Title",
      "url": "https://example.com/article",
      "extractedAt": "2026-03-22T10:30:00.000Z",
      "wordCount": 1250,
      "tokenCount": 1680,
      "readingTime": 5,
      "author": "Jane Doe",
      "publishedDate": "2026-03-20",
      "description": "A brief summary extracted from the page meta tags."
    }
  }
}
```

| Поле            | Тип       | Описание                                                 |
| --------------- | --------- | -------------------------------------------------------- |
| `title`         | `string`  | Заголовок страницы, извлечённый из `<title>`             |
| `url`           | `string`  | Исходный URL (если был указан)                           |
| `extractedAt`   | `string`  | Временная метка преобразования в формате ISO 8601        |
| `wordCount`     | `integer` | Общее количество слов (английские слова + иероглифы CJK) |
| `tokenCount`    | `integer` | Оценочное количество токенов LLM                         |
| `readingTime`   | `integer` | Оценочное время чтения в минутах                         |
| `author`        | `string?` | Имя автора из мета-тегов или JSON-LD                     |
| `publishedDate` | `string?` | Дата публикации (ГГГГ-ММ-ДД)                             |
| `description`   | `string?` | Описание страницы из Open Graph или мета-тегов           |

## Лимиты запросов

Запросы к API ограничены **60 запросами в минуту** на один API-ключ. При превышении лимита API возвращает код состояния `429`. Дождитесь окна сброса лимита перед повторной попыткой.

## Ответы с ошибками

| Статус | Значение                                                     | Пример                                                    |
| ------ | ------------------------------------------------------------ | --------------------------------------------------------- |
| `400`  | Некорректный запрос — отсутствующие или конфликтующие данные | Указаны и `url`, и `html`, либо не указано ни одно из них |
| `401`  | Не авторизован — неверный или отсутствующий API-ключ         | Отсутствует заголовок `Authorization`                     |
| `422`  | Невозможно обработать — не удалось получить URL              | Целевой сайт вернул ошибку или превышено время ожидания   |
| `429`  | Превышен лимит запросов                                      | Более 60 запросов за одну минуту                          |
| `500`  | Внутренняя ошибка сервера                                    | Непредвиденный сбой на нашей стороне                      |

Все ответы с ошибками имеют следующую структуру:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}
```

## Примеры

### Преобразование URL с помощью curl

```bash theme={null}
curl -X POST https://web2md.org/api/v1/convert \
  -H "Authorization: Bearer w2m_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "options": {
      "includeImages": true,
      "includeLinks": true,
      "includeMeta": false
    }
  }'
```

### Преобразование необработанного HTML с помощью curl

```bash theme={null}
curl -X POST https://web2md.org/api/v1/convert \
  -H "Authorization: Bearer w2m_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Hello World</h1><p>This is a <strong>test</strong> paragraph.</p>"
  }'
```

### JavaScript (fetch)

```javascript theme={null}
const response = await fetch("https://web2md.org/api/v1/convert", {
  method: "POST",
  headers: {
    "Authorization": "Bearer w2m_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/blog/post",
    options: {
      includeImages: true,
      includeLinks: true,
    },
  }),
});

const result = await response.json();

if (result.success) {
  console.log(result.data.markdown);
  console.log(`Word count: ${result.data.metadata.wordCount}`);
} else {
  console.error(result.error.message);
}
```

<Tip>
  Храните API-ключ в переменной окружения, а не в коде напрямую. Например, используйте `process.env.WEB2MD_API_KEY` в Node.js.
</Tip>