CrewIO Developer API Reference

REST API Dokumentation

Detaillierte Reference für alle Endpoints, Scopes, Fehlercodes und Webhook-Events. Alle Beispiele basieren auf der produktiven Base URL https://api.crewio.co/api/developer/v1/ und der gleichen Quelle wie die OpenAPI-Spec.

OpenAPI JSON API Roadmap Integration anlegen Direkt zu Endpoints

Stabilitäts-Level

Aktuelle Major-Version: v1. Breaking Changes nur mit Vorankündigung und Major-Bump.

Minor-Versionen ergänzen Felder und Endpoints rückwärtskompatibel.

Base URL

https://api.crewio.co/api/developer/v1/

Alle Endpoints sind unter dieser Base URL erreichbar. Pfade in der Reference sind relativ.

Zugriff

ProPass oder das API-Access-Add-on aktiviert die Core-API.

Webhooks erfordern ProPass oder beide Add-ons api_access_plus + webhooks_access.

Authentifizierung

Jeder Request wird über einen Crewio-API-Key authentifiziert. Keys sind verein-scoped und tragen die im Dashboard ausgewählten Scopes. Verloren gegangene Keys lassen sich nicht wiederherstellen — Rotation per Neuanlage und Löschen des alten Keys.

Authorization-Header

Empfohlene Form: Bearer-Token.

curl 'https://api.crewio.co/api/developer/v1/events' \
  -H 'Authorization: Bearer crw_live_…'

Alternative: x-crewio-api-key

Für Systeme, die keine Authorization-Header setzen können (z. B. statische Webhooks aus älteren Tools).

curl 'https://api.crewio.co/api/developer/v1/events' \
  -H 'x-crewio-api-key: crw_live_…'

Schlüssel verwalten

Erstellen, Scopes setzen, deaktivieren.

Im Verein-Dashboard unter Integrationen verwalten. Sichtbar nur einmal — danach gehasht abgelegt.

Dashboard öffnen

Scopes

Jeder API-Key trägt eine Whitelist von Scopes. Endpoints prüfen den geforderten Scope serverseitig. Verein-Scoping ist implizit: ein Key kann nur den Verein lesen/schreiben, dem er gehört.

Scope	Beschreibung
events:read	Events lesen.
events:create	Events erstellen (zählt aufs Plan-Limit).
events:write	Events aktualisieren und syncen.
events:delete	Events soft-löschen.
roles:read	Rollenkatalog lesen.
roles:write	Rollen anlegen, ändern, löschen.
shifts:read	Schichten lesen.
shifts:write	Schichten anlegen/ändern/löschen.
helpers:read	Helfer lesen, suchen und filtern.
helpers:write	Helfer bulk upserten und Event-Zugriff setzen.
messages:read	Event-Nachrichten lesen.
messages:write	Nachrichten und Broadcasts erstellen.
assignments:read	Schichtbesetzung lesen.
assignments:write	Schichtbesetzung upserten und Status setzen.
availability:read	Verfügbarkeits-Umfragen lesen.
availability:write	Verfügbarkeits-Umfragen und Antworten schreiben.
webhooks:read	Webhook-Konfiguration und Delivery-Logs lesen.
webhooks:write	Webhooks erstellen und deaktivieren.
automation:read	Automation-Workflows lesen.
automation:write	Automation-Workflows anlegen/ändern und manuell triggern.

Request- und Response-Header

Request-Header

Header	Pflicht	Beschreibung
Authorization	ja	Bearer mit Crewio-API-Key (alternativ Header x-crewio-api-key).
Content-Type	ja	Pflicht für alle POST/PATCH-Requests mit Body.
Idempotency-Key	nein	Wird derzeit zur Beobachtung geloggt, künftig für Replay-Schutz aktiv. Empfehlung: bei POST setzen.
x-crewio-api-key	nein	Alternative zur Bearer-Authentifizierung.

Response-Header

