API v1

Die Ciele-API verwendet JSON über HTTP. Alle Version-1-Routen beginnen mit /api/v1.

Open the interactive API reference, um alle öffentlichen Operationen nach Domäne zu durchsuchen. Laden Sie dort den aktuellen OpenAPI-Vertrag als JSON oder YAML herunter.

Die Bereitstellung entdecken

Verwenden Sie diese öffentlichen Endpunkte, bevor Sie einen Client generieren:

GET /api/v1/meta
GET /api/v1/openapi.json

meta listet die API-Version und die verfügbaren Domains auf. openapi.json gibt den maschinenlesbaren Vertrag für die Bereitstellung zurück.

Eine Anfrage authentifizieren

Senden Sie den API-Schlüssel als Bearer-Token:

curl https://ciele.app/api/v1/whoami \
  --header "Authorization: Bearer $CIELE_API_KEY"

Für Self-Hosting ersetzen Sie https://ciele.app durch den öffentlichen Ciele-Ursprung.

Die Antwort enthält capabilities: die Berechtigungen des Schlüssels. Ein Schlüssel kann nur das tun, was sowohl seine Role als auch sein Creator tun dürfen.

Bei einer Operation für einen Assistant gilt die Role des Erstellers dieses Assistants. Wenn nur diese Assistant Role den Vorgang ablehnt, gibt die API 404 zurück – genauso wie bei einem Assistant, der nicht existiert.

Fehler in der Antwort

Fehler verwenden einen JSON-Envelope:

{
  "error": {
    "code": "forbidden",
    "message": "This API key cannot perform this operation."
  }
}

Häufige Statuscodes sind:

Paginierung

Verwenden Sie die bei jeder Operation angezeigten Paginierungsparameter. Cursorbasierte Listen geben nextCursor zurück. Geben Sie es bei der nächsten Anfrage als cursor weiter.

Sichere Wiederholungsversuche

Mutation-Routen können einen Idempotency-Key-Header akzeptieren. Verwenden Sie denselben Wert nur dann erneut, wenn Sie dieselbe logische Operation wiederholen.

Häufige Domains

Dies sind Beispiele. Die API-Referenz listet den vollständigen, aktuellen Satz von Operationen auf.

• Assistants: list, read, create, update, duplicate und delete.
• Flows: list, read, create, update, reorder und delete.
• Knowledge: Verwalten Sie Collections, Sources, FAQs und die Assistant-Links für jede Source.
• Publication: Status lesen, veröffentlichen, Veröffentlichung aufheben und eine Publication wiederherstellen.
• Inbox: Conversations überprüfen, exportieren, anheften, kommentieren, bewerten und löschen.
• Improvements: Elemente auflisten, lesen und aktualisieren.
• Memories: Überprüfen Sie die Einstellungen und führen Sie eine bereichsbezogene Löschung von Memories durch.
• SSO: Verwalten von Identity Claims, Verbindungseinstellungen, Validierung und Trennung.
• Help Desks: Verwalten Sie Desks, Eskalationskanäle, die Reihenfolge sowie das Ticketing-Ziel.
• Teammates: Verwalten Sie AI Teammates und lesen Sie Ihre eigenen Teammate-Konversationen.
• Projects: Verwalten Sie Projects, deren Meilensteine und die Project-Dokumente, die Teammates lesen.
• Tasks: Tasks auflisten, lesen, erstellen, ändern, archivieren und löschen, sie kommentieren sowie Task Labels verwalten. Die Liste wird nach Project, Assignee, Status, Label, Due Dates, Text und Improvement gefiltert und verwendet für jede Seite einen Cursor. Ein Schlüssel liest nur die Projekte, die sein Mitglied lesen darf. Ein Kommentar zeigt dieses Mitglied als Autor an.
• Reviews: Human Review Requests auflisten, lesen und darüber entscheiden.
• Channels: Lesen und gestalten Sie die Teammate-Channels, in denen Sie Mitglied sind, sowie deren Roster. Es gibt keinen Endpunkt, um eine Nachricht zu senden: Eine Nachricht startet eine Kette von Antworten von Teammitgliedern, und diese läuft in der Konsole ab.
• Configuration: Verwalten Sie Skills, Assistant Goals und betriebliche Alerts.
• Organization: Verwalten Sie Einstellungen, Members, Invites und API keys. Beschränken Sie ein Mitglied auf ausgewählte Assistants.
• Integrations: Verwalten Sie Assistant-API-Integrationen und Verbindungen zu Modellanbietern.
• Usage: Lesen Sie die Zähler des Plans und sehen Sie, wer die Credits eines Fensters verbraucht hat. Schreibgeschützt. Die Aufschlüsselung der Ausgaben hält ihre Dimensionen getrennt. Eine Antwort nennt sowohl das Teammitglied, das den Vorgang ausgeführt hat, als auch den Kollegen, der ihn angefordert hat. Wenn man also die Dimensionen addiert, wird er doppelt gezählt. Der Kauf von Credits hat keinen Endpunkt: Ein Kauf gehört auf einen Bildschirm, auf dem eine Person einen Betrag bestätigt.
• Audit-Protokoll: Lesen Sie, wer was von welcher Oberfläche aus geändert hat, mit den Werten vor und nach der Änderung für Role, Invitation, Key, Access und Settings. Schreibgeschützt. Filtern Sie nach action, actor und date. Um weiter zurückliegende Einträge anzuzeigen, senden Sie den createdAt und den id des letzten Eintrags, den Sie haben, als before und beforeId.

Verwenden Sie das OpenAPI-Dokument für Request-Felder, die Authentifizierung und die dokumentierten Response-Statuscodes.