Un contrat pour vos casas

Le contrat lisible par machine

GET /api/v1/openapi.json renvoie un document OpenAPI 3.1 décrivant exactement ce qu’implémente ce déploiement : chaque chemin, schéma, portée requise et réponse, ainsi que les événements webhook. Il provient du catalogue d’opérations en cours, qui produit aussi les outils MCP : REST et MCP restent ainsi alignés.

curl -s "https://<your host>/api/v1/openapi.json"

L’interface couvre casas et brouillons, révisions et publications, billets, catalogue de modèles, imports, portefeuilles et lots, domaines et plans DNS, transferts de courrier, réglages d’inscription et de contact, sources sociales, statistiques, promotions, facturation, membres d’équipe et webhooks. GET /workspaces/{id}/capabilities indique les éléments actifs, simulés ou en attente d’identifiants dans votre espace.

Des nouvelles tentatives maîtrisées

• Chaque mutation exige un en-tête Idempotency-Key de 16 à 128 caractères. Répéter une requête avec la même clé et le même corps renvoie le résultat initial avec Idempotent-Replayed: true. La même clé avec un autre corps produit 409 idempotency_key_reused.
• Modifier une casa exige If-Match avec l’ETag de la dernière lecture. Une valeur périmée produit 412 revision_conflict et rien ne change.
• La publication prend exactement les revision_id et expected_digest lus : vous publiez ce que vous avez vérifié.

Les opérations longues deviennent des tâches

Publication, lots et autres opérations lentes répondent 202 avec une tâche. Interrogez GET /workspaces/{id}/jobs/{job_id} sans dépasser le rythme next_poll_after_seconds, ou abonnez-vous aux webhooks job.updated. Accepté ne signifie pas terminé : lisez le state, les compteurs et l’error avant d’annoncer une réussite.

Les erreurs décrivent les problèmes

Elles utilisent application/problem+json avec un code stable, un title localisé, le request_id et retryable. Basez vos branchements sur code, jamais sur le texte du titre.

{
  "type": "https://<your host>/problems/insufficient_scope",
  "title": "This token does not include the permission this action needs.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

Listes et limites

• Les points d’accès de liste acceptent limit (jusqu’à 100) et un cursor de la page précédente.
• Chaque jeton d’espace autorise 120 lectures et 30 écritures par minute. Au-delà, vous recevez 429 avec un en-tête Retry-After.
• Conservez les champs de réponse inconnus : de nouveaux champs peuvent apparaître sans changement de version.