Перейти к содержимому

Политики API

Машинный контракт — openapi.json. Рабочий пример — quickstart.md. Эта страница публикует числа и семантику, на которых спотыкаются разработчики: лимиты, ошибки, идемпотентность, доставка вебхуков, версии.

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

Authorization: Bearer <token> в каждом запросе. Персональные токены доступа Sanctum создаются в Настройки → API. Без cookie и без CSRF: хост API не принимает сессионную аутентификацию. Запрос с валидной cookie приложения, но без bearer-токена, всё равно 401.

Права токена — это области:

feeds:read feeds:write
posts:read posts:write
channels:read publishers:read
account:read

Токен без отмеченных прав получает права на чтение явными строками. Подстановки «все права» нет. Неверное право — это 403. Отозванный, истёкший или неизвестный токен — это 401. Чужой id записи — это 404, не 403, поэтому существование не утекает между аккаунтами. Не больше 20 активных токенов на пользователя.

Лимиты частоты

Два ведра. Ведро на пользователя общее для всех его токенов. Ведро на IP срабатывает до аутентификации как потолок от флуда и не режет законное использование тарифа.

ТарифЗапросов/мин (на пользователя)
free (тариф, который получают новые пользователи)30
starter60
pro180
agency600
безлимит (флаг, переопределение или дополнение)защитный потолок 3000

Нет права или право равно нулю — доступа к API нет: 403 forbidden, не ведро IP. Смена тарифа доходит до лимитера до 60 с. Потолок флуда по IP (6000/мин) выше бюджета любого тарифа. IP с 60 неудачными аутентификациями за минуту отклоняется до поиска токена.

Каждый аутентифицированный ответ несёт X-RateLimit-Limit, -Remaining и -Reset. Ответ 429 несёт Retry-After: подождите столько секунд. Если хранилище счётчика недоступно, API закрывается с 503, а не обходит лимиты. Сервер MCP (/mcp) использует то же ведро на пользователя.

Ошибки

Ответы с ошибкой используют один конверт:

{ "error": { "type": "validation_failed",
"message": "The given data was invalid.",
"details": { "title": ["…"] },
"request_id": "01J…" } }

request_id — это ULID в каждом ответе: в теле при ошибке и в заголовке X-Request-Id при успехе. Он пишется в лог сервера. Отправьте его в поддержку, и вызов найдётся без догадок. details есть только тогда, когда есть что сказать про конкретное поле.

ТипСтатусЗначение
unauthenticated401Токен отсутствует, отозван или истёк.
forbidden403Неверное право, или тариф не даёт доступ к API.
not_found404Такой записи в этом аккаунте нет.
malformed_json400Тело — невалидный JSON.
payload_too_large413Тело больше лимита 256 КБ.
unsupported_media_type415Запись должна использовать Content-Type: application/json.
validation_failed422Неизвестные поля, плохие значения, неизвестные фильтры.
invalid_cursor422Подделанный, чужой или не совпавший с фильтрами курсор. Начните с первой страницы.
idempotency_in_progress409Тот же ключ ещё выполняется. Подождите секунду и повторите с тем же ключом.
idempotency_key_reused422Тот же ключ, другой запрос. Новой операции нужен новый ключ.
rate_limited429Бюджет исчерпан. Соблюдайте Retry-After.
service_unavailable503API выключен или хранилище лимитера недоступно. Повторите с нарастающей паузой.

Метки времени — ISO 8601 UTC (Z). Вход без смещения — это 422. Id — целочисленные первичные ключи. Ни один ответ не содержит user_id, хеши токенов, OAuth-токены или сырые метаданные провайдера.

Пагинация, фильтры, сортировка

Курсор: ?cursor= и ?per_page= (по умолчанию 25, максимум 100). Курсор подписан и привязан к ресурсу, пользователю, родителю и фильтрам. Курсор от другого набора фильтров — это 422 invalid_cursor, не тихий перезапуск. Списки не считают общее число. meta — это {per_page, next_cursor, has_more}.

Фильтры разрешены по списку на каждый endpoint (см. openapi.json). Неизвестный ключ — это 422. В v1.0 API сортировки нет. Списки идут id DESC (умные фиды листаются по позиции в снимке).

Идемпотентность

Все POST/PATCH требуют Idempotency-Key. DELETE его принимает. От 1 до 255 печатных символов ASCII, область — владелец токена, хранение 24 ч.

  • Повтор ключа возвращает исходные статус и тело и не выполняет операцию снова. Повтор безопасен при любом сомнении в сети. Восстанавливаются только Content-Type и Location. X-Request-Id и Cache-Control на каждом повторе новые.
  • Тот же ключ с другим методом, путём, запросом или телом — это 422 idempotency_key_reused.
  • Ключ, который ещё выполняется в другом месте, — это 409 с Retry-After: 1.
  • После истечения ключ — новая логическая операция.
  • Новый токен с достаточными правами может повторить ключ. Токен с меньшими правами получает 403 на повторе.

Вебхуки

Подписка в Настройки → API (до 20 endpoint на пользователя, только публичный HTTPS). События: post.published, publisher.run.failed, channel.token_expired. Содержимое — версионированный конверт (WebhookPostPublished, WebhookPublisherRunFailed, WebhookChannelTokenExpired в openapi.json). Ломающее изменение формы выходит новым version, а не тихой сменой поля.

Гарантии доставки:

  • Как минимум один раз, без порядка. Дедупликация по устойчивому event_id: UUID для post.published, publisher.run.failed:<uuid> и channel.token_expired:<integrationId>:<uuid> для двух других. X-Feedigy-Delivery несёт id строки доставки этого endpoint (целое, устойчивое на повторах этой доставки) и то же тело.
  • Пять попыток (первая отправка и повторы примерно через 10 с, 60 с, 5 мин, 30 мин, плюс джиттер). Ограниченный Retry-After на ваш 429/503 важнее лестницы. Редиректов нет, таймаут HTTP — 10 с.
  • Пять окончательных неудач подряд сами отключают endpoint и дают одно уведомление в приложении. Любой успех или повторное включение сбрасывает счётчик.
  • Подпись: X-Feedigy-Signature: t=<ts>,v1=<hmac> от <ts>.<точное сырое тело>, HMAC-SHA256 с вашим секретом. На каждую попытку новая метка времени, тело и id доставки те же. Отклоняйте метки вне окна 5 минут, сравнивайте за постоянное время. В течение 24 ч после смены секрета приходят обе подписи. Принимайте любую.
  • Содержимое тонкое (id и краткие сводки, меньше 64 КБ) и повторяет публичные ресурсы v1: без токенов, без содержимого провайдера, без секретов.
  • Журнал доставки в настройках показывает коды статуса и сокращённые выдержки, фильтрует неудачи и отдаёт повтор по запросу. Выключение endpoint откладывает его ожидающие строки. Включение их отправляет.

Версии

/v1/… в пути. v2 выходит рядом с v1. v1 не убирают без опубликованного окна устаревания и заголовков Sunset. Добавления (новые поля, новые endpoint, новые события) версию не поднимают. Ломающее изменение формы выходит новым version содержимого (вебхуки) или новой версией пути (REST). Удаление или переименование требует v2.

Keep posting through busy weeks

Set sources, keywords and posting hours once. Feedigy posts to your channels while you work on other things.

No card required. The Free plan has no time limit.