API v1

Rufen Sie die aktuelle Ciele-Verwaltungs-API mit einem Organisations-API-Schlüssel auf.

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änen 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-Origin.

Fehler bei der Antwort

Fehler verwenden einen JSON-Envelope:

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

Häufige Statuscodes sind:

Status	Bedeutung
`400`	Der Anfrageinhalt ist fehlerhaft oder eine erforderliche Datei fehlt.
`401`	Der Schlüssel fehlt, ist ungültig oder wurde gesperrt.
`403`	Die Rolle des Schlüssels erlaubt den Vorgang nicht.
`404`	Die Ressource existiert nicht in der Organisation.
`409`	Die Anfrage steht im Konflikt mit dem aktuellen Zustand.
`422`	Die verarbeiteten Eingaben bestehen die Validierung nicht.

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äufig verwendete Domains

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

Assistants: auflisten, lesen, erstellen, aktualisieren, duplizieren und löschen.
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.
Verbesserungen: Elemente auflisten, lesen und aktualisieren.
Entities und Memories: Verwalten Sie typisierte Organisationsdaten und das Löschen von Memories innerhalb eines bestimmten Geltungsbereichs.
SSO: Verwalten von Identity Claims, Verbindungseinstellungen, Validierung und Trennung.
Help Desks: Verwalten Sie Desks, Eskalationskanäle, Ordering und ServiceNow.
Teammates: Verwalten Sie AI Teammates und lesen Sie Ihre eigenen Teammate-Konversationen.
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 der Teammates, die in der Konsole ausgeführt wird.
Configuration: Verwalten Sie Skills, Assistant Goals und betriebliche Alerts.
Organization: Verwalten Sie Einstellungen, Members, Invites und API keys.
Integrations: Verwalten Sie Assistant-API-Integrationen und Model-Provider-Connections.
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. In einer Antwort werden sowohl das Teammitglied, das den Vorgang ausgeführt hat, als auch der Kollege, der die Anfrage gestellt hat, genannt. Wenn man also die Dimensionen zusammenzählt, wird der Vorgang 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.

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