Sandbox API — Clarity Developer

Quickstart

One key. One observable request.

Lege im Developer Workspace zuerst eine Sandbox-App mit dem kleinsten benötigten Scope an. Ein Schlüssel wird genau einmal angezeigt, läuft nach 180 Tagen ab und gehört ausschließlich auf deinen Server.

status.sh

curl https://clarity.audecius.com/api/developer/v1/status \
  --header "Authorization: Bearer $CLARITY_API_KEY" \
  --header "X-Request-ID: quickstart-01"

Version 2026-08-12

Neun Operationen. Keine versteckte Wirkung.

GET /status: Projekt, Umgebung, gewährte Scopes und API-Version prüfen.
Scope · status.read
GET /profile: Die Developer-Projektidentität und ihre expliziten Datengrenzen lesen.
Scope · profile.read
GET /sessions: Operatorveröffentlichte Developer-Termine ohne Zugangslinks abrufen – niemals private Clarity Sessions einer Person.
Scope · sessions.read
GET /usage: 30-Tage-Nutzung ausschließlich für das authentifizierte Sandbox-Projekt lesen.
Scope · usage.read
GET /webhooks: Eigene Endpunkte und ihren letzten Zustellstatus prüfen.
Scope · webhooks.read
GET /tools: Menschlich geprüfte, deklarative Tool-Manifeste aus der Bibliothek lesen.
Scope · tools.read
POST /tools/validate: Ein clarity.tool/v1-Manifest deterministisch prüfen.
Scope · tools.validate
POST /tools/preview: Ein nicht ausführendes Review-Paket mit Safety-Grenze erzeugen.
Scope · tools.preview
POST /webhooks/test: Ein signiertes Sandbox-Ereignis und die Verifikationsdaten erzeugen.
Scope · webhooks.test

validate-tool.sh

curl https://clarity.audecius.com/api/developer/v1/tools/validate \
  --request POST \
  --header "Authorization: Bearer $CLARITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "manifest": {
      "schema": "clarity.tool/v1",
      "name": "Study outline",
      "entry": "study.outline",
      "consequenceClass": "C1",
      "permissions": ["profile.read"],
      "display": {
        "layout": "list",
        "icon": "list.bullet.rectangle",
        "color": "blue",
        "columns": [
          { "name": "Outline item", "type": "text" },
          { "name": "Done", "type": "toggle" }
        ]
      }
    }
  }'

Authentication

Secrets stay server-side.

Format: Authorization: Bearer clt_test_…
Speicherung: Nur der SHA-256-Hash liegt in Clarity. Das vollständige Secret erscheint einmal bei der Ausgabe.
Rotation: Erzeuge einen neuen Schlüssel, aktualisiere deinen Server und widerrufe danach den alten.
Projektgrenze: Jeder Schlüssel gehört genau einer App, einer Umgebung und einer serverbestätigten Scope-Liste.
Tool-Berechtigungen: Native Tool-Manifeste dürfen derzeit ausschließlich profile.read und sessions.read beantragen. Account-, Health-, School- und Family-Daten bleiben geschlossen.

Operational contract

Every failure has a stable shape.

400: Ungültiges JSON oder eine unbekannte Eingabe.
401: Key fehlt, ist ungültig, abgelaufen oder widerrufen.
403: Der erforderliche Scope fehlt.
413: Der Request überschreitet 64 KB.
422: Das Manifest verletzt den clarity.tool/v1-Vertrag.
429: Mehr als 120 Requests pro Minute und Key; Reset steht im Response-Header.
503: Die Sandbox kann die Autorisierung nicht sicher bestätigen und bleibt geschlossen.

Jede Antwort enthält X-Request-ID; Limits werden über X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset sichtbar. Requests und Fehler werden täglich pro Projekt und Operation aggregiert.