API-Dokumentation

Aurora Agents API

Alles, was Ihre Entwickler brauchen, um die KI-Agenten von Aurora mit Ihrem CRM, ERP oder TMS zu verbinden: Authentifizierung, Aufgaben, Konversationen, Tools, Webhooks, Token-Limits und Abrechnung.

Schnellstart Agenten-Referenz

Einführung

Mit der Aurora-API kann Ihr CRM, ERP, TMS oder jedes Backend Arbeit an die KI-Agenten von Aurora übergeben und strukturierte Ergebnisse erhalten. Jeder Agent hat einen festen Satz an Aufgabentypen mit dokumentierten Eingaben und JSON-Ausgaben, sodass sich Ihr System auf die Form der Antwort verlassen kann.

BASEhttps://api.auroraaisystems.com/v1

Format: JSON über HTTPS, UTF-8. Senden Sie Content-Type: application/json mit jedem Request-Body.
Zeiten: ISO 8601 in UTC, z. B. 2026-10-09T08:14:03Z. Abrechnungsmonate beginnen am 1. um 00:00 UTC.
IDs: mit Präfix nach Objekttyp — task_, thr_, msg_, tool_, doc_, whk_, evt_, inv_. Agenten nutzen lesbare IDs wie carla.
Beträge: Dezimalbeträge in EUR, z. B. 699.00.
Request-IDs: Jede Antwort enthält den Header Aurora-Request-Id. Geben Sie ihn an, wenn Sie den Support kontaktieren.

Die Agenten

Agenten-ID	Agent	Wichtigste Aufgabentypen
carla	Carla — Koordinatorin für Transportanfragen	`transport_request.extract`, `transport_request.qualify`
rio	Rio — Koordinator für Disposition und Frachtführer	`carrier.match`, `carrier.request_offers`
quinn	Quinn — Spezialistin für Angebote und Preise	`quote.create`, `quote.compare_offers`
victor	Victor — Sales Development Representative	`lead.qualify`, `lead.research`
mara	Mara — Marketing-Managerin	`content.plan`, `content.draft`
sofia	Sofia — Leiterin Kundensupport	`ticket.triage`, `ticket.reply`
ada	Ada — Buchhaltungsassistentin	`invoice.extract`, `invoice.match`
paul	Paul — Einkaufsspezialist	`rfq.create`, `offers.compare`
hugo	Hugo — HR- und Recruiting-Partner	`job_ad.draft`, `applications.organize`
lex	Lex — Assistent für Recht und Compliance	`contract.review`, `contract.draft`
iris	Iris — Analystin für Daten und Reporting	`data.ask`, `report.generate`
atlas	Atlas — Stabschef	`task.route`, `brief.generate`

Ihr Konto, Ihre Agenten und Integrationen werden beim Onboarding gemeinsam mit Ihnen eingerichtet. Testschlüssel gibt es nach dem Kickoff, Live-Schlüssel beim Go-live. Bis dahin lässt sich alles auf dieser Seite in der Sandbox ausprobieren.

Schnellstart

Vier Schritte von einer E-Mail im Posteingang zu einem strukturierten Datensatz in Ihrem CRM.

1. Testschlüssel hinterlegen

Bewahren Sie Schlüssel als Umgebungsvariable auf Ihrem Server auf. Niemals in einen Browser, eine mobile App oder ein öffentliches Repository.

Terminal

export AURORA_API_KEY="aur_test_…"

2. Aufgabe anlegen

Bitten Sie Carla, eine Kunden-E-Mail in eine Transportanfrage umzuwandeln. metadata kommt unverändert zurück, damit Sie das Ergebnis Ihrem CRM-Datensatz zuordnen können.

curl https://api.auroraaisystems.com/v1/agents/carla/tasks \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transport_request.extract",
    "input": {
      "channel": "email",
      "from": "mihai@agrodelta.example",
      "subject": "Truck Pitesti - Lyon",
      "body": "Hi, we need a truck from Pitești to Lyon next week, 14 europallets ~9t, not stackable. Can you send a price?"
    },
    "metadata": {
      "crm_record_id": "REQ-2041"
    }
  }'

202 Accepted

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "type": "transport_request.extract",
  "status": "queued",
  "metadata": {
    "crm_record_id": "REQ-2041"
  },
  "created_at": "2026-10-09T08:14:03Z"
}

3. Ergebnis abrufen

Registrieren Sie einen Webhook und empfangen Sie task.completed, oder fragen Sie die Aufgabe ab, bis ihr Status final ist.

curl https://api.auroraaisystems.com/v1/tasks/task_01J9Z3K8R4 \
  -H "Authorization: Bearer $AURORA_API_KEY"

200 OK

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "type": "transport_request.extract",
  "status": "completed",
  "output": {
    "transport_request": {
      "pickup": {
        "city": "Pitești",
        "country": "RO",
        "postcode": null,
        "date": null
      },
      "delivery": {
        "city": "Lyon",
        "country": "FR",
        "postcode": null
      },
      "cargo": {
        "pallet_type": "EUR",
        "pallets": 14,
        "stackable": false,
        "weight_kg": 9000,
        "loading_meters": 5.6,
        "adr": false
      },
      "missing_fields": [
        "pickup.date",
        "delivery.postcode"
      ],
      "language": "en",
      "confidence": 0.93
    }
  },
  "handoffs": [
    {
      "agent_id": "quinn",
      "task_id": "task_01J9Z3M2QP",
      "type": "quote.create",
      "mode": "auto"
    }
  ],
  "parent_task_id": null,
  "escalation": null,
  "error": null,
  "usage": {
    "input_tokens": 3120,
    "output_tokens": 640,
    "total_tokens": 3760
  },
  "metadata": {
    "crm_record_id": "REQ-2041"
  },
  "created_at": "2026-10-09T08:14:03Z",
  "completed_at": "2026-10-09T08:14:09Z"
}

4. Verwenden

Schreiben Sie output.transport_request in Ihren CRM-Datensatz. Carla hat die Anfrage außerdem automatisch an Quinn übergeben — ihr Angebot kommt als weiteres task.completed-Ereignis, sobald der Kunde die fehlenden Angaben geschickt hat.

Authentifizierung

Authentifizieren Sie jede Anfrage mit einem geheimen Schlüssel im Header Authorization.

HTTP-Header

Authorization: Bearer aur_live_4f9c…

Schlüsselpräfix	Umgebung	Verhalten
`aur_test_`	Sandbox	Dieselben Agenten und dieselbe API. 500.000 kostenlose Tokens pro Monat. Tool-Aufrufe und Webhooks gehen an Ihre Test-Endpunkte. Nie berechnet.
`aur_live_`	Produktion	Echte Arbeit, gemessen und berechnet. Ausgegeben beim Go-live.

Scopes und Einschränkungen

Jeder Schlüssel lässt sich auf bestimmte Scopes und Agenten beschränken und kann ein eigenes monatliches Token-Limit haben. Verfügbare Scopes: agents:read, agents:write, tasks:read, tasks:write, threads:write, tools:write, knowledge:write, webhooks:write, usage:read, limits:write, billing:read.

Erstellen, beschränken und rotieren Sie Schlüssel in der Konsole. Ein widerrufener Schlüssel funktioniert sofort nicht mehr.
Für ein Chat-Widget auf Ihrer Website rufen Sie Aurora aus Ihrem Backend auf — nie aus dem Browser des Besuchers.
Ein fehlender oder ungültiger Schlüssel liefert 401 authentication_error; ein Schlüssel ohne passenden Scope liefert 403 permission_denied.

Grundkonzepte

