API-Überblick

Was die API bietet

Mit der API legt Ihr Server isolierte Bereiche an, konfiguriert sie (Manifest, Secrets, Werkzeuge, MCP-Server), sendet Anfragen mit Dateien und erhält Antworten und vom Agenten erzeugte Dateien. Abgerechnet wird über Ihr Konto, aufgeschlüsselt nach Ihren eigenen Kunden.

Schlüssel und Zugriff

• Basis-URL: https://dash.octodus.com/v1
• Jede Anfrage: der Header Authorization: Bearer octo_live_…
• Schlüssel erstellen Sie im Dashboard: Integrationen, API-Schlüssel. Der Schlüssel wird einmal angezeigt.
• Die API ist für serverseitige Aufrufe gedacht: Betten Sie einen Schlüssel nie in einen Browser oder eine mobile App ein.

end_user_ref ist Ihre eigene Kunden-ID. Sie legt bei uns kein Konto an, aber Verbrauch und Limits pro Kunde werden darüber geführt.

Ihre erste Anfrage

Legen Sie einen Bereich an, senden Sie einen Turn mit Idempotency-Key und fragen Sie ihn ab, bis er einen Endzustand erreicht. Python- und TypeScript-Versionen stehen in der Referenz.

BASE=https://dash.octodus.com/v1
KEY=octo_live_xxxxxxxxxxxxxxxx

SLUG=$(curl -s -X POST $BASE/spaces -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"title":"My first space"}' | jq -r .space_id)

TURN=$(curl -s -X POST $BASE/turns -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"space":"'"$SLUG"'","end_user_ref":"customer-42","text":"Hello"}' | jq -r .turn_id)

curl -s $BASE/turns/$TURN -H "Authorization: Bearer $KEY" | jq '{state, result, energy_used}'

Über die eigene API Ihrer App arbeiten

• /v1 liefert keine Daten. Ein Turn ist ein Auslöser („Bearbeite Auftrag 42“), und sein result ist Text für Menschen: Zeigen oder protokollieren Sie ihn, aber parsen Sie kein JSON daraus und lesen Sie keine Daten heraus.
• Zuerst die Arbeit des Menschen. Jede Aktion in der Oberfläche Ihrer App (Auftrag übernehmen, seine Datei abrufen, Ergebniszeilen schreiben, Lieferant oder Objekt setzen, Status setzen, zur Prüfung senden) ist eine Operation der eigenen API Ihrer App, mit ihrer normalen Authentifizierung. Das Audit-Log zeigt, wer es war: ein Mensch oder der Agent als Vertreter von Maria. Ein Mensch kann dieselbe Arbeit mit denselben Anfragen ohne den Agenten erledigen. Einen eigenen Ergebnis-Endpunkt, ein eigenes Ergebnisformat oder ein Werkzeug wie submit_result gibt es nicht.
• Der Nutzer überträgt diese Arbeit dem Agenten. Ihre App stellt einen Zugang für den Vertreter des Nutzers aus und übergibt dem Bereich ihre API direkt beim Anlegen, in einem Aufruf (app_api bei POST /v1/spaces). Danach liest der Bereich die Eingaben selbst, schreibt Ergebnisse und Status, liest das Geschriebene erneut und korrigiert, was Ihre App abgelehnt hat: Auf einen fehlerhaften Schreibvorgang antwortet Ihre App mit 4xx und einem Grund, genau wie bei einem Menschen.
• Danach sendet Ihre App nur den Auslöser: POST /v1/turns mit „Bearbeite Auftrag 42“ und einem Idempotency-Key. Den Fortschritt zeigt Ihre App aus der eigenen Datenbank (die Status, die der Bereich gesetzt hat). Ein Webhook meldet nur, dass ein Turn fertig ist.

curl -s -X POST $BASE/spaces -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"title":"Orders for Maria","app_api":{
    "name":"orders","base_url":"https://orders.acme.com/api",
    "credentials":{"ORDERS_API_TOKEN":"<delegate token>"},"acts_for":"[email protected]"}}'

curl -s -X POST $BASE/turns -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"space":"'"$SLUG"'","text":"Handle request 42"}'

Einen bestehenden Bereich anbinden, den Token wechseln, auflisten oder entfernen: PUT, PATCH, GET und DELETE auf /v1/spaces/{slug}/app-api. App-API in der Referenz

Ablauf und Webhooks