Header	Beschreibung
x-crewio-request-id	Eindeutige Request-ID für Support-Tickets.
x-crewio-ratelimit-limit	Limit für das aktuelle Fenster.
x-crewio-ratelimit-remaining	Verbleibende Calls im Fenster.
x-crewio-ratelimit-reset	Sekunden bis Reset.

ProPass

180 req/min

Pro API-Key. Burst von 30 zusätzlichen Requests in 5 Sekunden.

Developer API Add-on

600 req/min

Pro API-Key. Empfohlen für Sync-Jobs und Plattformen.

Retry-Policy

Bei 429: Wartezeit aus x-crewio-ratelimit-reset beachten.

Bei 5xx: idempotente Operationen mit Exponential Backoff (1s, 2s, 4s, max. 30s).

Pagination & Filterung

Pattern

GET-Listen liefern in der Regel ein Wurzelobjekt, z. B. { "events": [...] }.
/helpers unterstützt limit/offset (Standard 100). Für andere Endpoints wird typischerweise limit + ressourcen-spezifische Filter verwendet.
Maximale Page-Size: 200. Größere Pagination per Cursor folgt in einer kommenden Minor-Version.
Sortierung ist endpoint-spezifisch (Events nach start_date, Schichten nach start_time, Nachrichten nach created_at desc).

Beispiel: /helpers mit Pagination

curl 'https://api.crewio.co/api/developer/v1/helpers?limit=100&offset=200&search=max' \
  -H 'Authorization: Bearer crw_live_…'

Fehlerformat & Status Codes

Fehler-Responses sind immer JSON. Pflichtfeld error, optional upgrade_hint, recommended_add_ons, code und upgrade_cta bei Plan/Add-on-Gates.

Status	Bedeutung	Aktion
400	Bad Request	Validation fehlgeschlagen. Erste Fehlermeldung steht in error.
401	Unauthorized	API-Key fehlt, ungültig oder widerrufen.
403	Forbidden	Scope, Plan/Add-on oder Verein-Mismatch. Upgrade-Hinweis im upgrade_hint-Feld.
404	Not Found	Ressource nicht gefunden oder nicht im Verein des Keys.
409	Conflict	Doppelter Datensatz oder konkurrierender Schreibvorgang.
422	Unprocessable Entity	Logischer Fehler nach Validation (z. B. Datumsreihenfolge).
429	Too Many Requests	Rate-Limit erreicht. Backoff aus x-crewio-ratelimit-reset nutzen.
500	Server Error	Interner Fehler. Idempotent retryen, sonst Support kontaktieren.

Fehler-Body

{
  "code": "FEATURE_FORBIDDEN",
  "error": "Webhooks benötigen ProPass oder beide Add-ons.",
  "upgrade_hint": "pro_or_api_and_webhooks_addons",
  "recommended_add_ons": ["api_access_plus", "webhooks_access"]
}

Webhooks

Webhooks pushen Änderungen in Echtzeit an deine Endpoints. Sie sind signiert (HMAC-SHA256 mit dem Signing-Secret aus POST /webhooks), werden bei Fehlern automatisch retryed und im Delivery-Log archiviert.

Retry-Policy

Bis zu 8 Versuche pro Delivery.
Backoff: 30 s, 1 min, 5 min, 15 min, 1 h, 6 h, 12 h, 24 h.
HTTP-2xx = erfolgreich. 4xx/5xx triggern Retry.

Header pro Delivery

X-Crewio-Event: helper.confirmed
X-Crewio-Delivery-Id: uuid
X-Crewio-Signature: sha256=hex(hmac)
X-Crewio-Timestamp: epoch

Event-Katalog

