# Разработчикам

Just Run предоставляет несколько интеграционных контрактов вокруг одной платформы, в которой все ресурсы принадлежат аккаунтам. Этот раздел помогает выбрать между ними и правильно обработать аутентификацию, асинхронное состояние, вывод в реальном времени, ошибки, повторные попытки и изменения контрактов. Точные пути, поля, ответы, инструменты и фреймы протоколов находятся в [Справочнике API](/api-reference.md).

Собственный REST API — основной выбор для новой интеграции. MCP, работа в реальном времени, совместимость с E2B и входящие вебхуки решают более узкие задачи и не являются взаимозаменяемыми псевдонимами REST.

## Выбор способа интеграции[​](#choose-an-integration-surface "Прямая ссылка на Выбор способа интеграции")

| Способ                                 | Лучший сценарий                                                                                 | Чего не следует предполагать                                                                                                           |
| -------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Собственный REST API под `/v1`         | Сервисы, скрипты, CLI, управление жизненным циклом и точный контроль запросов и ответов         | Что каждая операция синхронна или допускает безопасный повтор                                                                          |
| MCP управления платформой на `/mcp`    | AI-агенты и MCP-клиенты, которые обнаруживают и вызывают инструменты платформы уровня аккаунта  | Что это Hosted MCP, туннель REST или API стриминга команд                                                                              |
| Эндпоинты песочницы на SSE и WebSocket | Постепенный вывод команд, переподключение к фоновому процессу и интерактивные терминалы         | Что у всех способов передачи одинаковая модель переподключения                                                                         |
| Адаптер совместимости с E2B            | Существующие приложения, проверенные с закрепленным оригинальным Python SDK `e2b`               | Полный паритет с E2B Cloud или собственный Python SDK Just Run                                                                         |
| Получатель вебхука автоматизации       | События провайдера, которые должны поставить запуск автоматизации в очередь                     | Что входящее событие аутентифицируется персональным токеном Just Run                                                                   |
| Публичный артефакт OpenAPI             | Генерация проверяемых типов для операций собственного REST API из публичного списка разрешенных | Что он покрывает инструменты MCP, семантику вебхуков, фреймы протоколов реального времени или каждый маршрут, реализованный в продукте |

Одна интеграция может сочетать несколько способов. Например, создать и проверить песочницу через REST, запустить фоновый процесс через REST и следить за ним через WebSocket. Назначьте одного канонического владельца каждой операции, чтобы резервная логика случайно не отправила одно изменение дважды.

## Одна инсталляция, несколько контрактов[​](#one-deployment-several-contracts "Прямая ссылка на Одна инсталляция, несколько контрактов")

```
integration
   │
   ├── REST /v1 ───────── resources, lifecycle, files, Storage, configuration
   ├── MCP /mcp ───────── discoverable control-plane tools for an agent
   ├── SSE / WebSocket ── command output, process attach, terminal
   ├── E2B adapter ────── translated control and sandbox data planes
   └── webhook receiver ─ verified external event → queued Automation run

all account-scoped control paths converge on the same deployment,
but each surface keeps its own authentication and completion contract
```

Используйте публичный адрес, предоставленный инсталляцией, например `https://your-just-run-host`. Собственный REST API, часть платформы для работы с данными песочницы, `/mcp` и адаптер E2B размещены по этому адресу шлюза. Приложения превью используют сгенерированные URL превью и имеют отдельную границу публикации и аутентификации.

## Аутентификация для нужного аккаунта[​](#authenticate-the-intended-account "Прямая ссылка на Аутентификация для нужного аккаунта")

Для интеграции с собственным REST API, работающей без участия человека, создайте [персональный токен](/accounts/personal-access-tokens.md), пока дашборд находится в личном контексте или контексте организации, которая должна владеть ресурсами. Персональный токен остается привязан к этому аккаунту; клиент не выбирает другой аккаунт, добавляя заголовок с ID аккаунта.

