API verwenden

Über die symbiofy-API stellst du Anfragen an die KI direkt aus deinen eigenen Anwendungen – ohne die Weboberfläche. Du sendest eine Nachricht, optional mit Dateianhängen und einem bestimmten SymbioBot, und erhältst die Antwort als JSON zurück.

Voraussetzungen:

• Das Feature API-Zugang muss für deine Organisation freigeschaltet sein.
• Du brauchst einen API-Schlüssel. Wie du ihn erstellst, steht unter API-Schlüssel.

Basis-URL

Alle Endpunkte liegen unter:

https://my.symbiofy.ai

Es gibt keine eigene API-Subdomain – die API läuft unter derselben Adresse wie die Anwendung.

Authentifizierung

Jede Anfrage braucht deinen API-Schlüssel im Authorization-Header als Bearer-Token:

Authorization: Bearer sk_dein-schluessel

Ein Schlüssel beginnt immer mit sk_ und ist 67 Zeichen lang.

Wichtig:

• Ein anderer Header (etwa x-api-key) funktioniert nicht.
• Eine Anmeldung über Cookies wird für die API nicht akzeptiert – ein Login im Browser genügt also nicht.
• Die API sendet keine CORS-Header. Rufe sie deshalb von deinem Server aus auf, nicht direkt aus dem Browser-JavaScript deiner Website.

Verfügbare Endpunkte

SymbioBots auflisten

Liefert die SymbioBots, auf die der Ersteller des API-Schlüssels zugreifen darf. Du brauchst diesen Endpunkt, um die templateId für eine Chat-Anfrage zu ermitteln.

curl https://my.symbiofy.ai/api/v1/templates \
  -H "Authorization: Bearer sk_dein-schluessel"

Antwort:

{
  "templates": [
    {
      "id": "3f2b8c14-9a7d-4c51-b8e2-7d1f6a3e9c40",
      "title": "Kundenservice-Assistent",
      "description": "Beantwortet Fragen zu unseren Produkten"
    }
  ]
}

Die Liste enthält alle passenden Bots auf einmal – Entwürfe ohne Namen erscheinen nicht. Es gibt keine Parameter für Filter oder seitenweises Abrufen. Sortiert wird nach dem Datum der letzten Änderung, neueste zuerst.

Nachricht senden

Der zentrale Endpunkt. Du sendest eine Nachricht und erhältst die fertige Antwort.

Anfrage

curl -X POST https://my.symbiofy.ai/api/v1/chat/responses \
  -H "Authorization: Bearer sk_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Fasse die wichtigsten Punkte unserer Datenschutzrichtlinie zusammen."
  }'

Felder:

Ohne templateId antwortet das Standardmodell deiner Organisation. Mit templateId wird immer die veröffentlichte Version des Bots verwendet – unveröffentlichte Entwürfe wirken sich auf die API nicht aus.

Unbekannte Felder werden ignoriert.

Antwort

{
  "role": "assistant",
  "content": "Die Richtlinie nennt drei zentrale Punkte: ..."
}

Mehr Felder gibt es nicht – keine ID, keine Angaben zum Verbrauch und kein Gesprächsverlauf.

Drei Dinge, die oft anders erwartet werden

Die Antwort wird nicht gestreamt. Du bekommst eine einzelne JSON-Antwort, erst wenn die KI vollständig fertig ist. Nutzt der Bot Tools oder wertet er Dateien aus, kann das mehrere Minuten dauern. Serverseitig darf eine Anfrage bis zu 13 Minuten laufen – stelle den Timeout deines Clients deshalb auf mindestens 15 Minuten ein, sonst brichst du gesunde Anfragen selbst ab.

Jede Anfrage steht für sich. Es gibt kein Feld für einen Gesprächsverlauf und keine Sitzung – die API merkt sich nichts zwischen zwei Aufrufen. Wenn frühere Nachrichten für die Antwort wichtig sind, schreibe sie mit in das Feld message. Die Chats aus der Weboberfläche sind über die API weder les- noch fortsetzbar, und API-Anfragen erscheinen dort nicht.

Einige Funktionen stehen über die API nicht zur Verfügung, auch wenn der Bot sie in der Weboberfläche nutzen kann: Bildgenerierung, Präsentationen, Canvas, Code-Interpreter, Bot-Suche, Rückfragen an dich und die Delegation an andere Agenten. Auch Tools von MCP-Servern werden nicht geladen. Ebenfalls nicht verfügbar ist das dynamische Nachladen von Skills; fest zugewiesene Skills wirken dagegen normal. Alle übrigen Tools – etwa der Zugriff auf die Wissensdatenbank – funktionieren normal. Persönliche Angaben und persönliches Gedächtnis des Schlüssel-Erstellers fließen nicht ein; hinterlegtes Unternehmenswissen dagegen schon.

Dateien mitsenden

Pro Anfrage kannst du bis zu 5 Dateien mitschicken – entweder als öffentlich erreichbare URL oder direkt als Base64-Inhalt.

