Основы работы с 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"}'
Новый ключ представляет новое создание и может породить еще одну песочницу.