| Контракт                        | Способ передачи учетных данных                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Защищенный собственный REST API | `Authorization: Bearer <PAT>` или поддерживаемый токен пользовательской сессии                                                                          |
| MCP управления платформой       | Статический `Authorization: Bearer <PAT>` в запросах Streamable HTTP или вход через браузер по OAuth: MCP-клиент сам получает и обновляет токен доступа |
| SSE и WebSocket песочницы       | Аутентификация bearer; у handshake из браузера есть отдельный путь с короткоживущей сессией                                                             |
| Управляющая часть E2B           | Персональный токен Just Run в `X-API-Key`; возвращенный токен доступа песочницы — для преобразованной части платформы для работы с данными              |
| Вебхук автоматизации            | Проверка подписи провайдера или общий токен, настроенные в автоматизации                                                                                |

Используйте персональный токен `read_only` для клиентов, которые только читают состояние. Основные изменяющие операции REST блокируются по методу HTTP, а MCP одновременно скрывает и отклоняет инструменты записи для такого токена. Выбирайте `full` только когда интеграция должна создавать, выполнять, изменять или удалять ресурсы.

Некоторые публичные маршруты обнаружения, входа, хранилища, превью, вебхуков и совместимости намеренно используют другие промежуточные обработчики. Следуйте контракту аутентификации на странице-владельце, а не добавляйте персональный токен к каждому URL. Никогда не помещайте долгоживущий персональный токен в строку запроса.

## Основы собственного REST API[​](#native-rest-fundamentals "Прямая ссылка на Основы собственного REST API")

Один раз задайте адрес инсталляции и добавляйте документированный путь:

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

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

Большинство тел запросов и ответов управляющей части платформы используют JSON, а передача файлов, операции хранилища по presigned URL, ответы SSE и переключения на WebSocket — документированные для них типы содержимого. Публичная ошибка HTTP содержит код статуса и небольшое тело JSON:

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

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

Коды статуса определяют способ восстановления:

| Статус          | Реакция интеграции                                                                    |
| --------------- | ------------------------------------------------------------------------------------- |
| `400` или `422` | Исправить запрос; повтор того же тела бесполезен                                      |
| `401`           | Обновить или заменить учетные данные, не запускать цикл                               |
| `403`           | Проверить права персонального токена или разрешения                                   |
| `404`           | Считать ресурс недоступным текущему аккаунту                                          |
| `409`           | Прочитать текущее состояние жизненного цикла до выбора следующей операции             |
| `413`           | Уменьшить или перенести передаваемые данные согласно правилам соответствующей функции |
| `429`           | Отличить исчерпание квоты от ограничения частоты запросов и отступить                 |
| `502` или `503` | Считать потенциально временным сбоем, но повторять только безопасную операцию         |
| `500`           | Сохранить `x-request-id`; внутренние подробности намеренно скрыты                     |

Ограничения частоты запросов зависят от конфигурации инсталляции и неодинаково охватывают маршруты. Ответ `429` не задает универсальное время сброса, а текущий общий контракт ошибок не обещает заголовок `Retry-After`. Используйте ограниченную экспоненциальную задержку со случайным разбросом и прекращайте попытки после заданного лимита.

## Явные повторные попытки для изменяющих операций[​](#make-mutation-retries-explicit "Прямая ссылка на Явные повторные попытки для изменяющих операций")

Классифицируйте каждую операцию до ее повтора:

* операции чтения обычно можно повторять в пределах ограниченной политики;
* удаление часто естественно сходится к одному состоянию, но проверяйте конкретный эндпоинт;
* создание, выполнение, повторная доставка и другие вызовы с побочными эффектами нельзя повторять только потому, что клиент потерял ответ;
* один метод HTTP не доказывает идемпотентность на уровне приложения.

`POST /v1/sandboxes` поддерживает `Idempotency-Key`. Повторно используйте один ключ для повторных попыток одного логического создания; новый ключ означает новую песочницу. Это контракт конкретной операции, а не общий заголовок идемпотентности шлюза.

Выполнение команды со стримингом не имеет ключа идемпотентности или курсора возобновления. Если его SSE-соединение закрылось без события `exit`, проверьте внешнее состояние до повторной отправки команды. Для работы, которая должна пережить отключение клиента, запустите фоновый процесс и подключайтесь к нему.

## Обработка асинхронной работы по наблюдаемому состоянию[​](#handle-asynchronous-work-by-observed-state "Прямая ссылка на Обработка асинхронной работы по наблюдаемому состоянию")

Разные операции завершаются на разных границах:

