# API Linkovod.ru

⚠️ Сейчас API поддерживает только работу с крауд-ссылками. Следите за обновлениями.

Базовый URL: https://linkovod.ru/api
Авторизация: заголовок `Authorization: Bearer <API_KEY>` (ключ выдаётся в личном кабинете)
Content-Type: application/json
Лимит: 30 запросов в секунду, запросы выполнять последовательно, дожидаясь ответа

При использовании API/MCP пользователь сам управляет размещением ссылок,
без участия алгоритма Linkovod: сам выбирает поисковые запросы, типы ссылок, скорость размещения —
либо поручает планирование ссылочной стратегии ИИ-агенту.

## Создание задания на размещение ссылки
- Перед созданием заданий необходимо один раз создать проект с адресом сайта
- Для каждого задания передаётся ID проекта, домен в задании должен совпадать с доменом проекта
- ID задания и ID проекта нужно сохранить для дальнейшего управления
- Сайты-доноры отбираются индивидуально, предварительно выбрать нельзя

## Отслеживание статуса
- Проверять статус задания не чаще 1 раза в сутки
- Время выполнения: от нескольких часов до нескольких дней

## Гарантия и мониторинг
- Каждое задание проверяется модераторами
- Наличие ссылки проверяется в течение 30 дней (гарантийный срок), при удалении — замена на аналогичную
- Рекомендуется синхронизировать статусы раз в сутки

## Управление заданиями
- Отклонить выполненную работу можно в течение 30 дней по уважительной причине
- Удалить задание можно только пока оно в статусе NEW

## Эндпоинты

### GET v1/users — Данные пользователя
Возвращает баланс и данные пользователя.
Ответ: { "userId": 1050, "email": "duncan@macleod.com", "name": "Дункан Маклауд", "balance": 1500 }

### POST v1/projects — Создание проекта
Параметры: url (string, обязателен, http:// или https://), name (string, необязателен, 1-255 символов), language (string, необязателен, по умолчанию RUSSIAN)

Поддерживаемые языки: ENGLISH, SPANISH, GERMAN, JAPANESE, FRENCH, PORTUGUESE, RUSSIAN, ITALIAN, DUTCH, POLISH, VIETNAMESE

Запрос: { "url": "https://www.macleod.com", "name": "Macleod", "language": "RUSSIAN" }
Ответ: { "status": "Project created successfully", "projectId": 5001 }

### GET v1/projects — Список проектов
Возвращает массив проектов: projectId, name, status, domain, language, maxCrowdPrice, createdAt, updatedAt

Статусы проектов:
- ACTIVE — активный проект
- PENDING — проект находится на проверке администрацией
- PAUSED — автоматическая покупка ссылок отключена
- REJECTED — проект отклонен (причина в rejectReason)

Возможные значения rejectReason: Language or region does not match the site, Prohibited content, Technical issues on the site

### GET v1/projects/<projectId>/status — Статус проекта
Статусы проектов: ACTIVE, PENDING, PAUSED, REJECTED (причина в rejectReason, значения — см. выше в GET v1/projects)
Ответ: { "projectId": 5001, "status": "ACTIVE", "domain": "macleod.com", "language": "RUSSIAN", "maxCrowdPrice": 400, "createdAt": "...", "updatedAt": "..." }

### PATCH v1/projects/<projectId> — Обновление лимита цены проекта
Параметры: maxCrowdPrice (number, от 250 ₽ для русского языка, от 300 ₽ для остальных языков, до 1000 ₽)
Запрос: { "maxCrowdPrice": 400 }
Ответ: { "projectId": 5001, "domain": "macleod.com", "name": "Macleod", "status": "ACTIVE", "maxCrowdPrice": 400 }

### DELETE v1/projects/<projectId> — Удаление проекта
Только если нет активных заданий.
Ответ: { "message": "Project deleted successfully" }

### POST v1/tasks — Создание задания на ссылку
Параметры: projectId (number), keyword (string, до 100 символов), url (string)
Запрос: { "projectId": 5001, "keyword": "заявка на бессмертие", "url": "https://www.macleod.com/immortality-application" }
Ответ: { "status": "Link task created successfully", "taskId": 20505, "balanceAfter": 12300 }

### GET v1/tasks/<taskId>/status — Статус задания
Статусы заданий:
- NEW — новое задание, еще не взято в работу
- IN_PROGRESS — задание находится в работе
- PENDING — задание находится на проверке модератором
- REJECTED — задание дорабатывается исполнителем
- COMPLETED — задание выполнено
- DELETED — задание удалено (админом или клиентом)

Для удалённых заданий (status: DELETED) в ответе присутствует поле deleteReason с причиной удаления на английском.

Возможные значения deleteReason: Site is unavailable or blocked, Page has no content, The task cannot be completed on the selected donor, Redirects to another page or site, Language or region does not match the page, Keyword contains an error, Keyword does not match the page, Unable to complete the task due to technical reasons, Task deleted by client (при удалении клиентом), Task deleted, no reason specified (причина не указана)

Ответ: { "taskId": 20505, "projectId": 5001, "status": "COMPLETED", "keyword": "...", "targetUrl": "...", "resultUrl": "...", "price": 300, "warrantyUpTo": "...", "createdAt": "...", "updatedAt": "..." }
Ответ для удалённого задания: { "taskId": 20508, "projectId": 5001, "status": "DELETED", "keyword": "заявка на бессмертие", "targetUrl": "https://www.macleod.com/immortality-application", "deleteReason": "Page has no content", "createdAt": "...", "updatedAt": "..." }

### GET v1/projects/<projectId>/tasks — Список заданий проекта
Параметры: page (по умолчанию 1), limit (по умолчанию 10, макс 1000), status (фильтр: NEW/IN_PROGRESS/PENDING/REJECTED/COMPLETED/DELETED). Без параметра status возвращаются задания всех статусов, включая DELETED.
Пример: GET /v1/projects/5001/tasks?page=1&limit=100&status=NEW

Статусы заданий и значения deleteReason — см. выше в GET v1/tasks/<taskId>/status.

Ответ содержит массив tasks и pagination (currentPage, totalPages, totalCount, limit). Поле completedAt присутствует в задании, только если оно не null.

### PATCH v1/tasks/<taskId>/reject — Отклонение выполненного задания
Параметры: reason (string, до 255 символов)
Запрос: { "reason": "Настоящий горец только Эдриан Пол, исправьте!" }
Ответ: { "message": "Link task sent for rework successfully" }

### DELETE v1/tasks/<taskId> — Удаление задания
Только для заданий в статусе NEW, возвращает средства на баланс.
Ответ: { "message": "Link task deleted, funds returned", "balanceAfter": 12600 }

## Коды ответов сервера
- 200 — запрос выполнен успешно
- 201 — создание проекта/задания выполнено успешно
- 400 — неверные параметры запроса
- 401 — ошибка авторизации (неверный или отсутствующий API-ключ)
- 403 — доступ запрещён (попытка изменить чужое задание)
- 404 — ресурс не найден
- 429 — превышен лимит 30 запросов в секунду
- 500 — ошибка сервера, рекомендуется повторить запрос позже