Начните с одной casa

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

Создайте подключение

Войдите, откройте Разработчикам в панели управления (только для владельцев и администраторов рабочего пространства) и выберите Новое подключение. Выберите REST API, сохраните разрешения по умолчанию только для чтения (workspaces:read, catalog:read, worlds:read) и для этого руководства добавьте worlds:write и worlds:publish. Токен показывается один раз, поэтому сразу скопируйте его в хранилище секретов.

Карточка Справочник на той же странице показывает базовый URL REST, конечную точку MCP и контракт OpenAPI.

export BASE="https://<your host>/api/v1"
export TOKEN="sw_rest_..."

Найдите рабочее пространство

Токен принадлежит ровно одному рабочему пространству. Запросите список, чтобы получить его идентификатор и свою роль:

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces"
export WS="<data[0].id>"

Затем запросите, что это пространство может делать сейчас. Каждая возможность сообщает, реализована ли она, имитируется, заблокирована из-за отсутствующих учётных данных или ждёт решения:

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/capabilities"

Создайте черновик casa

Выберите дизайн из каталога (GET /catalog/templates), затем создайте черновик. Каждая запись требует Idempotency-Key длиной от 16 до 128 символов; повтор с тем же ключом и телом возвращает исходный результат вместо второй casa.

curl -s -X POST "$BASE/workspaces/$WS/worlds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"my-first-casa","template_id":"pizza",
       "profile":{"display_name":"My first casa","bio":"Hello from the API.","content_language":"en"}}'

Редактируйте безопасно

Сначала прочитайте casa. Ответ содержит заголовок ETag; передайте его обратно как If-Match вместе с изменением. Если кто-то успел отредактировать черновик, вы получите 412 revision_conflict, и ничего не изменится.

curl -s -i -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/worlds/$WORLD"

curl -s -X PATCH "$BASE/workspaces/$WS/worlds/$WORLD" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H 'If-Match: W/"<etag>"' \
  -H "Content-Type: application/json" \
  -d '{"profile":{"bio":"Edited over the API."}}'

Опубликуйте и дождитесь задания

Публикация принимает точные draft_revision_id и draft_digest из последнего чтения, чтобы вы опубликовали проверенное. Она отвечает 202 с заданием; предыдущая версия остаётся доступной до успешной новой сборки.

curl -s -X POST "$BASE/workspaces/$WS/worlds/$WORLD/publications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -H "Content-Type: application/json" \
  -d '{"revision_id":"<draft_revision_id>","expected_digest":"<draft_digest>"}'

curl -s -H "Authorization: Bearer $TOKEN" "$BASE/workspaces/$WS/jobs/$JOB"

Опрашивайте не чаще, чем указано в next_poll_after_seconds. Задание completed возвращает canonical_url действующей страницы. Когда заданий становится больше нескольких, предпочтите вебхук опросу.

Куда двигаться дальше

• Аутентификация и области доступа: разрешения для каждой операции.
• MCP: подключение агента-клиента к тем же операциям.
• Справочник API: соглашения, ошибки и контракт OpenAPI.