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

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

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

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

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

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

## 1. Создание песочницы[​](#1-create-a-sandbox "Прямая ссылка на 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. Выполнение команды[​](#2-execute-a-command "Прямая ссылка на 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","…"]`.

## Проверка результата[​](#verify-the-result "Прямая ссылка на Проверка результата")

Ответ 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. Очистка ресурсов[​](#3-clean-up "Прямая ссылка на 3. Очистка ресурсов")

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

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

## Диагностика[​](#troubleshooting "Прямая ссылка на Диагностика")

* HTTP `401`: проверьте хост и персональный токен — его значение и срок действия.
* HTTP `403` с кодом `permission.read_only_token`: токен с правами *Только чтение* не может создавать и удалять песочницы, нужен токен с правами *Полные*.
* HTTP `429`: с кодом `quota.exceeded` — исчерпана квота, с кодом `rate_limit.exceeded` — превышено ограничение частоты запросов, повторите запрос позже.
* Песочница существует, но не выполняет команды: проверьте ее статус и события по [порядку диагностики](/sandboxes/observability-and-troubleshooting.md#diagnose).

## См. также[​](#related "Прямая ссылка на См. также")

* [Персональные токены](/accounts/personal-access-tokens.md)
* [Основы работы с API](/developers/api-fundamentals.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Изолированный запуск команды оболочки](/examples/run-untrusted-code.md)