Objekt	Was es ist
Agent	Ein konfigurierter KI-Mitarbeiter mit einer Aufgabe. Sein Manifest vereint Persona, Skills, Tools, Wissen, Schutzmechanismen und Limits.
Aufgabe	Eine Arbeitseinheit für einen Agenten: ein Typ, eine Eingabe und nach Abschluss eine JSON-Ausgabe. Aufgaben laufen asynchron.
Thread & Nachricht	Eine Konversation — ein Support-Chat, ein WhatsApp-Austausch. Der Thread speichert den Verlauf; jede Nachricht erhält die Antwort des Agenten.
Tool	Eine Aktion in Ihren Systemen, die ein Agent aufrufen darf, etwa einen Kunden finden oder einen Auftrag anlegen.
Wissensdokument	Eine Datei oder ein Text, auf den der Agent zurückgreifen kann: Tarife, Bedingungen, Richtlinien, Vorlagen.
Übergabe	Die Weitergabe eines fertigen Ergebnisses an den nächsten Agenten, automatisch oder nach Ihrer Bestätigung.
Verbrauch & Limits	Pro Modellaufruf gemessene Tokens; sie steuern Warnungen, Limits und die Position für zusätzliche Tokens auf Ihrer Rechnung.
Ereignis	Eine Webhook-Benachrichtigung, dass etwas passiert ist — eine Aufgabe ist abgeschlossen, ein Limit erreicht, eine Rechnung bezahlt.

Agenten

Das Agent-Objekt ist das Manifest des Agenten: wie er klingt, was er kann, worauf er zugreifen darf und wo er aufhört. Sie können alles lesen; ändern lassen sich Persona, Status und Limits.

Das Agent-Objekt

Agent-Objekt

{
  "id": "carla",
  "object": "agent",
  "name": "Carla",
  "title": "Transport Request Coordinator",
  "status": "active",
  "persona": {
    "traits": [
      "meticulous",
      "calm under volume",
      "politely persistent"
    ],
    "tone": {
      "formality": 3,
      "description": "Warm and precise"
    },
    "languages": [
      "en",
      "ro",
      "de"
    ],
    "reply_in_sender_language": true,
    "signature": "Carla, dispatch desk"
  },
  "skills": [
    "transport_request.extract",
    "transport_request.qualify",
    "transport_request.follow_up"
  ],
  "tools": [
    "crm.find_customer",
    "crm.create_request"
  ],
  "knowledge": [
    "kb_lanes",
    "kb_general_terms"
  ],
  "guardrails": {
    "never": [
      "quote_prices",
      "invent_missing_data"
    ],
    "handover_when": [
      "adr_goods",
      "oversized_cargo",
      "estimated_value_eur > 20000"
    ]
  },
  "handoffs": [
    {
      "on": "transport_request.qualified",
      "to": "quinn",
      "task_type": "quote.create",
      "mode": "auto"
    }
  ],
  "limits": {
    "monthly_token_limit": null,
    "max_output_tokens": 4000
  },
  "created_at": "2026-10-01T09:00:00Z",
  "updated_at": "2026-10-06T15:20:11Z"
}

Parameter	Beschreibung
id string	Lesbare Agenten-ID, z. B. `carla`. Ändert sich nie, auch wenn Sie den Agenten umbenennen.
status enum	`active`, `paused` oder `configuring`. Pausierte Agenten lehnen neue Aufgaben mit `409` ab.
persona object	Anzeigename, Eigenschaften, Ton (Förmlichkeit 1–5), Sprachen, ob in der Sprache des Absenders geantwortet wird, und Signatur.
skills array	Aufgabentypen, die dieser Agent ausführt. Siehe Agenten-Referenz.
tools array	Namen der Tools, die dieser Agent aufrufen darf.
knowledge array	Wissenssammlungen, die der Agent nutzen darf.
guardrails object	Was der Agent nie tut und wann er an einen Menschen übergibt. Nur lesbar.
handoffs array	Welches Ergebnis an welchen Agenten geht, und wie. Nur lesbar.
limits object	Monatliches Token-Limit für diesen Agenten (oder `null` für den gemeinsamen Pool) und maximale Output-Tokens pro Modellaufruf.

Agenten auflisten

GET/v1/agents

curl https://api.auroraaisystems.com/v1/agents \
  -H "Authorization: Bearer $AURORA_API_KEY"

Einen Agenten abrufen

GET/v1/agents/{agent_id}

Einen Agenten aktualisieren

PATCH/v1/agents/{agent_id}

Nur die folgenden Felder lassen sich über die API ändern. Skills, Tools, Schutzmechanismen und Übergaben ändern Sie gemeinsam mit unserem Team, damit jede Änderung in der Sandbox getestet wird, bevor sie Ihre Kunden erreicht.

Parameter	Beschreibung
persona.display_name string	Der Name, den Kunden sehen, z. B. wenn Sie Carla passend zu Ihrer Marke umbenennen.
persona.tone.formality integer 1–5	1 ist sehr förmlich, 5 sehr locker.
persona.languages array	ISO-639-1-Codes der Sprachen, in denen der Agent schreibt, z. B. `["en","ro","de"]`.
persona.reply_in_sender_language boolean	In der Sprache der eingehenden Nachricht antworten, sofern sie in der Liste steht.
persona.signature string	Grußformel in ausgehenden Nachrichten, bis zu 60 Zeichen.
status enum	`active` oder `paused`.
limits.monthly_token_limit integer oder null	Monatliche Obergrenze für diesen Agenten innerhalb Ihres Pools.
limits.max_output_tokens integer	Bis zu 4.000, sofern nicht anders vereinbart.

curl -X PATCH https://api.auroraaisystems.com/v1/agents/carla \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": {
      "tone": {
        "formality": 2
      },
      "signature": "Carla, dispatch desk — Northline Logistics"
    }
  }'

Aufgaben

Eine Aufgabe ist eine Arbeitseinheit für einen Agenten. Aufgaben laufen asynchron: Sie legen eine an und erhalten das Ergebnis per Webhook oder Polling.

Aufgabe anlegen

POST/v1/agents/{agent_id}/tasks

Parameter	Beschreibung
type string erforderlich	Ein vom Agenten unterstützter Aufgabentyp, z. B. `transport_request.extract`.
input object erforderlich	Eingabe für den Aufgabentyp. Die Felder je Typ stehen in der Agenten-Referenz; ungültige Eingaben liefern `422`.
metadata object	Bis zu 20 Schlüssel-Wert-Paare, die unverändert zurückkommen, z. B. Ihre CRM-Datensatz-ID.
callback_url string	Sendet die Ereignisse dieser Aufgabe an diese URL statt an Ihre registrierten Webhooks.
thread_id string	Hängt die Aufgabe an eine Konversation, damit der Agent deren Verlauf sieht.
priority enum	`normal` (Standard) oder `high`.
handoff enum	`auto`, `suggest` oder `none`. Standard ist das Manifest des Agenten.
max_output_tokens integer	Senkt das Output-Limit für diese Aufgabe.

Senden Sie einen Idempotency-Key-Header, damit eine wiederholte Anfrage nie eine doppelte Aufgabe anlegt. Die Antwort ist 202 Accepted mit der Aufgabe im Status queued.

Das Aufgaben-Objekt

Aufgaben-Objekt

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "type": "transport_request.extract",
  "status": "completed",
  "output": {
    "transport_request": {
      "pickup": {
        "city": "Pitești",
        "country": "RO",
        "postcode": null,
        "date": null
      },
      "delivery": {
        "city": "Lyon",
        "country": "FR",
        "postcode": null
      },
      "cargo": {
        "pallet_type": "EUR",
        "pallets": 14,
        "stackable": false,
        "weight_kg": 9000,
        "loading_meters": 5.6,
        "adr": false
      },
      "missing_fields": [
        "pickup.date",
        "delivery.postcode"
      ],
      "language": "en",
      "confidence": 0.93
    }
  },
  "handoffs": [
    {
      "agent_id": "quinn",
      "task_id": "task_01J9Z3M2QP",
      "type": "quote.create",
      "mode": "auto"
    }
  ],
  "parent_task_id": null,
  "escalation": null,
  "error": null,
  "usage": {
    "input_tokens": 3120,
    "output_tokens": 640,
    "total_tokens": 3760
  },
  "metadata": {
    "crm_record_id": "REQ-2041"
  },
  "created_at": "2026-10-09T08:14:03Z",
  "completed_at": "2026-10-09T08:14:09Z"
}