• Ein Turn ist asynchron: queued → running → done | failed | cancelled.
• Statt abzufragen, registrieren Sie einen Webhook: Die Plattform sendet bei jedem Übergang ein signiertes Ereignis. Es enthält keine Daten, nur „der Turn ist fertig“, um eine Ansicht zu aktualisieren oder einen Fehler zu bemerken. Webhooks
• Das Ergebnis eines Turns ist Text für Menschen. Die Daten schreibt der Agent über die API direkt in Ihre App; GET /v1/turns/{id} dient zum Prüfen von Zustand, Fehler und energy_used. Die API Ihrer App
• "stateless": true: Der Turn läuft in einem frischen Wegwerf-Unterbereich ohne Verlauf, der nach dem Ende archiviert wird. Für den Unterschlüssel einer App ist das der Standard; "stateless": false behält das Gedächtnis zwischen Aufrufen. Details
• "model": stellt den ganzen Bereich auf dieses Modell um, nicht nur diesen Turn. Es bleibt, bis ein Turn ein anderes Modell oder "auto" nennt (zurück zum Standard); ein Turn ohne Modell behält es. Ein Modellwechsel kostet so einen Sitzungswechsel, und der Cache bleibt, statt bei jedem Turn zu wechseln. In einem Wegwerf-Unterbereich (stateless) endet das Modell mit ihm. Details

Timeouts und Wiederholungen

• Abfragen oder Push: Fragen Sie den Turn alle 1 bis 2 s mit wachsendem Abstand (bis 10 s) ab, oder empfangen Sie Ereignisse per Webhook (einmal eingerichtet oder webhook_url am Turn) und behalten Sie eine seltene Kontrollabfrage bei. Beides liefert keine Daten: Die sind schon in Ihrer App.
• Jeder API-Aufruf antwortet sofort, 30 s pro HTTP-Anfrage genügen. Geben Sie dem Turn selbst mindestens 180 s: Die meisten sind in Sekunden oder ein bis zwei Minuten fertig, mit Dateien und Werkzeugen länger. Wenn Sie aufhören zu warten, läuft der Turn trotzdem und wird berechnet; brechen Sie ihn ab, wenn Sie ihn nicht mehr brauchen.
• Eine Abfrage (GET), die 502, 503, 504 oder einen Netzwerkfehler erhält, darf immer wiederholt werden. POST /v1/turns wiederholen Sie nur mit demselben Idempotency-Key: Sie erhalten den ursprünglichen Turn zurück, keinen zweiten bezahlten.
• Ein Netzwerkfehler ist kein Ergebnis. Ein POST /v1/turns, der in einen Timeout lief, hat den Turn womöglich schon gestartet: Markieren Sie den Auftrag nicht als fehlgeschlagen, senden Sie dieselbe Anfrage später mit demselben Idempotency-Key erneut, und sie liefert diesen Turn. Geben Sie der Dokumentenerkennung keine Frist unter einigen Stunden: Zeigen Sie „läuft noch“. Senden Sie Connection: close, damit eine hängende Verbindung den nächsten Aufruf nicht blockiert.
• Ein fehlgeschlagener Turn wird erneut gesendet, nicht als Fehler des Auftrags angezeigt. Endet ein Turn mit failed und SUBAGENT_BLOCKED oder SUBAGENT_PARTIAL (ein Worker hat abgelehnt oder nicht fertig gemacht), sendet Ihre App „Bearbeite Auftrag 42“ mit wachsendem Abstand erneut, jedes Mal mit neuem Idempotency-Key. Das ist sicher: Der Bereich setzt den Auftrag bei den Status fort, die er in Ihrer App schon gesetzt hat. Aus der Antwort wird nichts geparst; nach dem letzten Versuch geht der Auftrag zur Prüfung.
• Wiederholen Sie ein 429 wegen eines Limits nie vor Retry-After; ein Kundenlimit (ohne Retry-After) und ein 402 lassen sich durch Wiederholen nicht aufheben.

Die Tabelle der Wiederholungen · Webhooks

Dateien

Laden Sie eine Datei in den Bereich hoch (Multipart, Feld file, bis 200 MB) und geben Sie ihre file_id im Turn an; vom Agenten erzeugte Dateien kommen im Turn als Links zurück. Dateinamen dürfen in jeder Sprache sein: Senden Sie den Namen als einfaches UTF-8 im Parameter filename (curl -F und fetch mit FormData tun das), er kommt unverändert als name zurück, und ein Download trägt ihn auch als filename* (RFC 5987).

FID=$(curl -s -X POST $BASE/spaces/$SLUG/files -H "Authorization: Bearer $KEY" \
  -F 'file=@./invoice.pdf' | jq -r .file_id)

curl -s -X POST $BASE/turns -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"space":"'"$SLUG"'","text":"Summarise this invoice","file_ids":["'"$FID"'"]}'

Dateien in der Referenz · Dateinamen

Spracheingabe