Event	Beschreibung
event.created	Neues Event wurde angelegt.
event.updated	Event wurde aktualisiert (Daten, Status).
event.deleted	Event wurde soft-gelöscht.
event.started	Event wechselt in den Status active.
event.ended	Event wurde archiviert/beendet.
role.created	Rolle wurde im Event angelegt.
role.updated	Rolle wurde aktualisiert.
role.deleted	Rolle wurde entfernt.
shift.created	Schicht wurde angelegt.
shift.updated	Schichtdaten wurden aktualisiert.
shift.deleted	Schicht wurde entfernt.
shift.changed	Aggregat-Event für Schicht-Updates inkl. Besetzungslage.
helper.registered	Helfer wurde neu erfasst.
helper.granted	Helfer hat Zugriff auf ein Event erhalten.
helper.revoked	Helfer-Zugriff wurde entzogen.
helper.confirmed	Helfer hat Schicht bestätigt.
helper.cancelled	Helfer hat Schicht abgesagt.
assignment.updated	Schichtbesetzung hat sich geändert.
message.created	Nachricht wurde erstellt/versendet.
message.updated	Nachricht wurde aktualisiert.
message.deleted	Nachricht wurde gelöscht.
availability.request.created	Verfügbarkeits-Umfrage wurde gestartet.
availability.response.upserted	Helfer-Antwort wurde gespeichert.
automation.triggered	Automation-Workflow wurde getriggert.

Signatur prüfen

Immer den Rohrequest-Body verwenden.

import crypto from 'node:crypto'

function verifyCrewioSignature(rawBody, signatureHeader, secret) {
  const provided = String(signatureHeader || '')
    .replace(/^sha256=/i, '')
    .trim()
  if (!/^[a-f0-9]{64}$/i.test(provided)) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(provided, 'hex')
  )
}

Endpoint-Reference

Alle Endpoints sind verein-scoped. Path-Parameter sind in der relativen URL angegeben. Felder, die nicht in der Reference stehen, werden ignoriert.

Events

Anlegen, lesen, aktualisieren und synchronisieren von Events.

GET/eventsevents:read

Events listen

Listet Events des aktuellen Vereins. Gefiltert nach Status, sortiert nach Startdatum.

Gate: ProPass oder API-Access-Add-on

Query-Parameter

Name	Typ	Required	Beschreibung
vereinIdquery	uuid	nein	Optionaler Override. Muss zum API-Key passen.
statusquery	enum	nein	draft, active, archived oder cancelled.
limitquery	integer 1-200	nein	Standard 50.

Responses

200Ok

{ "events": [Event] }

403Plan oder Add-on fehlt.

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Response Beispiel

{
  "events": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "verein_id": "00000000-0000-0000-0000-000000000000",
      "name": "Sommerfest 2026",
      "start_date": "2026-08-20",
      "end_date": "2026-08-21",
      "status": "active",
      "updated_at": "2026-05-13T18:21:42.317Z"
    }
  ]
}

POST/eventsevents:create

Event anlegen

Legt ein Event im Verein des API-Keys an. Aktive/Draft-Events prüfen das Event-Limit des Plans.

Gate: Plan-/Capacity-Gate (Limit pro Plan/Add-on)

Request-Body

Name	Typ	Required	Beschreibung
name	string	ja	2–140 Zeichen.
description	string \| null	nein	Bis 4 000 Zeichen.
start_date	date (YYYY-MM-DD)	ja	Startdatum.
end_date	date (YYYY-MM-DD)	ja	Enddatum.
location	string \| null	nein	Bis 240 Zeichen.
location_coordinates	string \| null	nein	Koordinaten z. B. "52.5200,13.4050".
status	enum	nein	Standard "draft". Werte: draft, active, archived, cancelled
auto_confirm_assignments	boolean	nein	Helfer automatisch bestätigen.

Responses

201Erstellt

{
  "event": {
    "id": "11111111-1111-1111-1111-111111111111",
    "verein_id": "00000000-0000-0000-0000-000000000000",
    "name": "Sommerfest 2026",
    "description": null,
    "start_date": "2026-08-20",
    "end_date": "2026-08-21",
    "location": "Vereinsheim",
    "status": "draft",
    "auto_confirm_assignments": false,
    "created_by": "user-uuid",
    "created_at": "2026-05-13T18:21:42.317Z",
    "updated_at": "2026-05-13T18:21:42.317Z"
  }
}

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

