Перейти к основному содержимому
Открыть Markdown

Основы работы с API

Собственный REST API начинается с /v1 по тому же публичному адресу, что и дашборд Just Run. Один раз задайте адрес инсталляции и добавляйте пути:

export JUSTRUN_API="https://your-just-run-host"

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

Аутентифицированные запросы используют bearer-токен доступа:

curl "$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT"

Для скриптов используйте персональный токен. Права Полные разрешают изменения, права Только чтение ограничены безопасными REST-методами и инструментами MCP для чтения.

Контекст аккаунта​

Аутентифицированный контекст содержит активный личный аккаунт или организацию. Обработчики запросов ограничивают операции этим аккаунтом. Перед созданием токена для другого аккаунта переключите контекст в дашборде, а не отправляйте произвольный заголовок с ID аккаунта.

JSON и ошибки​

Для тела JSON отправляйте Content-Type: application/json. Публичная ошибка состоит из статуса HTTP и объекта:

{
"error": "human-readable message"
}

Основные статусы:

  • 400 — неверные поля или несовместимая с состоянием операция;
  • 401 — отсутствующая, неверная, истекшая или отозванная аутентификация;
  • 403 — недостаточные права или разрешения;
  • 404 — ресурс не виден;
  • 409 — конфликт жизненного цикла;
  • 429 — квота или ограничение частоты запросов;
  • 502/503 — возможно временное состояние исходного сервера или нехватка ресурсов;
  • 500 — внутренняя ошибка с намеренно общим публичным текстом.

ID запроса​

Каждый ответ содержит x-request-id. Для диагностики сохраните его вместе со временем, методом, путем, статусом и ID ресурса. Валидный ID, переданный клиентом, пробрасывается; иначе шлюз генерирует новый.

Безопасный повтор создания​

POST /v1/sandboxes принимает Idempotency-Key. Используйте одно уникальное значение для одной логической операции и повторяйте его только при неизвестном результате первого запроса:

curl --request POST "$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Idempotency-Key: worker-build-42" \
--header "Content-Type: application/json" \
--data '{"template":"base"}'

Новый ключ представляет новое создание и может породить еще одну песочницу.