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 hat eine Environment-Auswahl und dieselben aktionsbezogenen Projektberechtigungen, die unter Team & Permissions angezeigt werden. Standardmäßig umfasst er alle aktuellen und künftigen Environments sowie alle von der API unterstützten Berechtigungen seines Owners. Wähle eine Teilmenge der Environments oder einzelne Berechtigungen aus, um den Zugriff einzuschränken. Beide Auswahlen lassen sich später ä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 |
|---|---|
| Environments | All environments ist die Standardeinstellung und umfasst auch später erstellte Environments. Eine Auswahl beschränkt den Key auf diese Environments; projektweite Aktionen erfordern Zugriff auf alle Environments. Wird eines der ausgewählten Environments gelöscht, bleibt der Key inaktiv, bis seine Auswahl angepasst wird. |
| 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 Owner kann Name, Environment-Auswahl und Berechtigungen des Keys ändern, ohne ihn zu rotieren. 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"
}'Kontozugänge (Connections)
Kontozugänge sind wiederverwendbare Zugangsdaten für das ganze Projekt, auf die Verbindungen verweisen. Diese Endpoints benötigen die Berechtigung connections.view, connections.create, connections.update oder connections.delete.
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /v1/projects/{project_id}/connections | Kontozugänge mit den Verbindungen auflisten, die sie verwenden. |
| POST | /v1/projects/{project_id}/connections | Kontozugang anlegen. |
| GET | /v1/projects/{project_id}/connections/{connection_id} | Einen Kontozugang abrufen. |
| PATCH | /v1/projects/{project_id}/connections/{connection_id} | Kontozugang umbenennen oder seine Einstellungen ersetzen. Neue Zugangsdaten gelten für jede Verbindung, die ihn verwendet. |
| DELETE | /v1/projects/{project_id}/connections/{connection_id} | Kontozugang löschen. Antwortet mit 409, solange eine Verbindung ihn verwendet. |
| GET | /v1/projects/{project_id}/connections/-/schema/{connector_type} | Felder eines Kontozugangs für einen Verbindungstyp abrufen. |
Secret-Felder lassen sich nur schreiben und werden maskiert zurückgegeben. Slack-Kontozugänge lassen sich nur im Dashboard anlegen.
Fehler bei Verbindungen während der Aktivierung
Beim Aktivieren eines Deployments wendet connic die darin in connectors/*.yaml deklarierten Verbindungen an. Schlägt eine Änderung an einer Verbindung fehl, antwortet POST /v1/projects/{project_id}/deployments/{deployment_id}/activate mit 409, listet die Fehler in detail.connector_failures auf und aktiviert nichts. Mit ?force=true wird trotzdem aktiviert; die fehlerhaften Verbindungen behalten ihren bisherigen Zustand.
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