Проверьте свой Key

GET /ping — это канонический первый запрос к Developer REST API: он подтверждает, что ваш key работает, и сообщает, что именно он может делать. Выполните этот запрос сразу после создания key, чтобы проверить учётные данные перед тем, как строить интеграцию на endpoints ресурсов.

`GET /ping`

Проверяет вызывающие учётные данные и сообщает контекст developer API, в который они разрешаются. Возвращает 200 с проверенным контекстом или 401, если key отсутствует, искажён, отозван или неизвестен.

Scope: не требуется — любой действительный key (или активная сессия) · Успех: 200

В отличие от каждого endpoint ресурсов, /ping не ограничен scope. Key, несущий любой отдельный scope — даже только knowledge:read — может вызвать его, чтобы проверить себя. В этом и смысл: вы должны иметь возможность убедиться, что key работает, независимо от того, что ему разрешено делать.


curl https://cuneiform.chat/api/developer/v1/ping \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

Запрос, аутентифицированный по key, возвращает организацию, от имени которой действует key, аутентифицированную роль, способ аутентификации, а также id вызывающего key, его имя, последние четыре символа и предоставленные scopes:


{
  "object": "developer_api_context",
  "organization": {
    "id": "org_8s2k1d",
    "name": "Acme Inc"
  },
  "role": "owner",
  "authenticated_via": "api_key",
  "api_key": {
    "id": "key_4f9a2c",
    "name": "Production CI",
    "last4": "ab12",
    "scopes": ["agents:read", "agents:query", "knowledge:read"]
  }
}

Массив scopes — это в точности набор, предоставленный key — используйте его, чтобы убедиться, что key имеет доступ, необходимый вашей интеграции, прежде чем полагаться на него.

Ошибки: 401, 429, 500.

Что сообщает ответ

Поле	Значение
`object`	Всегда `developer_api_context`.
`organization`	Организация, от имени которой действуют учётные данные — `id` и отображаемое `name`. Каждый запрос ограничен этой организацией; вы никогда не передаёте id организации.
`role`	Роль, в которой действуют учётные данные (например `owner`, `admin` или `member`). Key никогда не может делать больше, чем эта роль могла бы в панели.
`authenticated_via`	`api_key` для key `cuk_…` или `session` для активной сессии в панели администратора.
`api_key`	Самоописание вызывающего key — `id`, `name`, `last4` и предоставленные `scopes`. Равно `null`, когда `authenticated_via` равно `session` (key отсутствует).

Что он никогда не возвращает

Ответ работает по принципу deny-by-default: он строится только из проверенного контекста запроса, поэтому никогда не может вернуть данные другой организации и не раскрывает внутреннее поле key. Полный секрет key, hash поиска, создатель, необработанный внутренний id и базовые RBAC-разрешения роли никогда не присутствуют — только четыре поля key выше.

Когда он завершается ошибкой

Отсутствующий, искажённый, отозванный или неизвестный key возвращает 401 со стандартным конвертом ошибки:


{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

Поскольку /ping не ограничен scope, он никогда не возвращает 403 по причине scope — 401 означает, что сами учётные данные недействительны.