Comece com um mundinho

Este passo a passo usa a API REST com curl. Cada etapa funciona do mesmo jeito via MCP, porque os dois são gerados a partir de um único catálogo de operações e passam pelas mesmas verificações de permissão do aplicativo.

Crie uma conexão

Entre na sua conta, abra Desenvolvedores no painel (apenas proprietários e administradores do espaço) e escolha Nova conexão. Selecione API REST, mantenha as permissões de leitura padrão (workspaces:read, catalog:read, worlds:read) e, para este passo a passo, adicione worlds:write e worlds:publish. O token aparece uma única vez: guarde-o logo no seu cofre de segredos.

O cartão Referência da mesma página mostra a URL base da REST, o endpoint MCP e o contrato OpenAPI.

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

Encontre seu espaço de trabalho

Um token pertence a exatamente um espaço de trabalho. Liste-o para obter o id e o seu papel:

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

Depois pergunte o que esse espaço consegue fazer agora. Cada capacidade informa se está implementada, simulada, bloqueada por falta de credenciais ou aguardando uma decisão:

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

Crie uma casa em rascunho

Escolha um design no catálogo (GET /catalog/templates) e crie um rascunho. Toda escrita precisa de uma Idempotency-Key de 16 a 128 caracteres; repetir a requisição com a mesma chave e o mesmo corpo devolve o resultado original em vez de uma segunda 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":"minha-primeira-casa","template_id":"pizza",
       "profile":{"display_name":"Minha primeira casa","bio":"Olá pela API.","content_language":"pt-BR"}}'

Edite com segurança

Leia a casa primeiro. A resposta traz um cabeçalho ETag; envie-o de volta como If-Match com a sua alteração. Se alguém editou o rascunho nesse meio-tempo, você recebe 412 revision_conflict e nada muda.

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":"Editado pela API."}}'

Publique e aguarde o trabalho

Publicar exige o draft_revision_id e o draft_digest exatos da última leitura, assim você publica o que conferiu. A resposta é 202 com um trabalho; a versão anterior continua no ar até a nova ser gerada com sucesso.

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"

Não consulte mais rápido que next_poll_after_seconds. Um trabalho completed devolve a canonical_url da página publicada. Quando tiver mais do que alguns trabalhos, prefira um webhook a consultas repetidas.

Próximos passos

• Autenticação e permissões: quais permissões cada operação exige.
• MCP: conecte um cliente de agente às mesmas operações.
• Referência da API: convenções, erros e o contrato OpenAPI.