Aufgabenstatus

Status	Bedeutung
`queued`	Angenommen und wartet auf Ausführung.
`running`	Der Agent arbeitet daran.
`requires_action`	Der Agent hat ein Tool im Client-Modus aufgerufen und wartet auf Ihr Ergebnis. Siehe Tool-Ergebnisse übermitteln.
`completed`	Abgeschlossen; `output` enthält das Ergebnis.
`escalated`	Ein Schutzmechanismus hat die Arbeit an einen Menschen übergeben. `escalation` enthält den Grund und eine Zusammenfassung für Ihr Team.
`failed`	Konnte nicht abgeschlossen werden; `error` erklärt warum. Von uns verursachte Fehler werden nicht berechnet.
`cancelled`	Von Ihnen abgebrochen. Bereits verbrauchte Tokens werden berechnet.

Eine Aufgabe abrufen

GET/v1/tasks/{task_id}

Aufgaben auflisten

GET/v1/tasks

Parameter	Beschreibung
agent_id string	Nur Aufgaben dieses Agenten.
status enum	Nur Aufgaben in diesem Status.
type string	Nur dieser Aufgabentyp.
created_after / created_before timestamp	Zeitfenster.
limit / cursor integer / string	Siehe Paginierung.

Tool-Ergebnisse übermitteln

POST/v1/tasks/{task_id}/tool_outputs

Ruft ein Agent ein im Client-Modus registriertes Tool auf, pausiert die Aufgabe in requires_action, und Sie erhalten task.requires_action:

Aufgabe wartet auf Ihr Tool-Ergebnis

{
  "id": "task_01J9Z3K8R4",
  "object": "task",
  "agent_id": "carla",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "tool_calls": [
      {
        "id": "call_7Hk2",
        "tool": "crm.find_customer",
        "arguments": {
          "email": "mihai@agrodelta.example"
        }
      }
    ]
  }
}

curl https://api.auroraaisystems.com/v1/tasks/task_01J9Z3K8R4/tool_outputs \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_7Hk2",
        "output": {
          "customer_id": "C-1042",
          "name": "Agro Delta SRL",
          "payment_terms_days": 30
        }
      }
    ]
  }'

Eine Aufgabe abbrechen

POST/v1/tasks/{task_id}/cancel

Aufgaben in queued, running oder requires_action können abgebrochen werden. Bereits verbrauchte Tokens werden berechnet.

Nachrichten & Threads

Nutzen Sie Threads für Konversationen — einen Support-Chat, einen WhatsApp-Austausch, einen internen Assistenten. Der Thread speichert den Verlauf; jede gesendete Nachricht liefert die Antwort des Agenten.

Einen Thread anlegen

POST/v1/threads

Parameter	Beschreibung
agent_id string erforderlich	Der Agent, dem die Konversation gehört, z. B. `sofia`.
channel enum	`chat`, `email`, `whatsapp` oder `internal`. Bestimmt Formatierung und Länge.
contact object	Name, E-Mail und Telefon der schreibenden Person. Dient dazu, Daten nachzuschlagen, die der Agent mit ihr teilen darf.
metadata object	Wird unverändert zurückgegeben.

curl https://api.auroraaisystems.com/v1/threads \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sofia",
    "channel": "whatsapp",
    "contact": {
      "name": "Mihai Popa",
      "phone": "+40700000000"
    },
    "metadata": {
      "crm_contact_id": "C-1042-01"
    }
  }'

Eine Nachricht senden

POST/v1/threads/{thread_id}/messages

curl https://api.auroraaisystems.com/v1/threads/thr_01J9ZC6Y2B/messages \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Hello, where is our shipment to Lyon?",
    "stream": false
  }'

Antwort des Agenten

{
  "id": "msg_01J9ZC7T1D",
  "object": "message",
  "thread_id": "thr_01J9ZC6Y2B",
  "role": "agent",
  "agent_id": "sofia",
  "content": "Hi Mihai! Your shipment SHP-5530 left Pitești on 14 October and is now near Dijon. The driver’s ETA in Lyon is today at 16:30.",
  "handover": false,
  "sources": [
    "tms:shipment:SHP-5530"
  ],
  "usage": {
    "input_tokens": 2210,
    "output_tokens": 96,
    "total_tokens": 2306
  },
  "created_at": "2026-10-16T13:02:44Z"
}

Ist handover true, hat der Agent aufgehört und ein Mensch sollte übernehmen; der Nachrichteninhalt teilt das dem Kunden mit, und task.escalated enthält die Zusammenfassung für Ihr Team.

Streaming

Setzen Sie "stream": true, um die Antwort als Server-Sent Events (text/event-stream) zu erhalten, während sie geschrieben wird. Ereignisse: message.delta, message.completed und error.

Ereignisstrom

event: message.delta
data: {"delta":"Hi Mihai! Your shipment SHP-5530 "}

event: message.delta
data: {"delta":"left Pitești on 14 October and is now near Dijon…"}

event: message.completed
data: {"id":"msg_01J9ZC7T1D","handover":false,"usage":{"input_tokens":2210,"output_tokens":96,"total_tokens":2306}}

Nachrichten auflisten und einen Thread löschen

GET/v1/threads/{thread_id}/messages

DELETE/v1/threads/{thread_id}

Das Löschen eines Threads entfernt ihn mit allen Nachrichten dauerhaft.

Tools

Tools lassen Agenten in Ihren Systemen handeln. Sie beschreiben eine Aktion mit einem JSON Schema; der Agent entscheidet, wann und mit welchen Argumenten er sie aufruft. In Ihren Systemen läuft nichts, wofür Sie kein Tool registriert haben.

Ein Tool registrieren

POST/v1/tools

Parameter	Beschreibung
name string erforderlich	Eindeutiger Name, z. B. `crm.find_customer`. Buchstaben, Ziffern, Punkte und Unterstriche.
description string erforderlich	Was das Tool tut und wann es zu verwenden ist. Agenten lesen das, also seien Sie konkret.
input_schema object erforderlich	JSON Schema für die Argumente.
mode enum erforderlich	`webhook`: Wir rufen Ihre URL auf. `client`: Die Aufgabe pausiert, und Sie führen das Tool aus.
url string	Im Webhook-Modus erforderlich. Nur HTTPS.
agents array erforderlich	IDs der Agenten, die das Tool aufrufen dürfen.
timeout_ms integer	Wie lange wir im Webhook-Modus auf Ihre Antwort warten. Standard 10.000, maximal 30.000.

curl https://api.auroraaisystems.com/v1/tools \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm.find_customer",
    "description": "Find a customer in our CRM by email address or VAT number.",
    "mode": "webhook",
    "url": "https://crm.yourcompany.example/aurora/tools",
    "agents": [
      "carla",
      "sofia",
      "ada"
    ],
    "timeout_ms": 10000,
    "input_schema": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email"
        },
        "vat_id": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }'

Webhook-Modus

Wir senden einen signierten POST an Ihre URL — dasselbe Signaturverfahren wie bei Webhooks — und warten auf Ihre JSON-Antwort.

Wir senden

{
  "tool": "crm.find_customer",
  "tool_call_id": "call_7Hk2",
  "task_id": "task_01J9Z3K8R4",
  "agent_id": "carla",
  "arguments": {
    "email": "mihai@agrodelta.example"
  }
}

Sie antworten (200 OK)

{
  "output": {
    "customer_id": "C-1042",
    "name": "Agro Delta SRL",
    "payment_terms_days": 30
  }
}

Liefert Ihr Endpunkt einen Fehler oder ein Timeout, erfährt der Agent, dass das Tool fehlgeschlagen ist. Er versucht es einmal erneut, macht ohne Ergebnis weiter, wenn das sicher möglich ist, oder eskaliert die Aufgabe.