403Plan- oder Capacity-Limit erreicht.

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Request Beispiel

{
  "name": "Sommerfest 2026",
  "start_date": "2026-08-20",
  "end_date": "2026-08-21",
  "status": "draft"
}

Emittierte Webhook-Events

event.createdevent.started

GET/events/{eventId}events:read

Event laden

Liest ein einzelnes Event des aktuellen Vereins.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{
  "event": {
    "id": "11111111-1111-1111-1111-111111111111",
    "verein_id": "00000000-0000-0000-0000-000000000000",
    "name": "Sommerfest 2026",
    "description": null,
    "start_date": "2026-08-20",
    "end_date": "2026-08-21",
    "location": "Vereinsheim",
    "status": "draft",
    "auto_confirm_assignments": false,
    "created_by": "user-uuid",
    "created_at": "2026-05-13T18:21:42.317Z",
    "updated_at": "2026-05-13T18:21:42.317Z"
  }
}

404Nicht gefunden

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

PATCH/events/{eventId}events:write

Event ändern

Aktualisiert ausgewählte Felder eines Events.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
name	string	nein	2–140 Zeichen.
description	string \| null	nein	Bis 4 000 Zeichen.
location	string \| null	nein	Bis 240 Zeichen.
start_date	date	nein	Startdatum.
end_date	date	nein	Enddatum.
status	enum	nein	Lifecycle-Status. Werte: draft, active, archived, cancelled

Responses

200Ok

{
  "event": {
    "id": "11111111-1111-1111-1111-111111111111",
    "verein_id": "00000000-0000-0000-0000-000000000000",
    "name": "Sommerfest 2026",
    "description": null,
    "start_date": "2026-08-20",
    "end_date": "2026-08-21",
    "location": "Vereinsheim",
    "status": "draft",
    "auto_confirm_assignments": false,
    "created_by": "user-uuid",
    "created_at": "2026-05-13T18:21:42.317Z",
    "updated_at": "2026-05-13T18:21:42.317Z"
  }
}

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

404Nicht gefunden

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

event.updatedevent.startedevent.ended

DELETE/events/{eventId}events:delete

Event löschen

Soft-Delete des Events. Helfer- und Schichtdaten bleiben für Audit erhalten.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{ "ok": true }

404Nicht gefunden

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

event.deleted

POST/events/syncevents:write

Events synchronisieren

Bulk-Create/Update von bis zu 100 Events in einer Anfrage. Zeilen mit "id" werden aktualisiert, sonst angelegt.

Gate: Plan-/Capacity-Gate (Limit pro Plan/Add-on)

Request-Body

Name	Typ	Required	Beschreibung
items	array<EventSyncItem>	ja	1–100 Events.

Responses

200Ok

{ "created": [Event], "updated": [Event] }

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

403Limit erreicht

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

EventSyncItem enthält die gleichen Felder wie POST /events plus optional "id".
Capacity-Checks werden je neu erstellter Zeile durchgeführt.

Rollen

Rollenkatalog je Event (z. B. Bar, Kasse, Aufbau).

GET/events/{eventId}/rolesroles:read

Rollen listen

Listet alle Rollen für ein Event.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{ "roles": [Role] }

POST/events/{eventId}/rolesroles:write

Rolle anlegen

Erzeugt eine neue Rolle für das Event.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
name	string	ja	1–80 Zeichen.
description	string \| null	nein	Bis 1 000 Zeichen.
color	string \| null	nein	HEX/Token, bis 20 Zeichen.
display_order	integer 0-10 000	nein	Sortier-Index.

Responses

201Erstellt

{ "role": Role }

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

role.created

PATCH/events/{eventId}/roles/{roleId}roles:write

Rolle ändern

Aktualisiert eine bestehende Rolle.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.
roleIdpath	uuid	ja	Rolle-ID.