Ein Nutzer Ihrer App kann eine Nachricht sprechen oder eine Audiodatei senden. Laden Sie die Aufnahme wie jede Datei hoch und geben Sie ihre file_id als voice_file_id im Turn an (text ist dann optional). Sie wird serverseitig mit derselben Spracherkennung wie eine Telegram-Sprachnachricht transkribiert, der Turn läuft mit dem Transkript als Nachricht des Nutzers, und die Aufnahme bleibt als Anhang im Bereich. Das Transkript kommt im Feld voice des Turns zurück (status: pending → done, transcript), damit Ihre App dem Nutzer seine Worte zeigt.

FID=$(curl -s -X POST $BASE/spaces/$SLUG/files -H "Authorization: Bearer $KEY" \
  -F 'file=@./voice.webm;type=audio/webm' | jq -r .file_id)

curl -s -X POST $BASE/turns -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -H "Idempotency-Key: $(uuidgen)" \
  -d '{"space":"'"$SLUG"'","voice_file_id":"'"$FID"'"}'

# GET /v1/turns/{id} → "voice": {"status": "done", "transcript": "Where is my order 42?", ...}

Formate: webm/opus, ogg, m4a/mp4, mp3, wav (sonst 415 UNSUPPORTED_MEDIA_TYPE), bis 100 MB (413 VOICE_TOO_LARGE). Eine Aufnahme ohne Sprache beendet den Turn mit VOICE_EMPTY, eine nicht erkennbare mit TRANSCRIPTION_FAILED: Bitten Sie den Nutzer, es zu wiederholen oder zu tippen. Die Transkription wird minutengenau in Energie dem Zahler des Turns berechnet und ist Teil von energy_used. Geben Sie Ihren Schlüssel nie an den Browser: Die Seite nimmt auf (MediaRecorder) und sendet das Audio an Ihr Backend, das die Datei hochlädt und den Turn mit seinem Schlüssel erstellt.

Spracheingabe in der Referenz

Live-Anrufe aus Ihrer App

Ein „Octo anrufen“-Button in Ihrer App: Ihr Nutzer spricht mit Octo per Stimme in Ihrem Bereich, ohne Konto bei uns. Ihr Server fordert mit seinem Schlüssel einen Anruf für diesen Nutzer (end_user_ref) an und erhält einen einmaligen join_url, 5 Minuten gültig; Ihre Seite öffnet ihn in einem Popup (oder einem iframe mit allow="microphone"): ein Sprachraum im Browser (WebRTC), nur dieser Nutzer und Octo. Der Anruf läuft als dieser Nutzer, wie seine Turns; Transkript und Zusammenfassung bleiben bei ihm, der Anruf wird dem Konto des Schlüssels in Energie berechnet.

curl -s -X POST $BASE/spaces/$SLUG/calls -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"end_user_ref":"cust-42","display_name":"Maria","lang":"en"}'

# → {"join_url": "https://…/app-call/…", "expires_at": "…", "max_minutes": 30, ...}
# afterwards: GET $BASE/spaces/$SLUG/calls/{call_id} → state, energy, transcript, summary_turn_id

Live-Anrufe in der Referenz

Abrechnung und Limits in Energie

• Die API meldet Kosten und Limits nur in Energie. Jeder Turn wird dem Konto berechnet, dem der Bereich gehört; die verbrauchte Energie, alle Multiplikatoren eingerechnet, steht in energy_used, der Verbrauch pro Kunde in GET /v1/usage.
• Limits sind Energie: Jeder Schlüssel hat ein Tageslimit (Standard 50 Energie, Rücksetzung um 00:00 UTC), der Unterschlüssel einer App kann ein Monatslimit haben, und ein Kunde ein Gesamtlimit total_limit_energy.
• 402 INSUFFICIENT_CREDITS: das Guthaben ist aufgebraucht und muss aufgeladen werden.
• 429 QUOTA_EXCEEDED: ein Schlüssel-, Kunden- oder Zeitfensterlimit; die Antwort enthält details.reason und Energiebeträge (cap_energy, spent_today_energy, remaining_energy), der Header Retry-After sagt, wann Sie es erneut versuchen dürfen, nie früher.
• Während einer Plattformwartung wird ein Turn trotzdem angenommen (202) und wartet als queued, bis die Wartung endet; die Antwort enthält maintenance und Retry-After, wenn das erwartete Ende bekannt ist.
• Es gibt kein Ratenlimit für Anfragen: Der Verbrauch wird durch Guthaben und Limits begrenzt.
• Die alten Dollar-Felder (billed_cost_usd, spend_usd, cap_usd und die übrigen *_usd) kommen noch neben den Energiefeldern, sind aber veraltet und entfallen am 2026-10-28.

Alle Fehlercodes · Grenzen · Abrechnung