Client-Modus

Die Aufgabe pausiert mit Status requires_action. Führen Sie die Aktion selbst aus und senden Sie das Ergebnis per Tool-Ergebnisse übermitteln. Nutzen Sie den Client-Modus, wenn Ihr System keine eingehenden Aufrufe empfangen kann.

Tools auflisten und löschen

GET/v1/tools

DELETE/v1/tools/{tool_id}

Wissen

Laden Sie die Dokumente hoch, auf die sich Agenten stützen sollen — Preislisten, Bedingungen, Richtlinien, Vorlagen, frühere Fälle. Bei einer Aufgabe ruft der Agent die relevanten Passagen ab und nutzt Ihre Fakten statt Allgemeinwissen.

Ein Dokument hochladen

POST/v1/knowledge/documents

Parameter	Beschreibung
file file	PDF, DOCX, XLSX, CSV, TXT, MD oder HTML, bis 50 MB. Als `multipart/form-data` senden.
url / text string	Statt einer Datei eine öffentliche URL zum Abrufen oder reiner Text, als JSON.
title string erforderlich	Wird in der Konsole und in den Quellen des Agenten angezeigt.
agents array erforderlich	IDs der Agenten, die das Dokument nutzen dürfen.
collection string	Gruppiert Dokumente, z. B. `kb_lanes`.

cURL — Multipart-Upload

curl https://api.auroraaisystems.com/v1/knowledge/documents \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -F file=@road-tariffs-2026.xlsx \
  -F title="Road tariffs 2026" \
  -F "agents[]=quinn" \
  -F "agents[]=carla"

201 Created

{
  "id": "doc_8KQ2M1",
  "object": "knowledge_document",
  "title": "Road tariffs 2026",
  "status": "processing",
  "agents": [
    "quinn",
    "carla"
  ],
  "bytes": 184320,
  "created_at": "2026-10-06T10:41:00Z"
}

Der Status wechselt von processing zu ready oder failed, und Sie erhalten knowledge.document.ready oder knowledge.document.failed. Hochladen und Indexieren sind kostenlos; in einer Aufgabe genutzte Passagen zählen als Input-Tokens.

Auflisten, abrufen und löschen

GET/v1/knowledge/documents

GET/v1/knowledge/documents/{document_id}

DELETE/v1/knowledge/documents/{document_id}

Das Löschen eines Dokuments entfernt die Datei und ihren Index; Agenten nutzen es nicht mehr.

Übergaben

Agenten geben Arbeit so weiter wie Ihr Team: Carla vervollständigt eine Transportanfrage, Quinn kalkuliert sie, Rio bucht den Frachtführer. Übergaben sind im Manifest jedes Agenten festgelegt und werden beim Setup mit Ihnen vereinbart.

Modus	Was passiert
`auto`	Die nächste Aufgabe wird automatisch angelegt, mit der fertigen Ausgabe als Eingabe.
`suggest`	Die Ausgabe enthält `suggested_handoffs`; nichts passiert, bis Sie bestätigen.
`none`	Keine Übergabe; Ihr System entscheidet, was als Nächstes passiert.

Eine vorgeschlagene Übergabe bestätigen

POST/v1/tasks/{task_id}/handoff

curl https://api.auroraaisystems.com/v1/tasks/task_01J9Z3K8R4/handoff \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "quinn",
    "type": "quote.create",
    "input_overrides": {
      "pricing_rules": "key_accounts"
    }
  }'

Jede Übergabe wird im Array handoffs der übergeordneten Aufgabe und in parent_task_id der untergeordneten Aufgabe festgehalten und löst handoff.created aus. Atlas kann längere Ketten für Sie koordinieren.

Webhooks

Webhooks senden Ereignisse an Ihr System, sobald sie passieren, damit Sie nicht abfragen müssen.

Einen Endpunkt registrieren

POST/v1/webhooks

curl https://api.auroraaisystems.com/v1/webhooks \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://crm.yourcompany.example/hooks/aurora",
    "events": [
      "task.completed",
      "task.escalated",
      "limit.reached",
      "invoice.created"
    ],
    "description": "CRM production"
  }'

201 Created — das Secret wird nur einmal angezeigt

{
  "id": "whk_3MZ81Q",
  "object": "webhook",
  "url": "https://crm.yourcompany.example/hooks/aurora",
  "events": [
    "task.completed",
    "task.escalated",
    "limit.reached",
    "invoice.created"
  ],
  "secret": "whsec_…",
  "created_at": "2026-10-06T10:02:00Z"
}

Ereignisse

Ereignis	Gesendet, wenn
`task.completed`	Eine Aufgabe wurde mit einer Ausgabe abgeschlossen.
`task.failed`	Eine Aufgabe konnte nicht abgeschlossen werden.
`task.requires_action`	Eine Aufgabe wartet auf Ihr Tool-Ergebnis.
`task.escalated`	Ein Schutzmechanismus hat eine Aufgabe an einen Menschen übergeben.
`handoff.created`	Ein Agent hat Arbeit an einen anderen Agenten übergeben.
`message.completed`	Ein Agent hat eine Antwort in einem Thread fertiggestellt.
`knowledge.document.ready`	Ein Dokument ist indexiert und in Gebrauch.
`knowledge.document.failed`	Ein Dokument konnte nicht verarbeitet werden.
`usage.threshold_reached`	Der Verbrauch hat eine Ihrer Warnschwellen überschritten.
`limit.reached`	Ein Token-Limit oder eine Ausgabenobergrenze wurde erreicht.
`invoice.created`	Eine neue Rechnung wurde ausgestellt.
`invoice.paid`	Eine Rechnung wurde bezahlt.
`invoice.payment_failed`	Eine automatische Zahlung ist fehlgeschlagen.
`agent.updated`	Persona, Status oder Limits eines Agenten haben sich geändert.

Payload

Ereignis-Envelope

{
  "id": "evt_01J9Z4D2WQ",
  "object": "event",
  "type": "task.completed",
  "created_at": "2026-10-09T08:14:09Z",
  "data": {
    "object": {
      "id": "task_01J9Z3K8R4",
      "object": "task",
      "agent_id": "carla",
      "status": "completed",
      "output": {
        "transport_request": {
          "…": "…"
        }
      },
      "metadata": {
        "crm_record_id": "REQ-2041"
      }
    }
  }
}

Signaturen prüfen

Jeder Webhook und jeder Tool-Aufruf im Webhook-Modus trägt den Header Aurora-Signature, z. B. t=1760000043,v1=6c1f…. Berechnen Sie einen HMAC-SHA256 mit Ihrem Endpunkt-Secret über {t}.{raw body}, vergleichen Sie ihn in konstanter Zeit mit v1 und lehnen Sie Anfragen ab, die älter als 5 Minuten sind.

import crypto from "node:crypto";

// rawBody: the request body exactly as received, before JSON parsing
export function verifyAuroraSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 || "", "hex");
  const exp = Buffer.from(expected, "hex");
  return given.length === exp.length && crypto.timingSafeEqual(given, exp);
}

Zustellung und Wiederholungen

Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status und erledigen Sie die schwere Arbeit im Hintergrund. Andernfalls wiederholen wir mit exponentiellem Backoff bis zu 24 Stunden lang. Ereignisse können mehrfach oder in anderer Reihenfolge eintreffen — speichern Sie die Ereignis-id und ignorieren Sie Duplikate.

Verbrauch & Token-Limits

Jeder Modellaufruf für Ihre Aufgaben wird in Tokens gemessen. Der Verbrauch steuert Ihre Warnungen, Ihre Limits und die Position für zusätzliche Tokens auf Ihrer Rechnung.

Wie Tokens gezählt werden

