Ein Vertrag für deine casas

Der maschinenlesbare Vertrag

GET /api/v1/openapi.json liefert ein OpenAPI-3.1-Dokument mit genau dem Funktionsumfang dieser Bereitstellung: alle Pfade, Schemas, erforderlichen Berechtigungsbereiche und Antworten sowie Webhookereignisse. Es wird aus dem laufenden Vorgangskatalog erzeugt, der auch die MCP-Werkzeuge erstellt. So laufen REST und MCP nie auseinander.

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

Die Schnittstelle umfasst casas und Entwürfe, Versionen und Veröffentlichungen, Beiträge, casita-Katalog, Importe, Portfolios und Stapelläufe, Domains und DNS-Pläne, E-Mail-Weiterleitung, Anmelde- und Kontakteinstellungen, soziale Quellen, Analysen, Werbung, Abrechnung, Teammitglieder und Webhooks. GET /workspaces/{id}/capabilities sagt, was davon in deinem Arbeitsbereich aktiv, simuliert oder wegen fehlender Zugangsdaten ausstehend ist.

Bewusste Wiederholungen

• Jede Änderung braucht einen Idempotency-Key-Header mit 16 bis 128 Zeichen. Dieselbe Anfrage mit gleichem Schlüssel und Inhalt liefert das ursprüngliche Ergebnis mit Idempotent-Replayed: true. Derselbe Schlüssel mit anderem Inhalt ergibt 409 idempotency_key_reused.
• Änderungen an einer casa brauchen If-Match mit dem ETag des letzten Lesevorgangs. Ein veralteter Wert ergibt 412 revision_conflict, und nichts ändert sich.
• Die Veröffentlichung nimmt genau revision_id und expected_digest aus deinem Lesevorgang, damit du das Geprüfte veröffentlichst.

Lange Arbeit ist ein Auftrag

Veröffentlichungen, Stapelläufe und andere langsame Vorgänge antworten mit 202 und einem Auftrag. Frage GET /workspaces/{id}/jobs/{job_id} nicht schneller ab als next_poll_after_seconds oder abonniere job.updated-Webhooks. Angenommen bedeutet nicht fertig: Lies state, Zähler und error des Auftrags, bevor du Erfolg meldest.

Fehler sind Problemdetails

Fehler nutzen application/problem+json mit stabilem code, lokalisiertem title, request_id und retryable. Verzweige anhand von code, niemals anhand des Titeltexts.

{
  "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" }
}

Listen und Grenzen

• Listenendpunkte nehmen limit (bis 100) und einen cursor der vorherigen Seite.
• Jedes Arbeitsbereichstoken darf pro Minute 120 Lese- und 30 Schreibvorgänge ausführen. Darüber erhältst du 429 mit einem Retry-After-Header.
• Bewahre unbekannte Antwortfelder: Neue Felder können ohne Versionswechsel hinzukommen.