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

Быстрый старт с API

Тремя аутентифицированными REST-запросами создайте песочницу, выведите сообщение и удалите ее. API доступен по тому же адресу, что и дашборд Just Run.

Перед началом​

Нужны cURL, jq и персональный токен с правами Полные. Создайте его в Токены → Новый токен, сохраните значение токена — Just Run показывает его только один раз — и задайте:

export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"

Не коммитьте эти значения.

1. Создание песочницы​

CREATE_RESPONSE=$(
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: api-quickstart-1" \
--data '{"template":"base","name":"api-quickstart"}'
)

SANDBOX_ID=$(jq -er '.id' <<<"$CREATE_RESPONSE")
printf 'created %s\n' "$SANDBOX_ID"

Первое создание возвращает HTTP 201. Сохраните ID для следующих операций.

Повтор этого запроса с тем же ключом идемпотентности в течение 30 дней после создания возвращает ответ первого создания — с тем же ID песочницы и кодом 200 вместо 201. Удаление песочницы ключ не сбрасывает: если песочницу удалили, повтор в эти 30 дней возвращает HTTP 404. Чтобы пройти инструкцию повторно, задайте в Idempotency-Key новое значение.

2. Выполнение команды​

curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{"cmd":"echo","args":["hello from just-run"],"timeout":30000}' |
jq

REST-контракт выполнения использует строковый cmd, отдельный массив args и timeout в миллисекундах. Оболочка при этом не запускается: для конвейеров и && передайте "cmd":"sh","args":["-c","…"].

Проверка результата​

Ответ HTTP 200 содержит:

{
"exit_code": 0,
"stdout": "hello from just-run\n",
"stderr": ""
}

Ненулевой exit_code при ответе HTTP 200 означает, что команда запустилась и завершилась с ошибкой. Если команду не удалось запустить, API возвращает HTTP-ошибку: несуществующая команда дает HTTP 422 с кодом request.validation_failed, а не ненулевой exit_code.

3. Очистка ресурсов​

curl --fail-with-body --silent --show-error \
--request DELETE "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"

Успешное удаление возвращает HTTP 204.

Диагностика​

  • HTTP 401: проверьте хост и персональный токен — его значение и срок действия.
  • HTTP 403 с кодом permission.read_only_token: токен с правами Только чтение не может создавать и удалять песочницы, нужен токен с правами Полные.
  • HTTP 429: с кодом quota.exceeded — исчерпана квота, с кодом rate_limit.exceeded — превышено ограничение частоты запросов, повторите запрос позже.
  • Песочница существует, но не выполняет команды: проверьте ее статус и события по порядку диагностики.