Input-Tokens: Anweisungen und Persona des Agenten, Ihre Aufgabeneingabe, Gesprächsverlauf, abgerufene Wissenspassagen und Tool-Ergebnisse.
Output-Tokens: alles, was der Agent schreibt, einschließlich Argumenten für Tool-Aufrufe.
Der Verbrauch einer Aufgabe ist die Summe all ihrer Modellaufrufe. Input- und Output-Tokens kosten gleich viel.
Jeder Agent umfasst 10.000.000 Tokens pro Monat, gebündelt über Ihre Agenten und am 1. um 00:00 UTC zurückgesetzt. Zusätzliche Tokens kosten 15 € pro Million, gemessen pro 1.000.
Hochladen und Indexieren von Wissen ist kostenlos. Aufgaben, die wegen eines Fehlers auf unserer Seite scheitern, werden nicht berechnet.

Jede Aufgabe und jede Nachricht liefert ein usage-Objekt, und jede Antwort trägt diese Header:

Header	Wert
`Aurora-Tokens-Used`	Von dieser Anfrage verbrauchte Tokens.
`Aurora-Tokens-Remaining`	Verbleibende inkludierte Tokens im laufenden Abrechnungsmonat, kontoweit.
`Aurora-Spend-Remaining`	Verbleibende EUR bis zur Ausgabenobergrenze, wenn die Regel `cap` ist.

Verbrauch abrufen

GET/v1/usage

Parameter	Beschreibung
period YYYY-MM	Abrechnungsmonat. Standard ist der aktuelle.
group_by enum	`agent` (Standard), `api_key` oder `day`.

curl https://api.auroraaisystems.com/v1/usage?period=2026-10&group_by=agent \
  -H "Authorization: Bearer $AURORA_API_KEY"

200 OK

{
  "object": "usage",
  "period": "2026-10",
  "included_tokens": 30000000,
  "used_tokens": 18412360,
  "remaining_included_tokens": 11587640,
  "overage_tokens": 0,
  "overage_amount_eur": 0.00,
  "by_agent": [
    {
      "agent_id": "carla",
      "input_tokens": 6904112,
      "output_tokens": 1301228,
      "total_tokens": 8205340,
      "tasks": 1874
    },
    {
      "agent_id": "quinn",
      "input_tokens": 5140215,
      "output_tokens": 964665,
      "total_tokens": 6104880,
      "tasks": 932
    },
    {
      "agent_id": "rio",
      "input_tokens": 3512018,
      "output_tokens": 590122,
      "total_tokens": 4102140,
      "tasks": 611
    }
  ],
  "updated_at": "2026-10-19T08:00:00Z"
}

Limits

Limits legen fest, was passiert, wenn Ihre inkludierten Tokens aufgebraucht sind, und verhindern, dass ein einzelner Agent oder eine Integration den ganzen Pool verbraucht. Sie legen die Regel bei der Bestellung fest und können sie jederzeit ändern; Änderungen gelten sofort.

Das Limits-Objekt

GET/v1/limits

Limits-Objekt

{
  "object": "limits",
  "overage_policy": "cap",
  "monthly_spend_cap_eur": 500.00,
  "alert_thresholds_pct": [
    50,
    80,
    100
  ],
  "alert_emails": [
    "finance@yourcompany.example"
  ],
  "agents": {
    "carla": {
      "monthly_token_limit": 12000000
    },
    "quinn": {
      "monthly_token_limit": null
    }
  },
  "api_keys": {
    "key_crm_prod": {
      "monthly_token_limit": null
    }
  },
  "rate_limits": {
    "requests_per_minute_per_agent": 60,
    "tokens_per_minute_per_agent": 200000
  },
  "max_output_tokens": 4000
}

Limits aktualisieren

PATCH/v1/limits

Parameter	Beschreibung
overage_policy enum	`hard_stop`: bei den inkludierten Tokens stoppen. `cap`: zusätzliche Tokens bis `monthly_spend_cap_eur` erlauben. `unlimited`: zusätzliche Tokens ohne Obergrenze erlauben.
monthly_spend_cap_eur number	Maximale monatliche Ausgaben für zusätzliche Tokens, zzgl. MwSt. Verwendet mit `cap`.
alert_thresholds_pct array	Prozentsätze der inkludierten Tokens, die `usage.threshold_reached` auslösen.
alert_emails array	Wer Warn-E-Mails erhält.
agents.{agent_id}.monthly_token_limit integer oder null	Monatslimit für einen Agenten.
api_keys.{key_id}.monthly_token_limit integer oder null	Monatslimit für einen API-Schlüssel.

curl -X PATCH https://api.auroraaisystems.com/v1/limits \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "overage_policy": "cap",
    "monthly_spend_cap_eur": 800,
    "agents": {
      "quinn": {
        "monthly_token_limit": 8000000
      }
    }
  }'

Rate Limits sind nur lesbar; kontaktieren Sie uns, um sie zu erhöhen.

Wenn ein Limit erreicht ist

Situation	Antwort
Inkludierte Tokens aufgebraucht und Regel ist `hard_stop`	`402` mit Code `quota_exceeded`
Ausgabenobergrenze erreicht (Regel `cap`)	`402` mit Code `spend_cap_reached`
Monatslimit eines Agenten erreicht	`402` mit Code `agent_limit_reached`, nur für diesen Agenten
Monatslimit eines API-Schlüssels erreicht	`402` mit Code `key_limit_reached`, nur für diesen Schlüssel

Bereits laufende Aufgaben werden normal beendet. Neue Aufgaben und Nachrichten werden bis zum nächsten Abrechnungsmonat oder bis zur Erhöhung des Limits abgelehnt. Ein limit.reached-Ereignis wird einmal pro Limit und Monat gesendet.

402 Payment Required

{
  "error": {
    "type": "limit_error",
    "code": "spend_cap_reached",
    "message": "Monthly spend cap of €500.00 reached. Raise monthly_spend_cap_eur or wait until 1 November 2026.",
    "request_id": "req_01J9ZB4N7F"
  }
}

Abrechnung & Rechnungen

Lesen Sie Ihr Abonnement, sehen Sie die nächste Rechnung vorab und rufen Sie Rechnungen ab — etwa um sie automatisch in Ihrem ERP zu buchen.

Die Setup-Gebühr wird bei der Bestellung berechnet.
Abonnements beginnen beim Go-live; der erste Monat wird tagesgenau anteilig berechnet.
Am 1. jedes Monats wird eine Rechnung ausgestellt: Abonnements für den neuen Monat im Voraus, zusätzliche Tokens des Vormonats nachträglich und bei Kartenzahlung die Gebühr des Zahlungsdienstleisters zum Selbstkostenpreis, soweit zulässig.
Karte und SEPA-Lastschrift werden am Rechnungsdatum automatisch belastet; Überweisungen sind innerhalb von 14 Tagen fällig.
Für rumänische Unternehmen werden Rechnungen zusätzlich über e-Factura übermittelt.

Abonnement

GET/v1/billing/subscription

Abonnement-Objekt

{
  "object": "subscription",
  "status": "active",
  "currency": "EUR",
  "agents": [
    {
      "agent_id": "carla",
      "status": "active",
      "unit_price": 699.00,
      "active_since": "2026-10-06"
    },
    {
      "agent_id": "quinn",
      "status": "active",
      "unit_price": 699.00,
      "active_since": "2026-10-06"
    },
    {
      "agent_id": "rio",
      "status": "active",
      "unit_price": 699.00,
      "active_since": "2026-10-06"
    }
  ],
  "current_period": {
    "start": "2026-10-01",
    "end": "2026-10-31"
  },
  "overage_price_per_million": 15.00,
  "payment_method": {
    "type": "sepa_debit",
    "last4": "3000"
  }
}

Agenten hinzufügen oder entfernen

POST/v1/billing/subscription/agents

curl https://api.auroraaisystems.com/v1/billing/subscription/agents \
  -H "Authorization: Bearer $AURORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "sofia"
  }'

Der Agent wird im Status configuring hinzugefügt und wird aktiv, sobald er für Sie eingerichtet ist; die Abrechnung beginnt mit der Aktivierung, anteilig. Braucht er eine neue Integration, stimmen wir den Umfang vorher mit Ihnen ab.