Pro Anhang gibst du entweder url oder data an, niemals beides. Zusätzlich brauchst du mindestens mediaType oder filename, damit der Dateityp erkannt werden kann.

Grenzen:

• Höchstens 20 MB pro Datei. Bei URLs kann das nur geprüft werden, wenn der Server einen Content-Length-Header sendet.
• Höchstens 40 MB für alle direkt eingebetteten Dateien einer Anfrage zusammen
• Erlaubte Formate: PDF, Word (docx, doc, dotx, dotm, rtf), Excel (xlsx, xlsm, xls, xltx, xltm, csv), PowerPoint (pptx, potx, potm), Text (txt, md, json) sowie Bilder (jpg, jpeg, png, gif, webp)

Beispiel mit Bot und PDF:

curl -X POST https://my.symbiofy.ai/api/v1/chat/responses \
  -H "Authorization: Bearer sk_dein-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Welche Risiken nennt der Bericht?",
    "templateId": "3f2b8c14-9a7d-4c51-b8e2-7d1f6a3e9c40",
    "attachments": [
      {
        "filename": "bericht.pdf",
        "mediaType": "application/pdf",
        "data": "JVBERi0xLjQKJeLjz9M..."
      }
    ]
  }'

Beispiel mit URL:

{
  "message": "Was steht in dieser Datei?",
  "attachments": [
    {
      "url": "https://example.com/bericht.pdf",
      "mediaType": "application/pdf",
      "filename": "bericht.pdf"
    }
  ]
}

Bei URLs prüft symbiofy die Datei vorab. Die Adresse muss HTTPS verwenden, öffentlich erreichbar sein und beim Abruf einen Content-Type liefern, der deinem mediaType entspricht – Groß- und Kleinschreibung sowie Zusätze wie ; charset=… spielen dabei keine Rolle. Fehlt der Header ganz, wird nicht geprüft. Adressen aus internen Netzen werden aus Sicherheitsgründen abgewiesen.

Beispiel mit JavaScript

const response = await fetch('https://my.symbiofy.ai/api/v1/chat/responses', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYMBIOFY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Fasse unsere Datenschutzrichtlinie zusammen.',
    templateId: '3f2b8c14-9a7d-4c51-b8e2-7d1f6a3e9c40',
  }),
  signal: AbortSignal.timeout(900_000), // 15 Minuten
})
 
if (!response.ok) {
  const fehler = await response.json()
  throw new Error(`${response.status}: ${fehler.error}`)
}
 
const { content } = await response.json()
console.log(content)

Lege deinen API-Schlüssel in einer Umgebungsvariablen ab – niemals direkt im Quelltext, und erst recht nicht in Code, der im Browser ausgeliefert wird.

Fehler

Fehler kommen in dieser Form zurück – das Feld details ist optional und fehlt bei manchen Fehlern (etwa 401, 403 und 404):

{
  "error": "Invalid request parameters",
  "details": "Maximum 5 attachments allowed per request"
}

Zu 404: Es wird bewusst nicht unterschieden, ob ein Bot gar nicht existiert oder nur nicht zugänglich ist. Prüfe im Zweifel mit /api/v1/templates, welche IDs dein Schlüssel tatsächlich sehen darf.

Kontingente und Anfragehäufigkeit

Anfragehäufigkeit: Als Richtwert gelten etwa 50 Anfragen pro Minute je Kombination aus Schlüssel und aufrufender IP-Adresse. Der Zähler läuft zusätzlich pro Server-Instanz, die tatsächliche Grenze kann also etwas höher liegen – verlasse dich nicht auf einen exakten Wert. Bei Überschreitung kommt 429 zurück, zusammen mit einem Retry-After-Header, der die Wartezeit in Sekunden nennt.

Kontingent: API-Anfragen zählen auf dasselbe monatliche Kostenbudget wie deine Workflows. Ist es aufgebraucht, antwortet die API mit 429 und dieser Meldung:

{
  "error": "quota_exceeded",
  "details": "QUOTA_COST_EXCEEDED"
}

Der Retry-After-Header nennt dann die Sekunden bis zum Beginn der nächsten Abrechnungsperiode.

Behandle 429 in deiner Anwendung, indem du die Wartezeit aus Retry-After abwartest und die Anfrage danach wiederholst.

Sicherheitshinweise

• Rufe die API nur von deinem Server aus auf, nie aus dem Browser – sonst wird dein Schlüssel öffentlich sichtbar.
• Lege Schlüssel in Umgebungsvariablen ab, nicht im Quelltext oder in einem Git-Repository.
• Ein Schlüssel hat dieselben Zugriffsrechte wie die Person, die ihn erstellt hat. Er kann also auf alle SymbioBots und Wissensdatenbanken zugreifen, die dieser Person offenstehen.
• Verwende für jede Anwendung einen eigenen Schlüssel. So kannst du einen einzelnen löschen, ohne die anderen zu beeinträchtigen.
• Schlüssel laufen nicht automatisch ab. Prüfe in der Übersicht regelmäßig die Spalte Zuletzt verwendet und lösche, was nicht mehr gebraucht wird.