Request-Body

Name	Typ	Required	Beschreibung
name	string	nein	1–80 Zeichen.
description	string \| null	nein	Bis 1 000 Zeichen.
color	string \| null	nein	Bis 20 Zeichen.
display_order	integer	nein	Sortier-Index.

Responses

200Ok

{ "role": Role }

404Nicht gefunden

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

role.updated

DELETE/events/{eventId}/roles/{roleId}roles:write

Rolle löschen

Löscht eine Rolle. Schichten mit dieser Rolle bleiben erhalten, verlieren aber die Zuordnung.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.
roleIdpath	uuid	ja	Rolle-ID.

Responses

200Ok

{ "ok": true }

Emittierte Webhook-Events

role.deleted

Schichten

Zeitfenster je Rolle, gegen das Plan-Limit für Schichten pro Event abgesichert.

GET/events/{eventId}/shiftsshifts:read

Schichten listen

Listet alle Schichten eines Events nach Startzeit.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{ "shifts": [Shift] }

POST/events/{eventId}/shiftsshifts:write

Schicht anlegen

Erzeugt eine Schicht. Capacity-Limit (Schichten pro Event) wird geprüft.

Gate: Plan-/Capacity-Gate (Limit pro Plan/Add-on)

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
role_id	uuid	ja	Existierende Rolle des Events.
start_time	datetime (ISO 8601)	ja	Schichtbeginn.
end_time	datetime (ISO 8601)	ja	Schichtende.
required_count	integer 1-500	nein	Standard 1.
allow_overbooking	boolean	nein	Mehrfachbesetzung erlauben.
notes	string \| null	nein	Bis 1 000 Zeichen.

Responses

201Erstellt

{ "shift": Shift }

403Schicht-Limit erreicht

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

shift.created

PATCH/events/{eventId}/shifts/{shiftId}shifts:write

Schicht ändern

Aktualisiert Felder einer Schicht.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.
shiftIdpath	uuid	ja	Schicht-ID.

Responses

200Ok

{ "shift": Shift }

Emittierte Webhook-Events

shift.updatedshift.changed

DELETE/events/{eventId}/shifts/{shiftId}shifts:write

Schicht löschen

Schicht entfernen. Zugewiesene Helfer werden archiviert.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.
shiftIdpath	uuid	ja	Schicht-ID.

Responses

200Ok

{ "ok": true }

Emittierte Webhook-Events

shift.deleted

Helfer

Helfer-Stammdaten verein- und event-scoped lesen oder synchronisieren.

GET/helpershelpers:read

Helfer listen

Listet Helfer im Verein, optional gefiltert nach Event oder Suchstring.

Gate: ProPass oder API-Access-Add-on

Query-Parameter

Name	Typ	Required	Beschreibung
vereinIdquery	uuid	nein	Muss zum API-Key passen.
eventIdquery	uuid	nein	Nur Helfer mit Event-Zugriff.
searchquery	string	nein	Trifft Name, E-Mail oder Telefon.
limitquery	integer 1-200	nein	Standard 100.
offsetquery	integer 0-10000	nein	Standard 0.

Responses

200Ok

{ "helpers": [Helper], "limit": 100, "offset": 0 }

POST/helpershelpers:write

Helfer bulk anlegen oder synchronisieren

Bis zu 200 Helfer per Identity-Match (user_id, email, phone) upserten. Optional Event-Zugriff setzen.

Gate: Plan-/Capacity-Gate (Limit pro Plan/Add-on)

Request-Body

Name	Typ	Required	Beschreibung
mode	enum	nein	"upsert" (Default) oder "import" (lege nur fehlende an).
helpers	array<HelperInput>	ja	1–200 Helfer-Datensätze.
sync_to_event_id	uuid	nein	Setzt Event-Zugriff für die übergebenen Helfer.
replace_event_helpers	boolean	nein	Mit sync_to_event_id: bestehende Zugriffe ersetzen.

