API

Вы можете вызывать RanklyAI из своего сервиса или скриптов: конспекты по URL/тексту и SEO/GEO-аудиты. Бэкенд отдаёт JSON-RPC по одному эндпоинту.

Базовый URL и формат запроса

Все вызовы: POST на {BASE_URL}/api, где BASE_URL — адрес бэкенда (например из переменной окружения вашего приложения). Тело — JSON с полями type, id, method, args.

{
  "type": "call",
  "id": "req-1",
  "method": "public.summaries.fromUrl",
  "args": [{ "url": "https://example.com/article" }]
}

Ответ при успехе: HTTP 200, тело — JSON с полем result (данные метода). При ошибке: HTTP 4xx/5xx или result отсутствует, в теле может быть error с message.

Авторизация

Методы конспектов и SEO требуют авторизации. Варианты: 1) Вызвать public.auth.login с email и password — в ответ приходит Set-Cookie (adminAuth), дальше все запросы с этой cookie. 2) Использовать заголовок Authorization: Bearer <token> — токен сессии тот же, что в cookie (получить после login из Set-Cookie или хранить у себя).

POST /api
Content-Type: application/json
Authorization: Bearer <session_token>

{ "type": "call", "id": "1", "method": "public.summaries.list", "args": [{}] }

Конспекты (Summaries)

Создание конспекта — асинхронное: запрос возвращает id и status (processing), затем результат нужно забирать по get. Один запрос — один конспект; списание с бюджета по тарифу.

• public.summaries.fromUrl — конспект по URL статьи. args[0]: { url (обязательно), options? }. Ответ: { success: true, id, status } или { success: false, error } (например Unauthorized, INVALID_URL, RATE_LIMIT, SUMMARY_LIMIT / INSUFFICIENT_BALANCE).
• public.summaries.fromText — конспект по переданному тексту. args[0]: { text (обязательно), options? }. Ответ такой же: { success, id?, status? } или error.
• public.summaries.get — получить конспект по id. args[0]: { id }. Возвращает объект конспекта (id, url, title, status, summary, keyPoints, terms, statistics, practicalTasks, createdAt и т.д.) или null/ошибку. Пока status не COMPLETED — результат может быть частичным; опрашивайте get по id до готовности.
• public.summaries.list — список конспектов с пагинацией. args[0]: { page?, limit?, query?, status?, dateFrom?, dateTo?, sort? }. Ответ: { summaries: [...], pagination: { total, page, limit, pages } }.

SEO / GEO аудит

Аудит страницы по URL или тексту. По умолчанию асинхронный: запрос возвращает auditId, отчёт формируется в фоне (до нескольких минут); готовый результат забирают через public.seo.get. Для синхронного ответа (долгое ожидание по HTTP) передайте sync: true в теле — тогда ответом будет полный отчёт сразу.

• public.seo.audit — запуск аудита. args[0]: { url? (или text?), mode?: 'basic'|'geo'|'auto', locale?, targetQueries?, useRendered?, sync? }. Обязательно url или text. Ответ (async): { success: true, async: true, auditId, message } или при sync: true — полный объект с result, coreWebVitals, llm и т.д. Ошибки: Unauthorized, INVALID_URL, INVALID_TEXT, RATE_LIMIT, INSUFFICIENT_BALANCE, LIMIT_EXCEEDED.
• public.seo.get — получить отчёт по id. args[0]: { id } (auditId). Возвращает запись аудита; в payload.jobStatus — pending | complete | failed. Пока pending — отчёт ещё формируется.
• public.seo.list — список аудитов. args[0]: { page?, limit?, sort?, query?, mode?, dateFrom?, dateTo? }. Ответ: { audits: [...], pagination: { total, page, limit, pages } }.

Полный перечень методов и параметров можно получить вызовом introspection.getSchema (без авторизации). Регистрация и вход: public.auth.register, public.auth.login; текущий пользователь: public.auth.me.