* ответ команды с буферизацией завершается после выхода команды и возврата собранного вывода;
* создание песочницы может вернуться после запуска VM, пока настройка репозитория или другая подготовка еще выполняется;
* ответ с фоновой задачей определяет долговременную фоновую работу, состояние которой можно читать отдельно;
* принятый вебхук автоматизации подтверждает постановку в очередь, а не успех действия;
* завершающие сообщения SSE и WebSocket, а не само закрытие соединения, подтверждают завершение команды или процесса.

API фоновых задач уровня аккаунта предоставляет получение списка, чтение и отмену:

```
GET    /v1/jobs
GET    /v1/jobs/{id}
DELETE /v1/jobs/{id}
```

Задача сообщает `status`, `progress_pct`, опциональные `result` или `error` и временные метки. Выполняйте опрос с ограниченным интервалом до `done`, `failed` или `cancelled`. Отмена принимается только пока задача находится в `pending` или `running`; не считайте ее откатом эффектов, которые обработчик задачи уже успел зафиксировать.

Предпочитайте состояние конкретной функции, когда оно точнее записи задачи. Например, дождитесь `provisioning.status` песочницы, прежде чем считать настройку репозитория готовой, и проверяйте запуск автоматизации, чтобы узнать результат действия.

## Выбор контракта обмена данными в реальном времени по поведению при разрыве соединения[​](#choose-the-realtime-contract-by-disconnect-behavior "Прямая ссылка на Выбор контракта обмена данными в реальном времени по поведению при разрыве соединения")

| Задача                          | Контракт                         | Граница завершения и переподключения                                                                                       |
| ------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Постепенный вывод одной команды | SSE `exec-stream`                | `exit` подтверждает завершение; повторный POST запускает еще одну команду                                                  |
| Следить за фоновым процессом    | WebSocket подключения к процессу | Процесс переживает разрыв соединения; переподключение включает ограниченное воспроизведение, способное повторить фрагменты |
| Интерактивная оболочка          | WebSocket терминала              | `exited` завершает один PTY; переподключение создает новый PTY без воспроизведения платформой                              |
| Один детерминированный ответ    | REST `exec` с буферизацией       | HTTP-ответ приходит после завершения; вывод может быть ограничен по размеру                                                |

События вывода — это фрагменты, а не построчные записи. Сохраняйте порядок внутри одного соединения и используйте декодеры, которые обрабатывают данные по частям, там, где протокол переносит исходные байты. Общий поток событий продукта и глобальный порядок между песочницами и соединениями отсутствуют.

Паттерны восстановления описаны на странице [Стриминг и обмен данными в реальном времени](/developers/streaming-and-realtime.md), точные фреймы приведены на странице [Протоколы песочницы для обмена данными в реальном времени](/api-reference/realtime.md).

## Использование MCP для управления платформой[​](#use-mcp-as-a-control-plane "Прямая ссылка на Использование MCP для управления платформой")

Эндпоинт шлюза `/mcp` — MCP-сервер с сохранением состояния на Streamable HTTP. MCP-клиент выполняет обычный handshake `initialize`, вызывает `tools/list` и использует возвращенные схемы для `tools/call`. Инструменты чтения и записи работают с аутентифицированным аккаунтом.

Этот эндпоинт подходит, когда агент должен обнаруживать действия платформы. Он отличается от [MCP-хостинга](/hosted-mcp.md), где Just Run запускает выбранный или предоставленный вами сервер. MCP управления платформой может содержать инструменты `hosted_mcp_*`, управляющие такими инстансами Hosted MCP.

Предпочитайте актуальный `tools/list` жестко заданному каталогу. Некоторые инструменты зависят от функций инсталляции — хранилища, доступа к каталогу навыков или Hosted MCP; наличие в списке не гарантирует, что соответствующая функция включена. Обрабатывайте ошибки инструментов MCP по контракту MCP, а не как тела ошибок REST.

Выполнение команд через MCP происходит с буферизацией. Если нужны постепенный вывод, подключение к процессу или терминал, используйте собственный REST API вместе с контрактами для работы в реальном времени.

## Сгенерированные клиенты как артефакты сборки[​](#treat-generated-clients-as-build-artifacts "Прямая ссылка на Сгенерированные клиенты как артефакты сборки")