Responses

200Ok

{ "helpers": [Helper], "created": n, "updated": n }

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Request Beispiel

{
  "mode": "upsert",
  "sync_to_event_id": "11111111-1111-1111-1111-111111111111",
  "helpers": [
    { "full_name": "Max Muster", "email": "max@example.org", "tags": ["bar"] },
    { "full_name": "Nora Team", "phone": "+49177111222" }
  ]
}

Emittierte Webhook-Events

helper.grantedhelper.registered

HelperInput erfordert mindestens eines: user_id, email oder phone.
Existierende Records werden über email oder phone gematcht und gemerged.

POST/events/{eventId}/helpershelpers:write

Helfer einem Event zuweisen

Granted Helfer den Zugriff auf das Event. Bestehender Zugriff bleibt idempotent erhalten.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
user_id	uuid	ja	User-ID des Helfers.
invite_id	uuid \| null	nein	Optionaler Bezug zur ursprünglichen Einladung.

Responses

200Ok

{ "ok": true }

Emittierte Webhook-Events

helper.granted

Zuweisungen

Schichtbesetzung lesen und schreiben. Neue aktive Zuweisungen zählen auf das Helfer-Limit.

GET/events/{eventId}/assignmentsassignments:read

Zuweisungen listen

Listet alle Assignments eines Events inkl. Status.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{ "assignments": [Assignment] }

POST/events/{eventId}/assignmentsassignments:write

Zuweisung anlegen oder Status setzen

Upsert eines Assignments. Aktivierungen prüfen das Helfer-Limit des Plans.

Gate: Plan-/Capacity-Gate (Limit pro Plan/Add-on)

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
shift_id	uuid	ja	Existierende Schicht des Events.
user_id	uuid	ja	Helfer-ID.
state	enum	ja	Assignment-Status. Werte: requested, confirmed, cancelled, no_show, checked_in, checked_out, completed
notes	string \| null	nein	Bis 1 000 Zeichen.

Responses

200Ok

{ "assignment": Assignment }

403Helfer-Limit erreicht

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

assignment.updatedhelper.confirmedhelper.cancelled

Nachrichten & Broadcasts

Event-Nachrichten erstellen. Channel-Gates: SMS, WhatsApp und Broadcast prüfen Plan oder Add-on.

GET/events/{eventId}/messagesmessages:read

Nachrichten listen

Listet Nachrichten eines Events, neueste zuerst.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{ "messages": [Message] }

POST/events/{eventId}/messagesmessages:write

Nachricht erstellen / Broadcast auslösen

Erstellt eine Nachricht im Event. Channel- und Zielgruppen-Auswahl gegen Plan-/Add-on-Gates. SMS/WhatsApp/Broadcast erfordern passende Freischaltung.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
subject	string \| null	nein	Bis 200 Zeichen.
body	string	ja	1–6 000 Zeichen.
audience_type	enum	nein	Standard "all". Werte: all, selected, role, shift
audience_filter	object	nein	Bei "selected"/"role"/"shift": user_ids[], role_id, shift_id.
send_email	boolean	nein	Standard false.
send_sms	boolean	nein	Erfordert SMS-Add-on.
send_whatsapp	boolean	nein	Erfordert WhatsApp-Add-on, EventPass oder ProPass.

Responses

201Erstellt

{ "message": Message }

403Channel-Add-on fehlt

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

message.created

audience_type "selected" benötigt user_ids in audience_filter.
Broadcast/segmented Versand prüft broadcast_messaging bzw. segmented_messaging Feature.

PATCH/events/{eventId}/messages/{messageId}messages:write

Nachricht aktualisieren

Aktualisiert Subject/Body/Zielgruppe einer noch nicht versendeten Nachricht.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.
messageIdpath	uuid	ja	Message-ID.

Responses

200Ok

{ "message": Message }

Emittierte Webhook-Events

message.updated

DELETE/events/{eventId}/messages/{messageId}messages:write