DELETE/v1/billing/subscription/agents/{agent_id}

Entfernt den Agenten zum Ende des laufenden Abrechnungsmonats.

Nächste Rechnung

GET/v1/billing/upcoming

Rechnungsvorschau

{
  "object": "invoice_preview",
  "issue_date": "2026-11-01",
  "currency": "EUR",
  "lines": [
    {
      "description": "Agent subscription — November 2026",
      "quantity": 3,
      "unit_price": 699.00,
      "amount": 2097.00
    },
    {
      "description": "Extra tokens — October 2026",
      "quantity": 0,
      "unit": "1M tokens",
      "unit_price": 15.00,
      "amount": 0.00
    }
  ],
  "subtotal": 2097.00,
  "vat": {
    "treatment": "domestic",
    "rate": 21,
    "amount": 440.37
  },
  "total": 2537.37
}

Rechnungen

GET/v1/billing/invoices

GET/v1/billing/invoices/{invoice_id}

GET/v1/billing/invoices/{invoice_id}/pdf

Rechnungs-Objekt

{
  "id": "inv_2026_11_0042",
  "object": "invoice",
  "number": "AUR 0142",
  "status": "paid",
  "issue_date": "2026-11-01",
  "due_date": "2026-11-01",
  "currency": "EUR",
  "subtotal": 2097.00,
  "vat_amount": 440.37,
  "total": 2537.37,
  "payment": {
    "method": "sepa_debit",
    "status": "succeeded",
    "paid_at": "2026-11-04T06:12:00Z"
  },
  "e_invoice": {
    "system": "RO e-Factura",
    "status": "accepted"
  },
  "pdf_url": "https://api.auroraaisystems.com/v1/billing/invoices/inv_2026_11_0042/pdf"
}

Parameter	Beschreibung
number string	Serie und Nummer, wie von unserem Rechnungssystem vergeben.
status enum	`open`, `paid`, `overdue` oder `void`.
payment object	Methode und Status der automatischen Zahlung, falls vorhanden.
e_invoice object oder null	Für rumänische Unternehmen: `pending`, `sent`, `accepted` oder `rejected` in e-Factura.

Fehler

Fehler nutzen Standard-HTTP-Statuscodes und einen einheitlichen JSON-Body.

422 Unprocessable Entity

{
  "error": {
    "type": "validation_error",
    "code": "missing_field",
    "message": "input.body is required when input.channel is \"email\".",
    "param": "input.body",
    "request_id": "req_01J9ZA2K5C"
  }
}

Status	Typ	Wann
400	`invalid_request_error`	Fehlerhaftes JSON, unbekannter Parameter oder falscher Typ.
401	`authentication_error`	Fehlender, ungültiger oder widerrufener API-Schlüssel.
402	`limit_error`	Ein Token-Limit oder eine Ausgabenobergrenze wurde erreicht. `code` sagt, welche.
403	`permission_denied`	Dem Schlüssel fehlt der Scope oder Agentenzugriff für diese Anfrage.
404	`not_found`	Das Objekt existiert nicht oder ist für diesen Schlüssel nicht sichtbar.
409	`conflict`	Idempotency-Key mit anderem Body wiederverwendet, oder der Objektstatus erlaubt die Aktion nicht.
413	`payload_too_large`	Request-Body oder Datei überschreitet die Größenbeschränkung.
422	`validation_error`	Die Eingabe entspricht nicht dem Schema des Aufgabentyps; `param` nennt das Feld.
429	`rate_limit_error`	Zu viele Anfragen oder Tokens pro Minute.
500	`api_error`	Auf unserer Seite ist etwas schiefgelaufen. Sie können mit demselben Idempotency-Key gefahrlos erneut senden.
503	`overloaded`	Vorübergehendes Kapazitätsproblem. Mit Backoff erneut versuchen.

Jeder Fehler enthält eine request_id. Senden Sie sie an support@auroraaisystems.com, wenn Sie Hilfe brauchen.

Rate Limits

Standardmäßig akzeptiert jeder Agent 60 Anfragen und 200.000 Tokens pro Minute in Ihrem Konto. Höhere Limits auf Anfrage.

Header	Bedeutung
`RateLimit-Limit`	Erlaubte Anfragen im aktuellen Zeitfenster.
`RateLimit-Remaining`	Verbleibende Anfragen im Zeitfenster.
`RateLimit-Reset`	Sekunden bis zum Zurücksetzen des Zeitfensters.
`Retry-After`	Mit 429 gesendet: Sekunden bis zum nächsten Versuch.

Wiederholen Sie 429 und 503 mit exponentiellem Backoff und Jitter. Andere 4xx-Fehler nicht ohne Änderung der Anfrage wiederholen.

Idempotenz

Senden Sie bei POST-Anfragen einen Idempotency-Key-Header — einen beliebigen eindeutigen String, etwa eine UUID. Kommt derselbe Schlüssel innerhalb von 24 Stunden mit demselben Body erneut, erhalten Sie die ursprüngliche Antwort statt einer doppelten Aufgabe. Derselbe Schlüssel mit anderem Body liefert 409 conflict.

Paginierung

Listen-Endpunkte liefern Seiten mit bis zu 100 Objekten (Standard 20). Übergeben Sie limit und für die nächste Seite cursor.

Listenantwort

{
  "object": "list",
  "data": [
    {
      "id": "task_01J9Z3K8R4",
      "object": "task",
      "status": "completed"
    }
  ],
  "has_more": true,
  "next_cursor": "c_9f3a1e"
}

Versionierung

Legen Sie eine Version mit dem Header Aurora-Version fest, z. B. Aurora-Version: 2026-10-01. Ohne Header wird die Version Ihres Kontos verwendet, die beim Go-live festgelegt wird. Inkompatible Änderungen erscheinen nur in neuen datierten Versionen, angekündigt im Änderungsprotokoll. Neue Felder, Ereignis- und Aufgabentypen können jederzeit hinzukommen — ignorieren Sie Felder, die Sie nicht kennen.

Agenten-Referenz

Aufgabentypen und Beispiel-Payloads für jeden Agenten. Die genauen Eingabefelder und Ausgabeschemata für Ihr Konto — einschließlich der beim Setup für Ihre Systeme ergänzten Felder — finden Sie in der Konsole und über GET /v1/agents/{agent_id}.

Carla — Koordinatorin für Transportanfragen

Agenten-ID carla, Operations. Agentenseite

Aufgabentyp	Was er tut
`transport_request.extract`	Macht aus einer E-Mail, Nachricht oder einem Dokument eine strukturierte Transportanfrage
`transport_request.qualify`	Prüft Vollständigkeit und Passung zu Ihren Relationen und Regeln
`transport_request.follow_up`	Entwirft oder sendet die Nachricht, mit der fehlende Angaben beim Kunden erfragt werden

Beispiel-Eingabe — POST /v1/agents/carla/tasks

{
  "type": "transport_request.extract",
  "input": {
    "channel": "email",
    "from": "mihai@agrodelta.example",
    "subject": "Truck Pitesti - Lyon",
    "body": "Hi, we need a truck from Pitești to Lyon next week, 14 europallets ~9t, not stackable. Can you send a price?"
  },
  "callback_url": "https://crm.yourcompany.example/hooks/aurora"
}

Beispiel-Ausgabe — transport_request.extract

{
  "transport_request": {
    "pickup": {
      "city": "Pitești",
      "country": "RO",
      "postcode": null,
      "date": null
    },
    "delivery": {
      "city": "Lyon",
      "country": "FR",
      "postcode": null
    },
    "cargo": {
      "pallet_type": "EUR",
      "pallets": 14,
      "stackable": false,
      "weight_kg": 9000,
      "loading_meters": 5.6,
      "adr": false
    },
    "missing_fields": [
      "pickup.date",
      "delivery.postcode"
    ],
    "language": "en",
    "confidence": 0.93
  }
}

