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

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

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

## Аутентификация[​](#authentication "Прямая ссылка на Аутентификация")

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

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

Для скриптов используйте [персональный токен](/accounts/personal-access-tokens.md). Права *Полные* разрешают изменения, права *Только чтение* ограничены безопасными REST-методами и инструментами MCP для чтения.

## Контекст аккаунта[​](#account-context "Прямая ссылка на Контекст аккаунта")

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

## JSON и ошибки[​](#json-and-errors "Прямая ссылка на JSON и ошибки")

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

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

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

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

## ID запроса[​](#request-ids "Прямая ссылка на ID запроса")

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

## Безопасный повтор создания[​](#retry-create-safely "Прямая ссылка на Безопасный повтор создания")

`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"}'
```

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

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

* [Быстрый старт с API](/getting-started/api.md)
* [Ошибки и ограничения частоты запросов](/developers/errors-and-rate-limits)
* [REST API](/api-reference/rest.md)
