Политики API
Машинный контракт — openapi.json. Рабочий пример —
quickstart.md. Эта страница публикует числа и семантику,
на которых спотыкаются разработчики: лимиты, ошибки, идемпотентность,
доставка вебхуков, версии.
Аутентификация
Authorization: Bearer <token> в каждом запросе. Персональные токены
доступа Sanctum создаются в Настройки → API. Без cookie и без CSRF:
хост API не принимает сессионную аутентификацию. Запрос с валидной cookie
приложения, но без bearer-токена, всё равно 401.
Права токена — это области:
feeds:read feeds:writeposts:read posts:writechannels:read publishers:readaccount:readТокен без отмеченных прав получает права на чтение явными строками. Подстановки «все права» нет. Неверное право — это 403. Отозванный, истёкший или неизвестный токен — это 401. Чужой id записи — это 404, не 403, поэтому существование не утекает между аккаунтами. Не больше 20 активных токенов на пользователя.
Лимиты частоты
Два ведра. Ведро на пользователя общее для всех его токенов. Ведро на IP срабатывает до аутентификации как потолок от флуда и не режет законное использование тарифа.
| Тариф | Запросов/мин (на пользователя) |
|---|---|
free (тариф, который получают новые пользователи) | 30 |
starter | 60 |
pro | 180 |
agency | 600 |
| безлимит (флаг, переопределение или дополнение) | защитный потолок 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 есть только
тогда, когда есть что сказать про конкретное поле.
| Тип | Статус | Значение |
|---|---|---|
unauthenticated | 401 | Токен отсутствует, отозван или истёк. |
forbidden | 403 | Неверное право, или тариф не даёт доступ к API. |
not_found | 404 | Такой записи в этом аккаунте нет. |
malformed_json | 400 | Тело — невалидный JSON. |
payload_too_large | 413 | Тело больше лимита 256 КБ. |
unsupported_media_type | 415 | Запись должна использовать Content-Type: application/json. |
validation_failed | 422 | Неизвестные поля, плохие значения, неизвестные фильтры. |
invalid_cursor | 422 | Подделанный, чужой или не совпавший с фильтрами курсор. Начните с первой страницы. |
idempotency_in_progress | 409 | Тот же ключ ещё выполняется. Подождите секунду и повторите с тем же ключом. |
idempotency_key_reused | 422 | Тот же ключ, другой запрос. Новой операции нужен новый ключ. |
rate_limited | 429 | Бюджет исчерпан. Соблюдайте Retry-After. |
service_unavailable | 503 | API выключен или хранилище лимитера недоступно. Повторите с нарастающей паузой. |
Метки времени — 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.
