Kurz gesagt
- Agenten, Chats und Kontakte.Agenten erstellen, lesen, aktualisieren und löschen sowie Unterhaltungen, Nachrichten und Kontakte lesen.
- Schlüssel mit nur den nötigen Rechten.Geheime Schlüssel für Ihre Server, eingeschränkte Schlüssel mit genau den Berechtigungen, die Sie ankreuzen.
- OpenAPI 3.1 inklusive.Eine maschinenlesbare Beschreibung wird live bereitgestellt und aus denselben Regeln erzeugt, die die API prüft.
- Sicher wiederholbar.Senden Sie einen Idempotency-Key, und ein wiederholter Schreibzugriff liefert das erste Ergebnis, statt zweimal zu laufen.
Über eine API kann Ihre eigene Software direkt mit OneType sprechen. Agenturen richten per Skript Agenten für Kunden ein, Produktteams holen Unterhaltungen in ihre eigenen Berichte, und Ops-Teams halten Agenteneinstellungen im Code. Die REST API gibt Ihnen dieselben Daten und Regeln wie das Dashboard, über schlichtes HTTPS.
Was Sie tun können
- Agenten: auflisten, erstellen, lesen, aktualisieren und löschen, einschließlich Anweisungen, Modell, erlaubter Domains und vorgeschlagener Fragen.
- Unterhaltungen: nach Agent, Status oder Startdatum auflisten, eine lesen und ihre Nachrichten lesen.
- Kontakte: die Personen auflisten und lesen, denen Ihr Agent begegnet ist.
- Chat: eine Unterhaltung eröffnen und die Antwort des Agenten erhalten, als JSON oder gestreamt.
- Laden Sie die OpenAPI-3.1-Beschreibung unter /v1/openapi.json herunter.
Jede Nachricht gibt an, ob sie von der KI oder von Ihrem Team geschrieben wurde. Listen verwenden Cursor, mit 1 bis 100 Einträgen pro Seite, und bleiben stabil, während neue Einträge eintreffen. Eine Aktualisierung kann die gelesene Revision mitführen, sodass eine zwischenzeitliche Änderung abgelehnt statt überschrieben wird.
API-Schlüssel mit Berechtigungsbereichen
Inhaber und Administratoren erstellen Schlüssel unter „Developer“, „API keys“. Ein geheimer Schlüssel kann alles, was ein Workspace-Administrator kann, außer Schlüssel zu verwalten und Aktionen nur für Inhaber. Ein eingeschränkter Schlüssel hat nur die Berechtigungen, die Sie ankreuzen, nie mehr als Ihre eigenen. Verwenden Sie pro Integration oder Skript einen eingeschränkten Schlüssel, damit jeder nur seine Aufgabe erledigen kann.
Ein Schlüssel wird einmal angezeigt und als Hash gespeichert. Die Liste zeigt die letzten Zeichen jedes Schlüssels und wann er zuletzt verwendet wurde. Widerrufen Sie einen Schlüssel, scheitert schon die nächste Anfrage damit. Schlüssel gehören zu einem Workspace und können nie die Daten eines anderen Workspace lesen.
Für echte Integrationen gebaut
Jeder Fehler hat dieselbe Form, mit einem stabilen Code, einer Meldung, Felddetails, wo sie zutreffen, und einer Anfrage-ID. Senden Sie bei einem Schreibzugriff Idempotency-Key, und das erste Ergebnis wird 24 Stunden lang gespeichert, sodass eine Wiederholung nach einem Timeout nie einen zweiten Agenten oder eine zweite Antwort erzeugt.
Jeder Schlüssel kann alle 10 Sekunden 100 Anfragen und bis zu 20 Chat-Nachrichten senden. RateLimit-Header zeigen, wie viel übrig ist, und ein 429 gibt an, wie lange zu warten ist. Die Limits sind in jedem kostenpflichtigen Tarif gleich. Anfragen mit falschem Schlüssel werden pro Netzwerkadresse begrenzt.
Was die API noch nicht abdeckt
Wissensquellen, Nutzung, Webhooks und Integrationen werden im Dashboard verwaltet, nicht über die API. Kontakte sind schreibgeschützt. Schlüssel sind nur für Server gedacht: Einen Browser-Schlüssel gibt es noch nicht. Aktuell gibt es kein veröffentlichtes SDK auf npm, nutzen Sie also schlichtes HTTPS oder erzeugen Sie einen Client aus der OpenAPI-Datei.
Die OpenAPI-Datei wird aus denselben Schemas erzeugt, mit denen die API Anfragen prüft, sodass sie nie von dem abweicht, was der Server akzeptiert. Die API ändert sich nur durch Hinzufügen: neue Felder, neue Endpunkte und neue Ereignistypen. Code, der unbekannte Felder ignoriert, funktioniert also weiter.