Commencez par une casa

Ce guide utilise l’API REST avec curl. Chaque étape fonctionne de la même façon avec MCP : les deux proviennent du même catalogue d’opérations et passent les mêmes contrôles d’autorisation que l’application.

Créer une connexion

Connectez-vous, ouvrez Développeurs dans le tableau de bord (propriétaires et administrateurs de l’espace uniquement) et choisissez Nouvelle connexion. Sélectionnez API REST, gardez les choix de lecture seule (workspaces:read, catalog:read, worlds:read) et ajoutez, pour ce guide, worlds:write et worlds:publish. Le jeton n’apparaît qu’une fois : copiez-le tout de suite dans votre coffre de secrets.

La carte Référence de cette page donne l’URL de base REST, le point d’accès MCP et le contrat OpenAPI.

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

Trouver votre espace

Un jeton appartient à un seul espace. Listez-le pour obtenir son identifiant et votre rôle :

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

Demandez ensuite ce que cet espace peut faire maintenant. Chaque capacité indique si elle est implémentée, simulée, bloquée par des identifiants manquants ou en attente d’une décision :

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

Créer une casa brouillon

Choisissez un modèle du catalogue (GET /catalog/templates), puis créez un brouillon. Chaque écriture exige une Idempotency-Key de 16 à 128 caractères ; réessayer avec la même clé et le même corps renvoie le résultat initial sans créer une seconde 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"}}'

Modifier avec soin

Lisez d’abord la casa. La réponse comporte un en-tête ETag : renvoyez-le comme If-Match avec votre modification. Si quelqu’un a modifié le brouillon entre-temps, vous recevez 412 revision_conflict et rien ne change.

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

Publier et attendre la tâche

La publication prend les valeurs exactes draft_revision_id et draft_digest de la dernière lecture : vous publiez ce que vous avez vérifié. Elle répond 202 avec une tâche ; la version précédente reste en ligne jusqu’à la réussite de la nouvelle construction.

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’interrogez pas plus vite que next_poll_after_seconds. Une tâche completed renvoie la canonical_url de la page en ligne. Préférez un webhook à l’interrogation répétée dès que vous avez plus de quelques tâches.

Pour aller plus loin

• Authentification et portées : les autorisations de chaque opération.
• MCP : connecter un client agent aux mêmes opérations.
• Référence API : conventions, erreurs et contrat OpenAPI.