Nachricht löschen

Entfernt eine Nachricht.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.
messageIdpath	uuid	ja	Message-ID.

Responses

200Ok

{ "ok": true }

Emittierte Webhook-Events

message.deleted

Verfügbarkeits-Umfragen

Zeitfenster anfragen und Antworten erfassen (z. B. für Tagespläne).

GET/events/{eventId}/availability/requestsavailability:read

Verfügbarkeits-Requests listen

Listet alle Verfügbarkeits-Anfragen eines Events.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Responses

200Ok

{ "requests": [AvailabilityRequest] }

POST/events/{eventId}/availability/requestsavailability:write

Verfügbarkeits-Request erstellen

Erstellt einen neuen Verfügbarkeits-Request mit Zeitfenstern.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
time_slots	array<{ id, label }>	ja	1–60 Slots. id ist beliebig, muss in Antworten passen.

Responses

201Erstellt

{ "request": AvailabilityRequest }

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

availability.request.created

GET/events/{eventId}/availability/responsesavailability:read

Antworten listen

Listet Antworten, optional gefiltert nach requestId.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Query-Parameter

Name	Typ	Required	Beschreibung
requestIdquery	uuid	nein	Filter auf einzelne Anfrage.

Responses

200Ok

{ "responses": [AvailabilityResponse] }

POST/events/{eventId}/availability/responsesavailability:write

Antwort upsert

Schreibt die Antwort eines Users auf eine Verfügbarkeits-Anfrage.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
eventIdpath	uuid	ja	Event-ID.

Request-Body

Name	Typ	Required	Beschreibung
request_id	uuid	ja	Existierender Request.
user_id	uuid	ja	Antwortender User.
responses	array<{ time_slot_id, available }>	ja	1–120 Slots.

Responses

200Ok

{ "response": AvailabilityResponse }

404Request nicht gefunden

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Emittierte Webhook-Events

availability.response.upserted

Webhooks

Webhooks erfordern ProPass ODER beide Add-ons (API-Access + Webhooks). Endpoints liefern signierte Events mit Retry und Delivery-Log.

GET/webhookswebhooks:read

Webhook-Endpoints listen

Listet alle Webhook-Endpoints der aktuellen Integration mit Status, Fehlerzahl und letztem Send-Zeitpunkt.

Gate: ProPass oder API-Access + Webhooks Add-ons

Responses

200Ok

{ "webhooks": [Webhook] }

POST/webhookswebhooks:write

Webhook erstellen

Legt einen neuen Webhook-Endpoint an. Das Signing-Secret wird nur einmal ausgegeben und muss sicher abgelegt werden.

Gate: ProPass oder API-Access + Webhooks Add-ons

Request-Body

Name	Typ	Required	Beschreibung
name	string	ja	2–80 Zeichen.
endpoint_url	https-url	ja	HTTPS-Pflicht.
events	array<WebhookEvent>	ja	1–20 Events.

Responses

201Erstellt – Signing-Secret nur einmal sichtbar.

{ "webhook": Webhook, "signing_secret": "whsec_...", "warning": "..." }

400Validation-Fehler oder kein HTTPS

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

403Plan/Add-ons fehlen

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

Signing-Secret danach nicht erneut abrufbar. Rotation = neuen Webhook anlegen, alten löschen.

DELETE/webhooks?webhookId={uuid}webhooks:write

Webhook deaktivieren

Setzt einen Webhook auf is_active=false. Delivery-Logs bleiben erhalten.

Gate: ProPass oder API-Access + Webhooks Add-ons

Query-Parameter

Name	Typ	Required	Beschreibung
webhookIdquery	uuid	ja	Webhook-ID.

Responses

200Ok

{ "ok": true, "webhook_id": "..." }

GET/webhooks/deliverieswebhooks:read

Delivery-Logs lesen

Liefert Versuche, Statuscodes, Response-Body und Dauer. Ideal für Retry-Diagnose.

