Entwickler
API-Überblick
Betten Sie den Agenten per HTTP-API in Ihre eigene App ein: Schlüssel und ihr Geltungsbereich, end_user_ref, der Ablauf einer Anfrage, Webhooks, Abrechnung und eine erste Anfrage in einer Minute.
Zuletzt aktualisiert:
Auf dieser Seite
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.
| Schlüsselbereich | Was er steuert |
|---|---|
| Nur von diesem Schlüssel angelegte Bereiche (empfohlen) | Über POST /v1/spaces mit diesem Schlüssel angelegte Bereiche |
| Ein Bereich | Der eine genannte Bereich |
| Alle meine Bereiche | Alle Bereiche des Kontos |
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}'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. Webhooks
- Das Ergebnis eines Turns ist Text für Menschen. Strukturierte Daten liefert der Agent über Ihre eigenen Werkzeuge (MCP oder REST). Werkzeuge und MCP
Abrechnung und Limits
- Jeder Turn wird dem Konto des Schlüsseleigentümers berechnet; die Kosten stehen in
billed_cost_usd. 402 INSUFFICIENT_CREDITS: das Guthaben ist aufgebraucht und muss aufgeladen werden.429 QUOTA_EXCEEDED: Tageslimit des Schlüssels, Kundenlimit oder Zeitfensterlimit; beachten Sie Retry-After.- Es gibt kein Ratenlimit für Anfragen: Der Verbrauch wird durch Guthaben und Limits begrenzt.