Empieza con una casa pequeñita

Este recorrido usa la API REST con curl. Cada paso funciona igual por MCP, porque ambos se generan a partir de un único catálogo de operaciones y pasan por las mismas comprobaciones de permisos que la aplicación.

Crea una conexión

Inicia sesión, abre Desarrolladores en el panel (solo propietarios y administradores del espacio) y elige Nueva conexión. Selecciona API REST, conserva los permisos de solo lectura predeterminados (workspaces:read, catalog:read, worlds:read) y, para este recorrido, añade worlds:write y worlds:publish. El token se muestra una sola vez: guárdalo enseguida en tu almacén de secretos.

La tarjeta Referencia de esa misma página muestra la URL base de REST, el endpoint MCP y el contrato OpenAPI.

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

Encuentra tu espacio de trabajo

Un token pertenece exactamente a un espacio de trabajo. Lístalo para obtener su id y tu rol:

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

Después pregunta qué puede hacer ese espacio ahora mismo. Cada capacidad indica si está implementada, simulada, bloqueada por falta de credenciales o pendiente de una decisión:

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

Crea una casa en borrador

Elige un diseño del catálogo (GET /catalog/templates) y crea un borrador. Cada escritura necesita una Idempotency-Key de 16 a 128 caracteres; si repites la solicitud con la misma clave y el mismo cuerpo, recibes el resultado original en lugar de una 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":"mi-primera-casa","template_id":"pizza",
       "profile":{"display_name":"Mi primera casa","bio":"Hola desde la API.","content_language":"es"}}'

Edítalo con seguridad

Lee primero la casa. La respuesta incluye una cabecera ETag; devuélvela como If-Match junto con tu cambio. Si alguien editó el borrador mientras tanto, recibes 412 revision_conflict y no cambia nada.

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 desde la API."}}'

Publica y espera el trabajo

Publicar requiere el draft_revision_id y el draft_digest exactos de la última lectura, así publicas lo que revisaste. La respuesta es 202 con un trabajo; la versión anterior sigue en línea hasta que la nueva se genera bien.

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"

No consultes más a menudo que next_poll_after_seconds. Un trabajo completed devuelve la canonical_url de la página publicada. Cuando tengas más de unos pocos trabajos, usa un webhook en lugar de consultar.

Siguientes pasos

• Autenticación y permisos: qué permisos necesita cada operación.
• MCP: conecta un cliente de agente a las mismas operaciones.
• Referencia de la API: convenciones, errores y el contrato OpenAPI.