Rio — Koordinator für Disposition und Frachtführer

Agenten-ID rio, Operations. Agentenseite

Aufgabentyp	Was er tut
`carrier.match`	Erstellt aus Ihren eigenen Daten eine Shortlist von Frachtführern für eine Ladung
`carrier.request_offers`	Sendet Preisanfragen an Frachtführer und sammelt die Antworten
`shipment.update`	Verarbeitet ein Status-, ETA- oder Verspätungsereignis und informiert die richtigen Personen
`documents.check`	Prüft CMR, POD und Fotos auf Vollständigkeit

Beispiel-Eingabe — POST /v1/agents/rio/tasks

{
  "type": "carrier.match",
  "input": {
    "shipment_id": "SHP-5530",
    "lane": {
      "from": "RO-110",
      "to": "FR-69"
    },
    "vehicle": "tautliner",
    "max_buy_price": 1260
  }
}

Beispiel-Ausgabe — carrier.match

{
  "candidates": [
    {
      "carrier_id": "car_118",
      "name": "Carpat Trans SRL",
      "lane_loads_90d": 4,
      "last_price": 1190,
      "score": 0.91
    },
    {
      "carrier_id": "car_052",
      "name": "Dunav Freight EOOD",
      "lane_loads_90d": 2,
      "last_price": 1240,
      "score": 0.78
    }
  ],
  "recommended": "car_118"
}

Quinn — Spezialistin für Angebote und Preise

Agenten-ID quinn, Vertrieb & Marketing. Agentenseite

Aufgabentyp	Was er tut
`quote.create`	Kalkuliert eine Anfrage und erstellt das Angebot
`quote.compare_offers`	Bewertet Frachtführer- oder Lieferantenangebote nach Ihren Regeln
`quote.follow_up`	Fasst bei offenen Angeboten nach und dokumentiert Gewinn- oder Verlustgründe

Beispiel-Eingabe — POST /v1/agents/quinn/tasks

{
  "type": "quote.create",
  "input": {
    "transport_request_id": "REQ-2041",
    "pricing_rules": "default",
    "currency": "EUR",
    "formats": [
      "email",
      "pdf"
    ]
  }
}

Beispiel-Ausgabe — quote.create

{
  "quote": {
    "id": "Q-7781",
    "sell_price": 1560,
    "currency": "EUR",
    "breakdown": {
      "estimated_buy_price": 1240,
      "margin": 320
    },
    "margin_pct": 20.5,
    "valid_until": "2026-10-12T14:00:00Z",
    "approval_required": false,
    "files": [
      {
        "type": "pdf",
        "file_id": "file_q7781"
      }
    ]
  }
}

Victor — Sales Development Representative

Agenten-ID victor, Vertrieb & Marketing. Agentenseite

Aufgabentyp	Was er tut
`lead.qualify`	Bewertet einen Lead anhand Ihres idealen Kundenprofils
`lead.research`	Fasst zusammen, was ein Unternehmen macht und warum es Sie brauchen könnte
`outreach.draft`	Schreibt eine erste Nachricht oder eine Nachfass-Sequenz
`deal.next_step`	Schlägt die nächste Aktion für einen Deal vor und plant sie ein

Beispiel-Eingabe — POST /v1/agents/victor/tasks

{
  "type": "lead.qualify",
  "input": {
    "lead": {
      "name": "Elena Radu",
      "company": "Nordic Pack SRL",
      "website": "https://nordicpack.example",
      "message": "We’re looking for a partner for weekly groupage to Germany."
    },
    "criteria": "default"
  }
}

Beispiel-Ausgabe — lead.qualify

{
  "qualification": {
    "score": 82,
    "fit": "high",
    "segment": "manufacturing",
    "reasons": [
      "recurring weekly volume",
      "lane matches RO to DE groupage"
    ],
    "next_step": {
      "type": "call_proposal",
      "draft_id": "drf_441"
    }
  }
}

Mara — Marketing-Managerin

Agenten-ID mara, Vertrieb & Marketing. Agentenseite

Aufgabentyp	Was er tut
`content.plan`	Erstellt einen Redaktionskalender für einen Zeitraum und ein Ziel
`content.draft`	Schreibt Beiträge, Newsletter, Artikel oder Anzeigentexte
`seo.brief`	Erstellt ein SEO-Briefing mit Suchintention und Gliederung
`review.reply`	Entwirft eine Antwort auf eine Bewertung oder einen Kommentar

Beispiel-Eingabe — POST /v1/agents/mara/tasks

{
  "type": "content.draft",
  "input": {
    "format": "social_post",
    "channel": "linkedin",
    "topic": "Weekly groupage Romania to Germany",
    "audience": "operations managers in manufacturing",
    "language": "en",
    "variants": 2
  }
}

Beispiel-Ausgabe — content.draft

{
  "drafts": [
    {
      "id": "drf_901",
      "text": "Every Thursday a truck leaves Romania for Germany with room for your pallets…",
      "status": "waiting_for_approval"
    },
    {
      "id": "drf_902",
      "text": "Groupage to Germany shouldn’t mean waiting for a full truck…",
      "status": "waiting_for_approval"
    }
  ]
}

Sofia — Leiterin Kundensupport

Agenten-ID sofia, Kundenservice. Agentenseite

Aufgabentyp	Was er tut
`ticket.triage`	Klassifiziert eine Nachricht nach Thema und Dringlichkeit und leitet sie weiter
`ticket.reply`	Beantwortet eine Kundennachricht mit Daten aus Ihren Systemen
`claim.intake`	Eröffnet einen Schadensfall und sammelt die nötigen Dokumente

Beispiel-Eingabe — POST /v1/agents/sofia/tasks

{
  "type": "ticket.reply",
  "input": {
    "channel": "whatsapp",
    "contact": {
      "phone": "+40700000000"
    },
    "message": "Hello, where is our shipment to Lyon?",
    "context_lookup": true
  }
}

Beispiel-Ausgabe — ticket.reply

{
  "reply": {
    "text": "Hi Mihai! Your shipment SHP-5530 left Pitești on 14 October and is now near Dijon…",
    "language": "en",
    "sources": [
      "tms:shipment:SHP-5530"
    ]
  },
  "ticket": {
    "id": "T-9120",
    "status": "answered",
    "handover": false
  }
}

Ada — Buchhaltungsassistentin

Agenten-ID ada, Finanzen & Einkauf. Agentenseite

Aufgabentyp	Was er tut
`invoice.extract`	Liest eine Lieferantenrechnung in strukturierte Daten ein
`invoice.match`	Gleicht eine Rechnung mit Aufträgen, Sendungen oder Bestellungen ab
`payments.reconcile`	Gleicht einen Kontoauszug mit offenen Posten ab
`collections.remind`	Bereitet eine Zahlungserinnerung vor oder sendet sie

Beispiel-Eingabe — POST /v1/agents/ada/tasks

{
  "type": "invoice.extract",
  "input": {
    "file_id": "file_inv_4471",
    "match_against": [
      "orders",
      "shipments"
    ]
  }
}

Beispiel-Ausgabe — invoice.extract

{
  "invoice": {
    "supplier": {
      "name": "Carpat Trans SRL",
      "vat_id": "RO00000000"
    },
    "number": "4471",
    "issue_date": "2026-10-17",
    "currency": "EUR",
    "total": 1250.00,
    "lines": [
      {
        "description": "Transport Pitești–Lyon",
        "amount": 1210.00
      },
      {
        "description": "Waiting time",
        "amount": 40.00
      }
    ]
  },
  "match": {
    "shipment_id": "SHP-5530",
    "expected_total": 1210.00,
    "difference": 40.00,
    "status": "needs_review"
  }
}

Paul — Einkaufsspezialist

Agenten-ID paul, Finanzen & Einkauf. Agentenseite