Загружаемый документ OpenAPI 3.1 генерируется из текущих схем Rust и точного публичного списка разрешенных операций. Он намеренно неполон и исключает эндпоинты администратора, оператора, проверки состояния, метрик и внутренней передачи данных. Генерируйте и проверяйте из него типы, но не приписывайте сгенерированному типу поведение повторных попыток, пагинации, ожидания или управления учетными данными.

Сообщения MCP, проверка вебхуков, фреймы протоколов реального времени и адаптер E2B описаны в отдельных справочниках, написанных вручную. Они не являются операциями OpenAPI собственного REST API.

Сейчас Just Run не публикует поддерживаемый собственный Python SDK. Путь через [совместимость с E2B](/developers/clients/e2b-compatibility.md) использует официальный пакет Python точной версии, покрытой набором тестов репозитория. Новые интеграции обычно следует начинать с собственного REST API.

## Планирование изменений контракта[​](#plan-for-contract-change "Прямая ссылка на Планирование изменений контракта")

Префикс `/v1` обозначает текущее пространство имен собственного REST API; сам по себе он не обещает семантического версионирования или графика устаревания. Пока отдельная политика не опубликует явный срок поддержки:

1. Закрепляйте или архивируйте входной документ OpenAPI, использованный для генерации клиентских типов.
2. Проверяйте различия в сгенерированных файлах до их принятия.
3. Допускайте появление новых полей в ответах и не обрабатывайте недокументированные значения перечислений исчерпывающим образом без запасного варианта.
4. Проверяйте важные сценарии на целевой инсталляции до внедрения.
5. Читайте [Историю изменений](/changelog) и заметки о миграции при изменениях поведения.

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

## Контрольный список интеграции для рабочей среды[​](#production-integration-checklist "Прямая ссылка на Контрольный список интеграции для рабочей среды")

Перед включением операций записи в рабочей среде:

1. Запишите целевой адрес и владельца аккаунта.
2. Выдайте клиенту минимальные права персонального токена и срок действия.
3. Перечислите каждую изменяющую операцию и определите, можно ли и как ее повторять.
4. Определите конечные состояния для используемых фоновых задач, подготовки, запусков автоматизаций и потоков в реальном времени.
5. Ограничьте опрос, задержки между повторами, таймауты, конкурентность и сохраняемый вывод.
6. Логируйте `x-request-id`, но не учетные данные, значения секретов или подписанные URL.
7. Закрепите сгенерированные контракты и протестируйте поведение при обновлении.
8. Определите очистку для каждого созданного интеграцией ресурса.

## Подробнее об интеграции[​](#explore-developers "Прямая ссылка на Подробнее об интеграции")

* [Основы работы с API](/developers/api-fundamentals.md) — адрес, заголовки, контекст аккаунта, ошибки, ID запросов и идемпотентность создания песочницы.
* [Стриминг и обмен данными в реальном времени](/developers/streaming-and-realtime.md) — выбор способа передачи, завершение, воспроизведение и поведение при переподключении.
* [Длительные операции](/developers/long-running-operations) — фоновые задачи, опрос, прогресс, отмена и готовность конкретных функций.
* [Генерация типов OpenAPI](/developers/clients/openapi.md) — загрузка, проверка, генерация и контроль объявлений типов TypeScript.
* [Совместимость с E2B](/developers/clients/e2b-compatibility.md) — закрепленная целевая версия SDK, преобразованное поведение и намеренные пробелы.
* [MCP управления платформой](/developers/mcp-control-plane) — безопасное подключение агентов и выбор инструментов MCP.
* [Ошибки и ограничения частоты запросов](/developers/errors-and-rate-limits) — классификация сбоев и ограниченное восстановление.
* [Версионирование и устаревание API](/developers/versioning-and-deprecations) — политика изменения контракта по мере ее формализации.
* [Справочник API](/api-reference.md) — точные контракты REST, вебхуков, MCP и протоколов реального времени.
* [Персональные токены](/accounts/personal-access-tokens.md) — привязка к аккаунту, права, срок действия и отзыв.
* [Быстрый старт с API](/getting-started/api.md) — создание песочницы, выполнение команды и удаление через cURL.
