zSync API.
REST + Webhooks für Pipeline- und Connector-Steuerung. JSON-only. Versioniert via Header apps3k-version: 2024-12-01.
Authentifizierung
Alle Requests verlangen einen Bearer-Token im Authorization-Header. Tokens werden im Workspace-Settings unter API Keys erzeugt und können auf bestimmte Scopes (events:read, bookings:write …) eingeschränkt werden.
https://api.apps3k.ch/zsync/v3 Fehler
Wir verwenden konventionelle HTTP-Statuscodes. 2xx = Erfolg, 4xx = Client-Fehler (validate, fix, retry), 5xx = Server-Fehler (idempotent retry mit Backoff).
| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request | Body- oder Query-Validierung fehlgeschlagen. Details in errors[]. |
| 401 | unauthorized | Token fehlt oder ist ungültig. |
| 403 | forbidden_scope | Token hat den benötigten Scope nicht. |
| 404 | not_found | Ressource existiert nicht oder gehört nicht zu diesem Workspace. |
| 409 | conflict | Versionskonflikt; Idempotency-Key ggf. erneut prüfen. |
| 429 | rate_limited | Limit überschritten, Retry-After Header beachten. |
| 503 | temporarily_unavailable | Backend kurz nicht erreichbar; idempotent retry empfohlen. |
Rate-Limits
300 req/min pro Token. Pipeline-Runs zählen separat: 100/min. Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset in jeder Antwort.
POST /pipelines/{id}/runs
Triggert einen neuen Pipeline-Lauf für die angegebene Pipeline. Der Run wird asynchron eingereiht; die Antwort enthält die Run-ID für Status-Polling oder Webhook-Subscriptions.
Pfad-Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| id | string · uuid | Required | Pipeline-ID (Pfadparameter). |
Body-Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| trigger | enum | Required | manual, schedule, webhook, backfill. |
| since | string · ISO 8601 | Optional | Start-Zeitstempel für Backfill-Runs. Default: letzter erfolgreicher Run. |
| dry_run | boolean | Optional | Wenn true: nur Validierung, keine Mutationen. Default: false. |
Antworten
| Status | Beschreibung |
|---|---|
| 202 | Run wurde akzeptiert und eingereiht. |
| 400 | Trigger-Wert ungültig oder Pipeline pausiert. |
| 404 | Keine Pipeline mit dieser ID. |
| 409 | Bereits ein Run aktiv (concurrency=1). |