Начало работы с API Instatus

Все эндпоинты находятся по адресу https://api.instatus.com. В целом они следуют архитектуре REST.

Все запросы должны быть в формате JSON с заголовком Content-Type: application/json.

Ответы API Instatus, включая ошибки, также приходят в формате JSON.

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

Запросы к API Instatus должны передавать API-ключ в заголовке Authorization:

Authorization: Bearer <API_KEY>

Создавайте ключи в разделе панели управления › Разработчику кнопкой Создать ключ. Ключей может быть несколько, у каждого своё название, например «GitHub Actions» или «Terraform». Ключи начинаются с inst_sk_.

Что может ключ

У каждого ключа свои настройки:

  • Роль: Участник, Редактор или пользовательская роль на плане Business. Роль определяет, что ключ может просматривать и изменять, так же как для людей. Ключ не может быть Владельцем, поэтому оплата, роли и удаление остаются за людьми.
  • Доступ: Просмотр и изменение или Только просмотр. Ключ с доступом «Только просмотр» ничего не может изменить, что бы ни разрешала его роль.
  • Проекты: все проекты, включая те, что вы добавите позже, или только выбранные.
  • Срок действия: дата, после которой ключ перестаёт работать. На плане Free ключ может действовать до 90 дней, на Pro — до 1 года, а на Business и Enterprise — сколько угодно, в том числе бессрочно. Владелец команды может задать меньший срок в разделе Настройки команды › Ключи API. Это не касается ключей, созданных до появления настроек ключей, а у существующих ключей срок сохраняется при смене плана.
  • Разрешённые IP: на плане Business ключ работает только с указанных IP-адресов или диапазонов.

Ключ принадлежит команде или вам:

  • Ключи команды продолжают работать, когда человек, который их создал, уходит из команды. Используйте их для CI, скриптов и интеграций.
  • Личные ключи действуют от вашего имени и никогда не могут больше, чем вы. Им можно задать роль Как у вас, и они перестают работать, если вы уйдёте из команды.

Владельцы команды задают правила для ключей в разделе Настройки команды › Ключи API: максимальный срок действия ключа, могут ли участники создавать ключи команды и разрешены ли личные ключи.

Создание, изменение, перевыпуск и отзыв ключа видны в разделе «Активность» команды, как и ключ, отозванный из-за утечки. Всё, что сделано через ключ или подключённое приложение, отображается там как человек через название ключа или приложения.

Как хранить ключи

  • Ключ показывается один раз, при создании. Сразу скопируйте его и храните как секрет.
  • Чтобы заменить ключ, откройте его и нажмите Перевыпустить. Выберите, сколько ещё будет работать старый ключ, до 7 дней, чтобы успеть обновить всё, что его использует.
  • Отзовите ключ через его меню, и он сразу перестанет работать.

Ключи, созданные до появления настроек ключей, продолжают работать без изменений. В разделе «Разработчику» они отмечены как «Создан до настроек ключей». Там к ним можно добавить ограничения или заменить их новым ключом.

Ошибки ключей

Если ключ не может выполнить запрос, ошибка содержит один из этих кодов, а её сообщение подсказывает, что изменить.

КодСтатусПричина
invalid_key401Такого ключа нет. Проверьте, что скопировали его целиком.
key_expired401Срок действия ключа истёк.
key_revoked401Ключ отозван.
key_owner_left401Человек, от имени которого действует личный ключ, ушёл из команды.
key_view_only403У ключа доступ «Только просмотр», а запрос что-то изменяет.
role_not_allowed403Роль ключа не позволяет просматривать или изменять это.
ip_not_allowed403Запрос пришёл с IP-адреса, который ключ не разрешает.
page_not_allowed403Ключ не может работать с этим проектом.
account_action_not_allowed403Ключи не могут создавать или удалять страницы, команды и рабочие пространства. Используйте панель управления.
route_not_allowed403Этот маршрут не входит в документированный API.

Как узнать ID страницы

ID страницы можно найти в панели управления:

  1. Откройте панель управления.
  2. Нажмите правой кнопкой по проекту в левом верхнем углу, чтобы открыть меню.
  3. Нажмите Copy Project ID — ID страницы скопируется в буфер обмена.
ID страницы

Ошибки

Все эндпоинты API возвращают код и сообщение в ответах об ошибке.

{
"error": {
"code": "forbidden",
"message": "Not authorized"
}
}

Значения статусов

Возможные статусы страницы. Это подробный status, который возвращает актуальный API (v2 и новее). Устаревший эндпоинт summary.json и уведомления через вебхуки используют сокращённый набор — только UP, HASISSUES и UNDERMAINTENANCE.

  • UP
  • HASISSUES
  • ALLUNDERMAINTENANCE
  • ALLDEGRADEDPERFORMANCE
  • ALLPARTIALOUTAGE
  • ALLMINOROUTAGE
  • ALLMAJOROUTAGE
  • SOMEUNDERMAINTENANCE
  • SOMEDEGRADEDPERFORMANCE
  • SOMEPARTIALOUTAGE
  • SOMEMINOROUTAGE
  • SOMEMAJOROUTAGE
  • ONEUNDERMAINTENANCE
  • ONEDEGRADEDPERFORMANCE
  • ONEPARTIALOUTAGE
  • ONEMINOROUTAGE
  • ONEMAJOROUTAGE

Возможные статусы компонента:

  • OPERATIONAL
  • UNDERMAINTENANCE
  • DEGRADEDPERFORMANCE
  • PARTIALOUTAGE
  • MAJOROUTAGE

Возможные статусы инцидента:

  • INVESTIGATING
  • IDENTIFIED
  • MONITORING
  • RESOLVED

Возможные статусы обслуживания:

  • NOTSTARTEDYET
  • INPROGRESS
  • COMPLETED

Перейти к эндпоинтам: