REST API
Programmatischer Zugriff auf ein Connic-Projekt mit API Keys für Runs, Retrieval, Deployments und Kostendaten. Verbindungen führen Agenten als Reaktion auf Events aus.
Auf dieser Seite
Überblick
Die REST API von Connic ermöglicht außerhalb des Dashboards den Zugriff auf ein Projekt. Darüber lassen sich Run-Ergebnisse an ein externes Monitoring übergeben, Retrieval programmatisch verwalten und Kostendaten für Abrechnungs-Dashboards abrufen.
Alle API-Anfragen werden mit projektspezifischen API Keys authentifiziert und pro Projekt rate-limitiert. Die vollständige Endpoint-Referenz enthält Request- und Response-Schemas sowie Beispiel-Requests. API Endpoints öffnen.
Authentifizierung
API-Anfragen werden mit API Keys authentifiziert. Jeder Key ist auf ein einzelnes Projekt begrenzt und kann nur auf Endpoints dieses Projekts zugreifen. Übergib den Key als Bearer Token im Authorization Header:
Authorization: Bearer cnc_your_api_keyErstelle und verwalte API Keys unter Projekt-Settings → API Keys & MCP Auth. Keys beginnen mit dem Präfix cnc_ und werden beim Erstellen nur einmal angezeigt. Bewahre sie sicher auf.
CONNIC_API_KEY.API-Key-Berechtigungen
Jeder API Key verwendet dieselben Projekt-Berechtigungen für einzelne Aktionen, die unter Team & Permissions angezeigt werden. Lass alle verfügbaren Berechtigungen ausgewählt oder wähle einzelne Berechtigungen aus. Die Auswahl lässt sich jederzeit ändern.
Berechtigungsmodell
Die Berechtigungsauswahl zeigt alle von der API unterstützten Berechtigungen, über die der Account verfügt, der den Key erstellt oder bearbeitet.
| Konzept | Details |
|---|---|
| Alle Berechtigungen | Die Standardeinstellung. Umfasst jede von der API unterstützte Berechtigung, die dem Besitzer des Keys zur Verfügung steht. |
| Einzelne Berechtigungen | Umfasst nur die ausgewählten Berechtigungen für einzelne Aktionen und kann leer sein. |
| Berechtigungen des Besitzers | Ein Key überschreitet nie die Projektberechtigungen seines Besitzers, selbst wenn für den Key weitergehende Berechtigungen ausgewählt sind. |
| Bearbeitung | Der Besitzer des Keys kann dessen Namen und Berechtigungen ändern. Projektmitglieder mit der Berechtigung zum Löschen von API Keys können ihn widerrufen. |
Rate Limiting
API-Anfragen werden pro Projekt rate-limitiert. Alle API Keys desselben Projekts teilen sich das Limit. Wird es überschritten, antwortet die API mit:
| Response | Details |
|---|---|
| Status Code | 429 Too Many Requests |
| Retry-After Header | Anzahl der Sekunden bis zum nächsten Retry |
Für höhere Limits steht das Connic-Team zur Verfügung.
Kurze Beispiele
Run-Details abrufen
curl https://api.connic.co/v1/projects/{project_id}/runs/{run_id} \
-H "Authorization: Bearer cnc_your_api_key"Text in Retrieval hochladen
Retrieval Endpoints benötigen den Query Parameter environment_id, um den Request auf ein bestimmtes Environment zu begrenzen.
curl -X POST "https://api.connic.co/v1/projects/{project_id}/retrieval/text?environment_id={env_id}" \
-H "Authorization: Bearer cnc_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"content": "Dokumenttext steht hier...",
"namespace": "docs.api",
"entry_id": "my-custom-id"
}'Fehlerantworten
Die API verwendet standardmäßige HTTP-Statuscodes. Die meisten Fehlerantworten enthalten einen JSON-Body mit dem Feld detail. Weitergeleitete Retrieval-Fehler verwenden stattdessen error.
| Code | Bedeutung |
|---|---|
| 401 | Fehlender oder ungültiger API Key |
| 403 | Dem Key fehlt die Berechtigung für diesen Endpoint oder der Endpoint gehört nicht zur öffentlichen API |
| 404 | Ressource nicht gefunden |
| 408 | Die Retrieval-Abfrage hat ihr Zeitlimit überschritten |
| 429 | Rate Limit überschritten. Prüfe den Retry-After Header. |
| 500 | Interner Serverfehler |
Entdecke alle Endpoints mit vollständigen Request- und Response-Schemas sowie Beispiel-Code.
API Endpoints öffnen