Gate: ProPass oder API-Access + Webhooks Add-ons

Query-Parameter

Name	Typ	Required	Beschreibung
webhookIdquery	uuid	nein	Filter auf einzelnen Webhook.
eventNamequery	enum	nein	Filter auf konkretes Event.
limitquery	integer 1-200	nein	Standard 100.

Responses

200Ok

{ "webhooks": [Webhook], "deliveries": [WebhookDelivery] }

Automationen

Workflows für availability_request_created, no_show_detected und event_created.

GET/automations/workflowsautomation:read

Workflows listen

Listet alle Automation-Workflows der Integration.

Gate: ProPass oder API-Access-Add-on

Responses

200Ok

{ "workflows": [AutomationWorkflow] }

POST/automations/workflowsautomation:write

Workflow anlegen

Erstellt einen neuen Workflow mit Trigger und Channel-Definition.

Gate: ProPass oder API-Access-Add-on

Request-Body

Name	Typ	Required	Beschreibung
name	string	ja	2–120 Zeichen.
trigger_type	enum	ja	Trigger. Werte: availability_request_created, no_show_detected, event_created
channel	enum	nein	Standard "mixed". Werte: email, sms, whatsapp, mixed
is_active	boolean	nein	Standard true.
config	object	nein	Freie Konfiguration (z. B. Templates).

Responses

201Erstellt

{ "workflow": AutomationWorkflow }

400Validation-Fehler

{
  "error": "Human-readable message",
  "upgrade_hint": "pro_or_developer_addon"
}

PATCH/automations/workflows/{workflowId}automation:write

Workflow ändern

Aktualisiert ausgewählte Felder eines Workflows.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
workflowIdpath	uuid	ja	Workflow-ID.

Responses

200Ok

{ "workflow": AutomationWorkflow }

DELETE/automations/workflows/{workflowId}automation:write

Workflow löschen

Entfernt einen Workflow vollständig.

Gate: ProPass oder API-Access-Add-on

Path-Parameter

Name	Typ	Required	Beschreibung
workflowIdpath	uuid	ja	Workflow-ID.

Responses

200Ok

{ "ok": true }

POST/automations/triggerautomation:write

Automation manuell auslösen

Findet passende aktive Workflows und stößt das Automation-Webhook-Event an.

Gate: ProPass oder API-Access-Add-on

Request-Body

Name	Typ	Required	Beschreibung
trigger_type	enum	ja	Trigger. Werte: availability_request_created, no_show_detected, event_created
event_id	uuid	nein	Optionaler Event-Kontext.
payload	object	nein	Freie Trigger-Payload.

Responses

200Ok

{ "ok": true, "dispatched": n }

Emittierte Webhook-Events

automation.triggered

Hinweise zu Plan- und Capacity-Gates

Endpoints mit Gate plan_or_capacity prüfen pro Aufruf das aktuelle Plan-Limit (Events/Schichten/Helfer). Antworten enthalten dann code: "FEATURE_FORBIDDEN" sowie Upgrade-Hinweise.

Webhook-Endpoints sind seit dem letzten Release strikter: ProPass reicht, sonst werden beide Add-ons (api_access_plus und webhooks_access) verlangt.

Versionierung

Pfad-Präfix /v1 für die stabile API. Neue Major-Versionen erscheinen unter eigenem Pfad und sind mindestens 12 Monate parallel verfügbar.

Deprecations werden in der Changelog-Sektion und per E-Mail an Verein-Owner kommuniziert.

Idempotenz

Empfehlung: bei POST/PATCH einen Idempotency-Key setzen (UUID). Aktuell als Replay-Schutz beobachtet, künftig hart enforced.

Status & Support

Statusseite und Health-Checks: status.crewio.co.

Bug? Bitte Request-ID aus x-crewio-request-id ans Support-Team senden.

Bereit für den ersten Call?

Lege im Dashboard eine Integration an, wähle Scopes und teste mit GET /events.

Integration anlegen OpenAPI JSON