Ceyu
Mein Konto

API quickstart

Erstelle einen eingegrenzten Schlüssel, sende eine Anfrage und behandle Fehler richtig. Die Beispiele sind bewusst vollständig genug für den Produktionseinsatz.

1. Schlüssel erstellen

Öffne Entwickler in Ceyu, wähle Schlüssel und erstelle einen Organisationsschlüssel. Kopiere ihn einmal in einen Secret Manager; committe ihn nie und lege ihn nie in Browser-Code offen.

Geheimnis

Ceyu akzeptiert Zugangsdaten nur im Authorization-Header. Schlüssel in URLs werden abgelehnt, weil URLs in Verlauf, Referrer, Logs und Caches gelangen.

2. Erste Anfrage senden

Sende den Schlüssel als Bearer-Zugangsdaten und lege das API-Datum fest. Ein Schlüssel behält seine konfigurierte Version, sodass spätere kompatible Ergänzungen deine Integration nicht still verändern.

curl https://api.ceyu.org/v1/me \
  -H "Authorization: Bearer $CEYU_API_KEY" \
  -H "Ceyu-Version: 2026-08-03"

3. Idempotent schreiben

Jeder Schreibzugriff braucht einen Idempotenzschlüssel. Derselbe Schlüssel mit demselben Body liefert die ursprüngliche Antwort; mit anderen Eingaben entsteht ein Konflikt.

curl https://api.ceyu.org/v1/tasks \
  -X POST \
  -H "Authorization: Bearer $CEYU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"workspace":"ws_…","title":"Launch checklist"}'

4. Fehler behandeln

Verzweige anhand von error.code, bewahre request_id für den Support auf und beachte Retry-After nach Ratenlimits oder vorübergehendem Lastabwurf. Validierungs- und Berechtigungsfehler dürfen nicht wiederholt werden.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_body",
    "message": "The request body is invalid.",
    "param": "title",
    "request_id": "req_01JAZ…"
  }
}

5. TypeScript-SDK verwenden

Der offizielle Client ergänzt Versions- und Idempotenz-Header, führt begrenzte Wiederholungen aus, stellt strukturierte Fehler bereit und prüft Webhook-Signaturen gegen den exakten unveränderten Request-Body.

import { CeyuClient } from "@ceyu/api";

const ceyu = new CeyuClient({ apiKey: process.env.CEYU_API_KEY });
for await (const task of ceyu.tasks.list({ limit: 20 })) {
  console.log(task.title);
}

6. Webhooks sicher empfangen

Eine neue oder geänderte URL muss zuerst auf ein platform.webhook_endpoint.verify-Ereignis mit 2xx antworten. Erst danach wird das Signiergeheimnis einmalig zurückgegeben. Prüfe jedes echte Ereignis vor dem JSON-Parsen gegen die exakten Rohbytes; ein erneut serialisierter Body darf nie geprüft werden.

import { verifyWebhookSignature } from "@ceyu/api";

const rawBody = await request.text();
const candidate = JSON.parse(rawBody);

// The reachability probe arrives before the secret is revealed.
if (candidate.type === "platform.webhook_endpoint.verify") {
  return new Response(null, { status: 204 });
}

await verifyWebhookSignature({
  rawBody,
  signature: request.headers.get("Ceyu-Signature") ?? "",
  secret: process.env.CEYU_WEBHOOK_SECRET,
});

// Process candidate only after verification.

Weiter zur generierten API-Referenz →