Авторизация и правила API.
Ключи, полномочия, ошибки, пагинация и идемпотентность.
Адрес и авторизация
Адрес API этого стенда: https://context4.me/v1. Консоль и подключения. Переменная CONTEXT4_API_KEY содержит ваш секретный ключ серверного окружения; документация его не подставляет.
curl "https://context4.me/v1/identity" \
-H "Authorization: Bearer $CONTEXT4_API_KEY"Ключ выпускается в консоли и показывается один раз. Его формат — ctx4_<env>_<secret>. Ключ ограничен областью организации и рабочего пространства и набором полномочий. Чужой tenant-ресурс возвращает 404 not_found. Нужное полномочие каждого метода указано в справочнике.
| Полномочие | Назначение |
|---|---|
tools:read | Инструменты и каталог HTTP-методов |
executions:read, executions:write | Чтение и создание выполнений; proxy тоже требует write |
connections:read, connections:write | Подключения, auth configs и источники |
connections:manage | Дополнительное право управлять чужими подключениями внутри tenant; требует connections:write |
tool-sessions:read, tool-sessions:write | Сессии инструментов |
syncs:read, syncs:write | Синхронизации и экспорты |
events:read, events:write | События и подписки |
Отсутствующее полномочие даёт 403 capability_missing. Обычный ключ не получает право изменять чужое подключение только из-за наличия connections:write. MCP OAuth не делегирует connections:manage.
Интерфейс предназначен для серверного использования. CORS на /v1, /mcp и compat не включён. Не помещайте bearer-ключ в браузерный код, URL или публичный репозиторий.
Тела и идентификаторы запросов
JSON передавайте с Content-Type: application/json. Лимит входного тела — 65 536 байт. Заголовки и request line ограничены listener; длинный vendor URL может быть отклонён ещё до маршрутизации.
X-Request-Id необязателен: допустимы 1–128 символов по шаблону [A-Za-z0-9][A-Za-z0-9._:-]{0,127}. Без него сервер создаёт UUID. Некорректное значение отклоняется с 422; ответ содержит новый безопасный request id. Сохраняйте X-Request-Id и execution id для диагностики.
Идемпотентность и повторы
Передавайте Idempotency-Key, когда он объявлен в параметрах метода. Значение: 8–128 символов [A-Za-z0-9._:-]. Повтор того же запроса с тем же ключом возвращает исходный результат; изменённое тело с прежним ключом даёт 409 idempotency_conflict. Для новой намеренной операции выбирайте новый ключ.
202 при создании execution означает принятие или сохранённый отказ, а не успешное изменение у провайдера. Читайте status, denial_code и адрес из Location, затем опрашивайте execution. Не повторяйте запись автоматически после таймаута: она могла примениться.
Текущий idempotency_conflict не различает ещё выполняющийся запрос и несовпадающее тело; Retry-After для него не обещан. Сверьте исходный запрос и состояние операции. Mirror API и raw proxy не являются идемпотентными: каждый вызов может отправить новый запрос провайдеру.
Пагинация
Списки используют непрозрачный cursor и next_cursor. Передавайте полученный курсор неизменным до null; не конструируйте его из ID. Общий limit — 1–100, по умолчанию 20; точные параметры и ограничения конкретного метода приведены в справочнике. Курсор ограничен 400 символами. Фильтры сохраняйте одинаковыми между страницами.
Vendor-пагинация — отдельный контракт провайдера: смотрите paging в описании endpoint. Существование курсора Context4 не означает автоматический сбор всех страниц upstream.
Ошибки и лимиты
Ошибка платформы возвращается как application/problem+json с type, code, title, status, request_id. Точные enum и поля: Problem. Внутренние причины и credentials клиенту не передаются.
| HTTP | Действие клиента |
|---|---|
| 400 | Исправьте параметры или тело; проверьте схему |
| 401 | Проверьте ключ, срок и отзыв |
| 403 | Проверьте полномочия, владельца, политику и ограничения сессии |
| 404 | Проверьте ID и область доступа |
| 409 | Проверьте конфликт версии, аккаунта или idempotency key |
| 429 | Соблюдайте Retry-After, если он возвращён |
| 500 | Сохраните request id для поддержки |
| 503 | Проверьте доступность сервиса; повтор записи требует проверки исхода |
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset описывают минутное окно API-ключа; reset — число секунд до сброса. При недоступности Redis изменения закрываются с 503; чтение может продолжиться без rate-limit заголовков. Квота выполнения и лимит HTTP-запросов — отдельные проверки.