Aufgabentyp	Was er tut
`rfq.create`	Schreibt und sendet eine Angebotsanfrage
`offers.compare`	Vergleicht Lieferantenangebote anhand gewichteter Kriterien
`po.draft`	Entwirft eine Bestellung zur Freigabe
`spend.analyze`	Schlüsselt Ausgaben nach Kategorie und Lieferant auf

Beispiel-Eingabe — POST /v1/agents/paul/tasks

{
  "type": "offers.compare",
  "input": {
    "rfq_id": "rfq_311",
    "criteria": {
      "price": 0.5,
      "delivery": 0.3,
      "terms": 0.2
    }
  }
}

Beispiel-Ausgabe — offers.compare

{
  "ranking": [
    {
      "supplier": "Supplier C",
      "unit_price": 326,
      "delivery_days": 2,
      "includes_fitting": true,
      "score": 0.86
    },
    {
      "supplier": "Supplier A",
      "unit_price": 318,
      "delivery_days": 1,
      "includes_fitting": false,
      "score": 0.82
    },
    {
      "supplier": "Supplier B",
      "unit_price": 299,
      "delivery_days": 21,
      "includes_fitting": false,
      "score": 0.64
    }
  ],
  "recommendation": "Supplier C if fitting is needed; otherwise Supplier A."
}

Hugo — HR- und Recruiting-Partner

Agenten-ID hugo, Personal & Recht. Agentenseite

Aufgabentyp	Was er tut
`job_ad.draft`	Schreibt eine Stellenanzeige aus einem kurzen Briefing
`applications.organize`	Macht aus Lebensläufen eine strukturierte Tabelle — ohne Bewertung
`interview.schedule`	Schlägt Termine für Gespräche vor und bucht sie
`documents.expiry`	Listet bald ablaufende Führerscheine, Zertifikate und Verträge auf

Beispiel-Eingabe — POST /v1/agents/hugo/tasks

{
  "type": "documents.expiry",
  "input": {
    "within_days": 60,
    "document_types": [
      "driving_licence",
      "adr_certificate",
      "tachograph_card",
      "contract"
    ]
  }
}

Beispiel-Ausgabe — documents.expiry

{
  "expiring": [
    {
      "employee_id": "emp_204",
      "document": "tachograph_card",
      "expires_on": "2026-11-28"
    },
    {
      "employee_id": "emp_118",
      "document": "tachograph_card",
      "expires_on": "2026-12-03"
    },
    {
      "employee_id": "emp_311",
      "document": "tachograph_card",
      "expires_on": "2026-12-09"
    }
  ],
  "notified": [
    "employees",
    "fleet_manager"
  ]
}

Lex — Assistent für Recht und Compliance

Agenten-ID lex, Personal & Recht. Agentenseite

Aufgabentyp	Was er tut
`contract.review`	Prüft einen Vertrag anhand Ihres Playbooks
`contract.draft`	Entwirft ein Dokument aus Ihrer Vorlage
`contract.compare`	Erklärt die Unterschiede zwischen zwei Versionen
`claim.prepare`	Stellt eine Schadens- oder Verspätungsakte zusammen
`gdpr.request`	Erfasst und verfolgt eine Betroffenenanfrage

Beispiel-Eingabe — POST /v1/agents/lex/tasks

{
  "type": "contract.review",
  "input": {
    "file_id": "file_nordic_fta",
    "playbook": "transport_client_v3"
  }
}

Beispiel-Ausgabe — contract.review

{
  "review": {
    "issues": [
      {
        "clause": "7.2",
        "topic": "payment_term",
        "found": "90 days",
        "playbook": "max 45 days",
        "severity": "high",
        "suggested_text": "Payment within 45 days of the invoice date."
      },
      {
        "clause": "9.3",
        "topic": "liability_cap",
        "found": "EUR 500 per shipment",
        "playbook": "CMR limits",
        "severity": "high"
      },
      {
        "clause": "15.1",
        "topic": "auto_renewal",
        "found": "3 years",
        "playbook": "max 1 year",
        "severity": "medium"
      }
    ],
    "escalate": [
      {
        "clause": "12",
        "reason": "exclusive foreign jurisdiction"
      }
    ]
  }
}

Iris — Analystin für Daten und Reporting

Agenten-ID iris, Management. Agentenseite

Aufgabentyp	Was er tut
`data.ask`	Beantwortet eine Frage zu Ihren Daten, mit Quellen
`report.generate`	Erstellt einen geplanten KPI-Bericht
`anomaly.scan`	Sucht nach ungewöhnlichen Bewegungen in Ihren Kennzahlen

Beispiel-Eingabe — POST /v1/agents/iris/tasks

{
  "type": "data.ask",
  "input": {
    "question": "Why is our margin lower this month?",
    "sources": [
      "erp",
      "tms"
    ],
    "period": "2026-10"
  }
}

Beispiel-Ausgabe — data.ask

{
  "answer": {
    "text": "Gross margin is 14.2% against 17.9% last month…",
    "figures": [
      {
        "metric": "gross_margin_pct",
        "value": 14.2,
        "previous": 17.9
      }
    ],
    "sources": [
      "erp:invoices",
      "tms:shipments"
    ],
    "suggested_actions": [
      {
        "agent_id": "ada",
        "type": "collections.remind",
        "note": "invoice unbilled waiting time"
      }
    ]
  }
}

Atlas — Stabschef

Agenten-ID atlas, Management. Agentenseite

Aufgabentyp	Was er tut
`task.route`	Versteht eine Anfrage und leitet sie an den richtigen Agenten weiter
`brief.generate`	Erstellt ein Management-Briefing für einen Zeitraum
`meeting.summarize`	Macht aus Notizen oder einem Transkript Entscheidungen und Aufgaben
`followups.track`	Listet offene Punkte auf und hakt bei den Verantwortlichen nach

Beispiel-Eingabe — POST /v1/agents/atlas/tasks

{
  "type": "brief.generate",
  "input": {
    "period": "yesterday",
    "audience": "management",
    "agents": [
      "carla",
      "quinn",
      "rio",
      "ada",
      "paul",
      "lex"
    ]
  }
}

Beispiel-Ausgabe — brief.generate

{
  "brief": {
    "summary": "Yesterday: 38 transport requests, 21 quotes sent, 14 accepted.",
    "needs_decision": [
      {
        "ref": "PO-1204",
        "agent_id": "paul",
        "action": "approve purchase order"
      },
      {
        "ref": "contract_nordic_fta",
        "agent_id": "lex",
        "action": "sign off contract check"
      },
      {
        "ref": "client_agro_delta",
        "agent_id": "quinn",
        "action": "framework price"
      }
    ]
  }
}

Sicherheit & Daten

Bei Übertragung und Speicherung: Der gesamte Verkehr nutzt TLS; gespeicherte Daten sind im Ruhezustand verschlüsselt.
Nutzung Ihrer Daten: Ihre Eingaben, Ausgaben und Dokumente werden nur zur Ausführung Ihrer Aufgaben und zur Erbringung des Dienstes verarbeitet. Sie werden nicht zum Training von KI-Modellen verwendet.
Aufbewahrung: Ein- und Ausgaben von Aufgaben werden standardmäßig 90 Tage gespeichert. Legen Sie in der Konsole einen kürzeren Zeitraum fest — oder null, um sie nach Zustellung zu löschen. Threads, Aufgaben und Dokumente lassen sich jederzeit über die API löschen.
Zugriff: Schlüssel mit Scopes, Limits pro Schlüssel und ein Anfrageprotokoll mit Schlüssel und Request-ID für jeden Aufruf.
Datenschutz: Wir verarbeiten personenbezogene Daten in Ihrem Auftrag gemäß den Bedingungen zur Auftragsverarbeitung des Abonnements.

Änderungsprotokoll

2026-10-01

Erste öffentliche Version der API: Agenten, Aufgaben, Threads und Nachrichten mit Streaming, Tools, Wissen, Übergaben, Webhooks, Verbrauch und Limits, Abrechnung und Rechnungen.