API-Referenz
Diese Seite dokumentiert die HTTP-API, die Sie für die Entwicklung gegen Tietai verwenden: wie eine Anfrage einen Dienst erreicht, wie die Authentifizierung erfolgt und die Workflow-Engine-Endpunkte für Pipelines, Ausführungen, Agenten, den Knotenkatalog, Konnektoren, LLM-Modelle und den Copilot.
Alle unten aufgeführten Endpunkte und Felder wurden vom Gateway und der Servicequelle ausgelesen. Die Beispiele stammen nicht von einem Live-Server: Betrachten Sie die Antworttexte als Struktur und nicht als aufgezeichnete Ausgabe.
Wie Anfragen einen Dienst erreichen
Der gesamte Datenverkehr läuft über das API-Gateway. Eine Anfrage hat folgendes Format:
https://<api-host>/api/v1/<service>/<path>
Das Gateway ordnet <service> einem Backend zu und ändert den Pfad. Für die Workflow-Engine lautet der Dienstname hydra-platform, und /api/v1/hydra-platform/<path> wird als /api/<path> an die Workflow-Engine weitergeleitet. Die Workflow-Route /api/pipelines ist somit öffentlich wie folgt:
https://<api-host>/api/v1/hydra-platform/pipelines
<api-host> ist der API-Host Ihrer Bereitstellung (die Registerkarte „Agent-API“ im Produkt verwendet https://api.tiet.ai). Jeder Workflow-Engine-Pfad auf dieser Seite wird relativ zu /api/v1/hydra-platform angezeigt.
Andere Dienste verwenden dasselbe Muster mit eigenem Präfix. Einfache Präfixe wie /api/v1/pipelines, /api/v1/agents und /api/v1/llm-models verweisen auf den älteren Agentendienst, nicht auf die Workflow-Engine. FHIR wird über /api/v1/fhir/<path> erreicht, das Gateway leitet die Anfrage als /fhir/<path> an den FHIR-Dienst weiter. Siehe FHIR-Interoperabilität.
Authentifizierung
Sende bei jeder Anfrage ein Bearer-Token:
Authorization: Bearer <token>
Das Gateway akzeptiert zwei Arten von Token:
| Token | Wie das Gateway es erkennt | Wo man es bekommt |
|---|---|---|
| Benutzer JWT | Enthält Punkte | Anmeldung beim Produkt |
| API-Token | Keine Punkte (eine tia_m2m_... Zeichenkette) | Admin-Konsole, Plattform, API-Tokens (siehe API-Tokens) |
X-Organization-ID ist optional. Die Organisation wird aus dem Token abgeleitet. Wenn Sie den Header senden, prüft das Gateway, ob der Aufrufer Mitglied dieser Organisation ist, und antwortet andernfalls mit 403 bzw. {"detail":"forbidden: not a member of the requested organization"} Ein API-Token ist an die Organisation gebunden, die ihn erstellt hat.
Die Workflow-Engine validiert API-Token selbst, jedoch nur auf bestimmten Routen. Laut dem von mir gelesenen Quellcode sind dies POST /execute (Scope pipeline:{id}:execute oder pipelines:execute) und POST /v1/agents/{id}/invoke (Scope agent:{id}:execute) sowie die Manifest-, Instanz- und Deployment-Routen. Alle anderen Routen auf dieser Seite (Pipelines, Agents, Executions, Connectors, LLM-Modelle, Copilot) erwarten ein Benutzer-JWT. Ein dort gesendetes API-Token erhält den 401 {"error":"unauthorized: invalid token"}.
Öffentliche Wege
Diese Workflow-Engine-Pfade benötigen keine Gateway-Authentifizierung:
Pfad (unter /api/v1/hydra-platform) | Notiz |
|---|---|
health | Gesundheitscheck |
node-catalog und alles darunter | Metadaten zum Knotentyp. Die node-catalog/datasource/... Routen benötigen weiterhin ein JWT, da die Workflow-Engine dies selbst erzwingt. |
v1/agents/ | Der öffentliche Agentenaufruf-Endpunkt. Die Workflow-Engine prüft den API-Schlüssel selbst. |
files/, uploaded-files/ | Generierte Berichte herunterladen und Anhänge hochladen |
Einige andere Pfade sind öffentlich, da ihre Aufrufer kein Token besitzen und sich auf eigene Weise authentifizieren können: Sprachanruf- und Messaging-Webhooks, die Seite zum Teilen von 3D-Patientenbildern (public/exhibit-shares/, wobei das Freigabetoken im Pfad die Anmeldeinformationen sind) und schreibgeschützte Bildbetrachter-Routen unter conversations/.../exhibits/. Sie sind nicht für den allgemeinen Gebrauch bestimmt.
Versionierung
Die Versionsangabe ist v1 in /api/v1/. Die Gateway-Konfiguration führt X-API-Version als Versionsheader auf, ich habe jedoch keinen Code gefunden, der diese Angabe ausliest. Verlassen Sie sich daher nicht darauf. Innerhalb der Workflow-Engine enthalten nur die Agentenaufrufe und Traceroutes ein v1 -Segment.
Ratenbegrenzungen
Es gelten zwei Beschränkungen:
- Gateway: Standardmäßig 600 Anfragen pro Minute, gezählt pro Organisation und Client-IP. Die API-Sicherheitseinstellungen der Organisation können dies ändern: Der Schalter Enable rate limiting auf Security in der Admin-Konsole deaktiviert das Gateway-Limit für die Organisation, und der gespeicherte Wert
requests_per_minuteersetzt den Wert „600“ (die Admin-Konsole hat kein Feld für diese Zahl). Bei Überschreitung des Limits werden429mit{"detail":"Rate limit exceeded"}und den HeadernX-RateLimit-Limit,X-RateLimit-Remaining(0) undX-RateLimit-Resetgesendet. Diese Header erscheinen nur in der Statusmeldung 429, nicht in normalen Antworten. - Workflow-Engine: 100 Anfragen pro Minute und authentifiziertem Benutzer (pro Client-IP, wenn kein Benutzer vorhanden ist). Bei Überschreitung des Limits erhalten Sie
429mit einemRetry-After-Header und{"error":"rate limit exceeded","retry_after":60}.
Ich konnte keine Beschränkungen pro Endpunkt für Agenten-Chat, Copilot oder Exporte feststellen, und es gab auch keine Beschränkung der gleichzeitigen Ausführungen.
Fehler
Es gibt keinen einzelnen Fehlerumschlag.
| Quelle | Format | Beispiel |
|---|---|---|
| Tor | {"detail": "..."} | {"detail":"Authentication required"} (401), {"detail":"Invalid or expired token"} (401) |
| Workflow-Engine, die meisten Pipelines, Ausführungs- und Authentifizierungsfehler | {"error": "..."} | {"error":"pipeline not found"} |
| Workflow-Engine, zahlreiche Agenten, Konnektoren, Tools und LLM-Modell-Handler | reiner Textkörper | agent not found |
| Workflow-Engine, Agentenversionskonflikte | {"error": "...", "code": "...", ...} | {"code":"AGENT_DEPLOYED_IMMUTABLE", ...} |
Prüfen Sie zuerst den Statuscode und lesen Sie den Body nur dann als JSON, wenn die Content-Type. application/json ist.
Pagination
Die Konventionen unterscheiden sich je nach Endpunkt:
| Endpunkt | Parameter | Standard | Antwortschlüssel |
|---|---|---|---|
GET /pipelines | page, page_size oder limit, offset (expliziter limit / offset -Sieg) | Seite 1, Größe 10 | pipelines, total, page, page_size |
GET /executions | limit, offset | 10, 0 | entries, total, limit, offset, organization_id |
GET /agents, GET /connectors | limit, offset | 20, 0 | agents oder connectors, total_count, limit, offset |
GET /llm-models | limit, offset | 20, 0 | items, total, skip (der Versatz), limit |
Pipelines
Eine Pipeline ist ein Graph aus Knoten und Verbindungen. Zum Lesen und Auflisten ist ein authentifizierter Benutzer einer Organisation erforderlich. Zum Erstellen ist eine Schreibrolle (admin, editor, superuser, platform_manager, organization_admin, developer) oder eine Schreibberechtigung für Pipelines notwendig. Zum Löschen ist eine Administratorrolle (admin, superuser, platform_manager, organization_admin) oder eine Löschberechtigung erforderlich. Für die Schritte PUT (Bereitstellen oder Entfernen der Bereitstellung) konnte ich keine Rollenprüfung finden, außer der Zugehörigkeit zur Organisation, der die Pipeline gehört.
| Methode und Pfad | Zweck | Erfolg |
|---|---|---|
GET /pipelines | Listen Sie die Pipelines Ihrer Organisation auf | 200 |
POST /pipelines | Erstellen Sie eine Pipeline | 201 |
GET /pipelines/{id} | Holen Sie sich eine Pipeline | 200 |
PUT /pipelines/{id} | Teilaktualisierung | 200 |
DELETE /pipelines/{id} | Löschen | 204 |
POST /pipelines/{id}/deploy | In einer Umgebung bereitstellen | 200 |
POST /pipelines/{id}/undeploy | Setzen Sie den Status wieder auf active | 200 |
GET /pipelines/{id}/executions | Ausführungen dieser Pipeline | 200 |
GET /pipelines/{id}/history | Wer hat diese Pipeline verändert? | 200 |
{id} muss eine UUID sein, andernfalls ist die Antwort 400 {"error":"invalid uuid format"}.
Erstellen Sie eine Pipeline
Senden Sie die Knoten, Verbindungen und Variablen auf oberster Ebene. Ein verschachteltes definition. Objekt ist ebenfalls zulässig; sind beide vorhanden, haben die Listen der obersten Ebene Vorrang. Der Nachrichtentext muss im JSON- (oder YAML-)Format vorliegen. Jeder andere Inhaltstyp gibt 415 zurück.
curl -X POST "https://<api-host>/api/v1/hydra-platform/pipelines" \
-H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" \
-d '{
"name": "Echo example",
"description": "Passes the input through and formats it as JSON",
"nodes": [
{"id": "in1", "type": "input", "label": "Input", "config": {}},
{"id": "out1", "type": "output", "label": "Output", "config": {"format": "json"}}
],
"connections": [
{"id": "c1", "source_node": "in1", "source_port": "output",
"target_node": "out1", "target_port": "input"}
],
"variables": {}
}'
| Feld | Bedeutung | Standard |
|---|---|---|
name | Erforderlich | |
description | Freitext | leer |
version | Semver-Zeichenkette | 1.0.0 |
nodes[] | Mindestens eines ist erforderlich. Jedes hat id, type, label, config (und optional position, timeout in Sekunden, retry). | |
connections[] | id, source_node, source_port, target_node, target_port | |
variables | Entweder ein Objekt {"name": value} oder ein Array von {name, type, value, description} |
Die Werte für Knoten type sowie deren Ports und Konfiguration stammen aus dem Knotenkatalog. Die Knoten input und output verwenden die im Katalog aufgeführten Ports und das Feld format.
Die Antwort ist 201 mit der Pipeline: id, name, description, version (ein String), status, created_at, updated_at, created_by, nodes, connections, variables und einem Objekt definition, das diese wiederholt. variables wird immer als Array zurückgegeben. Der Server ordnet jedem Knoten eine Release zu, daher enthalten die Knoten in der Antwort zusätzliche Felder wie version und schema_digest. GET /pipelines gibt dieselben Pipelines ohne den Wrapper definition zurück.
Fehler:
| Status | Körper | Ursache |
|---|---|---|
| 400 | {"error":"name is required"} / {"error":"at least one node is required"} | Fehlender Name oder keine Knoten |
| 400 | {"error":"node release x@ is unavailable"} | type ist nicht in der Knotenregistrierung. (PUT antwortet stattdessen mit unknown node type: "x") |
| 403 | {"error":"forbidden: insufficient permissions"} | Keine Schreibrolle |
| 415 | {"error":"unsupported media type"} | Falsch Content-Type |
Auflisten, abrufen, aktualisieren, löschen
curl "https://<api-host>/api/v1/hydra-platform/pipelines?page=1&page_size=10" \
-H "Authorization: Bearer <jwt>"
{"pipelines": [ { "id": "...", "name": "...", "version": "1.0.0", "nodes": [], "connections": [], "variables": [] } ],
"total": 1, "page": 1, "page_size": 10}
PUT /pipelines/{id} ändert nur die von Ihnen gesendeten Felder (name, description, version, nodes, connections, variables, definition); der Rest bleibt erhalten. Im Gegensatz zu POST muss variables hier als Array vorliegen. Unbekannte Knotentypen werden mit dem Fehlercode 400 abgelehnt. Eine organisationsübergreifende ID beantwortet Frage 404 {"error":"pipeline not found"}.
DELETE gibt 204 ohne Antworttext zurück. Ich habe keine Prüfung gefunden, die das Löschen einer bereitgestellten Pipeline verhindert.
Bereitstellen und Entfernen der Bereitstellung
curl -X POST ".../pipelines/<id>/deploy" -H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" -d '{"environment": "<slug>"}'
Ein leerer Body wird in der Standardumgebung der Organisation bereitgestellt. Eine unbekannte oder archivierte Umgebung gibt 422 zurück. Der Status ändert sich zu deployed:<environment slug>. Durch Aufheben der Bereitstellung wird der Status wieder auf active gesetzt. Siehe Umgebungen und Bereitstellung.
Führe eine Pipeline aus
POST /execute benötigt ein Benutzer-JWT mit der Berechtigung pipeline:execute oder ein API-Token mit dem Bereich pipeline:{pipeline_id}:execute oder der organisationsweiten Berechtigung pipelines:execute.
| Feld | Bedeutung | Standard |
|---|---|---|
pipeline_id | Erforderlich | |
inputs | Objekt mit Eingabewerten. input wird als Alias akzeptiert. Eine explizite null gibt 400 input is required zurück. | {} |
async | true gibt sofort einen Wert zurück und läuft im Hintergrund. | false (läuft inline) |
environment | Umgebungs-Slug. Der Header X-Hydra-Environment wird verwendet, wenn dieser leer ist, andernfalls der Standardwert der Organisation. | Standardumgebung |
test_mode | true oder false überschreibt den eigenen Testmodus der Pipeline für diesen Durchlauf. | Pipeline-Einstellungen |
Mesh-Felder (segment_id, version, plan_id, run_id, envelope) sind für verteilte Läufe vorgesehen; siehe Run on mesh.
Synchron (Standard)
curl -X POST "https://<api-host>/api/v1/hydra-platform/execute" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"pipeline_id": "<uuid>", "inputs": {"patient_id": "TEST-001"}}'
Der Anruf hält die Verbindung aufrecht, bis der Durchlauf beendet ist und 200 antwortet:
{"execution_id": "...", "status": "completed", "outputs": {}, "node_results": {}}
outputs enthält die endgültigen Ausgaben und node_results einen Eintrag pro Knoten. Eine Pipeline, deren Knoten ausgefallen ist, liefert dennoch ein normales Ergebnis: Sie erhalten 200 mit "status": "failed" und einer error Nur ein Durchlauf, der gar nicht erst gestartet werden konnte, gibt einen 5xx-Fehler zurück.
Vom Motor verwendete Statuswerte: pending, running, completed, partial, failed, cancelled, waiting.
Ein Lauf, der wartet
Wenn ein Knoten den Lauf unterbricht (z. B. weil er auf ein externes Ereignis wartet), antwortet der synchrone Aufruf auf 202 mit status: "waiting", wait_token und resume_url (/api/execute/resume/<token>). Anschließend wird der Lauf fortgesetzt mit:
curl -X POST "https://<api-host>/api/v1/hydra-platform/execute/resume/<wait_token>" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" -d '{"payload": {"approved": true}}'
Die Workflow-Engine selbst authentifiziert diese Route nicht (das Token dient als Anmeldeinformation), sie befindet sich jedoch nicht auf der öffentlichen Liste des Gateways. Daher senden Sie über das Gateway weiterhin ein Bearer-Token. Die von der Workflow-Engine zurückgegebene resume_url beginnt mit /api/: Ersetzen Sie dieses Präfix durch /api/v1/hydra-platform/ wenn Sie über das Gateway aufrufen. Ein unbekanntes oder bereits verwendetes Token wird 404 {"error":"unknown or expired wait token"} zurückgegeben.
Asynchron
Bei "async": true ist die Antwort 202 {"execution_id": "...", "status": "pending"}. Abfrage GET /executions/{execution_id}. Abbrechen bei POST /executions/{execution_id}/cancel (nur für asynchrone Ausführungen, die noch im Speicher gehalten werden).
Ausführungen, Wiederholungsversuche, Statistiken
| Methode und Pfad | Zweck |
|---|---|
GET /executions | Verlauf. Abfrage: limit, offset, status, pipeline_id, from, to (RFC 3339), organization_id |
GET /executions/{id} | Eine Ausführung: execution_id, pipeline_id, status, started_at, completed_at, result, node_results, error |
POST /executions/{id}/cancel | Asynchronen Lauf abbrechen |
POST /execute/retry | Erneuter Start von einem ausgefallenen Knoten |
GET /stats | Aggregate für Ihre Organisation |
Benutzer, die nicht admin sind, sehen nur ihre eigenen Läufe.
Antworttext erneut senden (alle drei Felder sind erforderlich, sonst 400):
{"pipeline_id": "<uuid>", "execution_id": "<previous execution id>", "from_node_id": "<node id>"}
Es verwendet die gespeicherten Ausgaben der Knoten oberhalb von from_node_id wieder und gibt 200 mit derselben Struktur wie ein synchroner Lauf zurück. Es gibt 404 previous execution not found zurück, wenn die Ausführung unbekannt ist, zu einer anderen Pipeline oder Organisation gehört, und 409 wenn sich die Knotentypen der Pipeline seit dem ursprünglichen Lauf geändert haben oder der Lauf nicht wiederholt werden kann (z. B. weil die Eingaben oder Ergebnisse zu groß waren).
GET /stats gibt total_executions, successful_executions, failed_executions, total, by_status, by_pipeline, average_duration, active_pipelines, running, success_rate und failed_today zurück.
Schrittweises Debuggen
| Methode und Pfad | Zweck |
|---|---|
POST /execute/step | Sitzung starten. Körper {"pipeline_id": "...", "inputs": {}} |
POST /execute/step/{sessionId}/next | Führe den nächsten Knotensatz aus (ohne Rumpf) |
DELETE /execute/step/{sessionId}/cancel (oder POST) | Sitzung beenden, 204 |
Jede Antwort enthält die Werte session_id, step, total_steps, completed, batch_nodes und node_results. Diese Fehlermeldungen sind Klartext, kein JSON.
Agenten
| Methode und Pfad | Zweck |
|---|---|
GET /agents | Listen Sie die Vertreter Ihrer Organisation auf. |
GET /agents?base_templates=true | Agentenliste (Basisvorlage) |
POST /agents | Agenten erstellen, 201 |
GET /agents/{id}, PUT /agents/{id}, DELETE /agents/{id} | Lesen, aktualisieren, löschen |
POST /agents/{id}/deploy, POST /agents/{id}/undeploy | Bereitstellen oder entfernen |
POST /agents/{id}/instantiate | Erstellen Sie Ihren eigenen Agenten anhand einer Basisvorlage. Textkörper {"project_id": "...", "name": "..."} (project_id erforderlich) |
POST /agents/{id}/chat | Führen Sie den Agenten aus (siehe unten). |
GET, POST /agents/{id}/conversations | Konversationen. Auch /conversations/{cid}, /messages, /steps |
GET /agents/{id}/executions | Laufverlauf. Auch /executions/{execId}/steps und /events |
GET /agents/{id}/versions | Versionslebenszyklus (/versions/{v}, /versions/{v}/deploy) |
Listenfilter: limit, offset, type, is_active (true oder false), project_id. Die Organisation stammt aus Ihrem Token; org_id wird nur für Organisationen berücksichtigt, denen Sie angehören.
Basisvorlagen können nicht bereitgestellt oder ausgeführt werden. Der Aufruf von deploy oder chat auf einer solchen Vorlage gibt 400 base templates cannot be deployed or run; POST /instantiate first and use the resulting agent zurück. Die einzige Ausnahme bildet der Aufruf von chat auf einem Hilfsagenten, der vom Produkt selbst per Slug aufgerufen wird: Der Server führt dann die organisationseigene Instanz des Hilfsagenten aus.
Agenten erstellen
curl -X POST "https://<api-host>/api/v1/hydra-platform/agents" \
-H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" \
-d '{
"name": "Discharge summary helper",
"agent_type": "conversational",
"description": "Drafts a discharge summary from a note",
"prompt_template": "You summarize clinical notes for {{specialty}}.",
"temperature": 20
}'
| Feld | Bedeutung | Standard |
|---|---|---|
name | Erforderlich | |
agent_type | conversational, task, hybrid oder react | conversational |
prompt_template | Systemaufforderung. {{KEY}} Token werden zur Laufzeit von variables aufgefüllt. | |
slug | Kleinbuchstaben, Ziffern und Bindestriche | |
temperature | Ganze Zahl von 0 bis 100 | |
compliance_level | hipaa, fda, soc2, gdpr oder none | |
| Andere | model_config, max_tokens, streaming, use_memory, expose_as_inference, capabilities, tags, sub_agents, project_id, organization_id, version |
Ein bereitgestellter Agent ist eingefroren. Ein Agent PUT, der seine Konfiguration ändert, gibt mit der {"code":"AGENT_DEPLOYED_IMMUTABLE","error":"agent version ... is deployed and immutable; create a new version ... and deploy it"} die 409 zurück. Name, Beschreibung, Tags und das Aktivierungsflag können weiterhin bearbeitet werden. Erstellen Sie einen Entwurf mit der POST /agents/{id}/versions und stellen Sie ihn bereit.
Chatten Sie mit einem Mitarbeiter
POST /agents/{id}/chat mit einem Benutzer-JWT. Body:
| Feld | Bedeutung |
|---|---|
message | Erforderlich, es sei denn, es wird attachments gesendet |
stream | true für serverseitig gesendete Ereignisse |
history | Frühere Runden als {role, content} |
variables | Ein Objekt von Zeichenketten, die {{KEY}} in der Eingabeaufforderung ausfüllen. |
thinking, attachments, response_language, grounding | Optional |
Ohne stream ist die Antwort ein einzelnes JSON-Objekt. reasoning_content, tool_calls, tool_trace, suggestions und die Token-Anzahl werden weggelassen, wenn sie leer oder null ist:
{"content": "...", "input_tokens": 120, "output_tokens": 80}
Bei "stream": true ist die Antwort text/event-stream Jeder Frame besteht aus data: <json> einfachen Zeilen (event: Zeilen gibt es nicht), und alle 15 Sekunden wird ein Kommentar : keepalive gesendet:
data: {"type":"step","event":"llm_call","data":{"round":0,"tools":2},"ts":1760000000000}
data: {"reasoning_content":"..."}
data: {"content":"Partial answer text"}
data: {"content":"","done":"true","input_tokens":120,"output_tokens":80,"final_content":"Full answer text"}
Lies Text ab dem content. Schlüssel von Frames, die keine "done" haben. Ein Fehler beendet den Stream mit {"type":"error","content":"...","done":"true"}.
Öffentlicher Aufruf-Endpunkt
Dies ist der Endpunkt, um einen Agenten aus Ihrer eigenen Anwendung mit einem API-Schlüssel aufzurufen.
POST https://<api-host>/api/v1/hydra-platform/v1/agents/{agent_id}/invoke
curl -X POST "https://<api-host>/api/v1/hydra-platform/v1/agents/<agent_id>/invoke" \
-H "Authorization: Bearer <api-token>" \
-H "Content-Type: application/json" \
-d '{"message": "Summarize this note: ...", "variables": {"specialty": "cardiology"}, "stream": false}'
Der Nachrichtentext entspricht dem Chat: message (oder attachments), stream, variables, history. Die Antwort ist die oben beschriebene Chat-Antwort oder der Ereignisstrom, falls stream gleich true ist. Der Agent muss der Organisation des Tokens angehören und aktiv sein.
Das Token benötigt den Gültigkeitsbereich agent:<agent_id>:execute. Die organisationsweiten Bereiche agents:execute oder agents:* sowie die agentenspezifischen Bereiche agent:<agent_id>:* und * erfüllen diese Anforderung ebenfalls. Die Workflow-Engine prüft das Token selbst; das Gateway leitet den Pfad weiter.
| Status | Körper | Ursache |
|---|---|---|
| 400 | message or attachments required | Leerer Körper |
| 401 | Authorization header required / Invalid authorization header format | Fehlender oder fehlerhafter Header |
| 403 | Forbidden | Token ungültig, widerrufen, abgelaufen, falscher Gültigkeitsbereich oder nicht zulässige IP-Adresse |
| 403 | Access denied / Agent is not active | Der Agent gehört einer anderen Organisation an oder ist inaktiv. |
| 404 | Agent not found | Unbekannte ID |
| 503 | Service temporarily unavailable | Der Authentifizierungsdienst konnte nicht erreicht werden. |
Diese Datenkörper sind Klartext, kein JSON. Ein widerrufener Schlüssel liefert 403, nicht 401.
Knotenkatalog
Öffentlich, kein Token erforderlich. Verwenden Sie es, um gültige Werte für Knoten type, Ports und Konfigurationsfelder zu ermitteln, bevor Sie eine Pipeline erstellen.
| Methode und Pfad | Zweck |
|---|---|
GET /node-catalog | Alle Knoten. Optionaler category Filter. Gibt nodes, categories oder total_count zurück. |
GET /node-catalog/search/{query} | Groß-/Kleinschreibung wird bei der Suche nach ID, Name, Beschreibung oder Kategorie nicht beachtet. Rückgabewert: query, results, count |
GET /node-catalog/{id} | Ein Knoten: id, name, category, description, inputs, outputs, config, compliance und, wobei Menge, maturity, risk_tier |
curl "https://<api-host>/api/v1/hydra-platform/node-catalog/input"
Die Knotenseiten dieser Website enthalten dieselben Daten. Für eine ID, die nicht in der Registry vorhanden ist, wird GET /node-catalog/{id} ein abgeleiteter Eintrag anstelle des Statuscodes 404 zurückgegeben. Eine erfolgreiche Antwort beweist also nicht die Existenz des Knotens. Mit POST /pipelines werden unbekannte Typen abgelehnt.
Konnektoren, Werkzeuge und LLM-Modelle
Alle benötigen ein Benutzer-JWT.
Steckverbinder
| Methode und Pfad | Zweck |
|---|---|
GET /connectors/types | Die Steckertypen und ob für jeden ein Treiber vorhanden ist (Available) |
GET /connectors | Liste. Filter: connector_type, is_template, scope, project_id, limit, offset |
POST /connectors | Erstellen, 201 |
GET, PUT, DELETE /connectors/{id} | Lesen, aktualisieren, löschen |
Body erstellen:
| Feld | Bedeutung |
|---|---|
name | Erforderlich |
connector_type | Erforderlich. Einer der Typen von GET /connectors/types, zum Beispiel hl7_fhir_r4, rest_api, postgres, s3, sftp oder kafka |
configuration | Objekt. Die erforderlichen Felder hängen vom Typ ab; der Endpunkt gehört hierher, nicht in ein Feld der obersten Ebene. |
credentials | Objekt mit Zeichenkettenwerten ({"token": "..."}). Wird separat von der Konfiguration gespeichert. |
scope | organization (Standard) oder project. project erfordert project_id |
description, tags, is_template, is_public, reason | Optional |
curl -X POST "https://<api-host>/api/v1/hydra-platform/connectors" \
-H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" \
-d '{"name": "Demo FHIR server", "connector_type": "hl7_fhir_r4",
"configuration": {"base_url": "https://fhir.example.org/fhir", "auth_type": "none"}}'
Für hl7_fhir_r4 ist nur base_url erforderlich; auth_type ist einer der Werte none, bearer, api_key, basic, client_credentials oder backend_jwt. Konfigurationen, die nicht mit dem Treiber übereinstimmen, geben 400 config validation failed: ... zurück. Siehe das Connector-Verzeichnis.
Werkzeuge
Die Werte GET /tools, POST /tools, GET, PUT, DELETE /tools/{id} und GET /tools/{id}/declarations existieren. Ich habe den Anfragetext des Tools nicht überprüft, daher ist er hier nicht dokumentiert.
LLM-Modelle
GET /llm-models listet die Modelle der Organisation auf (API-Schlüssel werden nie zurückgegeben; jedes Element hat has_api_key). Filter: provider, status, limit, offset. POST /llm-models akzeptiert name, provider, model_name und optional api_key, api_base_url, context_window, default_temperature, default_max_tokens, input_cost_per_1k, output_cost_per_1k und weitere. GET, PUT, DELETE /llm-models/{id}, POST /llm-models/{id}/set-default und POST /llm-models/{id}/test-connection existieren ebenfalls.
Kopilot
Alle Copilot-Routen benötigen ein Benutzer-JWT und sind standardmäßig POST sofern nicht anders angegeben.
| Weg | Zweck |
|---|---|
copilot/chat | Chat. message erforderlich; stream: true Stream. |
copilot/generate/pipeline, validate/pipeline, refine/pipeline, modify/pipeline, auto-configure/pipeline, configure/node, generate/pipeline-docs, generate/agent | Pipeline- und Agenten-Erstellungshilfen |
copilot/pipeline-assistant, agent-assistant, graph-assistant, board-assistant | Assistenten im Inneren der Bauarbeiter |
copilot/route-agent, copilot/compose-pipeline | Body {"task": "...", "catalog": "..."}, beide erforderlich. Gibt {"raw": "..."} zurück. |
GET copilot/capabilities, GET copilot/health | Fähigkeiten und Gesundheit |
Diese Routen beantworten 501 {"error":"not implemented","feature":"<name>", ...}: copilot/generate/code, generate/hl7-mapping, generate/fhir-queries, infer/schema und transformer-assistant. Die älteren Routen suggestions, analyze und insights existieren nicht mehr und liefern den Fehlercode 404 zurück.
Umgebungen, Manifeste und Bereitstellungen
Diese Routen dienen der Zusammenarbeit zwischen Umgebungen: GET, POST /environments, GET, PATCH /environments/{slug}, GET, PUT /environments/routes, POST /environments/{slug}/deployments, GET /environments/{slug}/releases, /manifests, /deployments/pending, POST /deployments/receive und GET /instance. Zum Lesen wird ein Benutzer-JWT benötigt; zum Erstellen, Ändern und Bereitstellen sind Superuser-Rechte oder die Berechtigung manage:hydra.environment erforderlich. Ausnahmen: manifests akzeptiert auch API-Token mit manifests:read, manifests:write oder manifests:publish, deployments/receive benötigt ein Token mit deployments:write, und GET /instance ist im Workflow-System öffentlich (über das Gateway wird weiterhin ein Bearer-Token gesendet). Diese Bereiche sind nicht in der Liste der API-Token enthalten. Daher kann über die Produkt-Benutzeroberfläche nur ein Token mit dem Bereich * erstellt werden, das diese Anforderungen erfüllt. Die Anfragetexte werden auf der Seite „Umgebungen“ beschrieben.
API-Tokens
Ein API-Token ermöglicht es einem Programm, die oben markierten Routen ohne Benutzersitzung aufzurufen.
Token erstellen
- Öffnen Sie die Admin-Konsole und gehen Sie zu Platform, dann zu API Tokens. Für diesen Bildschirm wird ein Organisationsadministrator benötigt.
- Wählen Sie Create Token und füllen Sie die Felder Name (erforderlich), Description, Scopes (erforderlich), Expires In (days) (1 bis 365; leer lassen für kein Ablaufdatum), Rate Limit (requests/minute) (0 bedeutet keine Begrenzung) und Allowed IPs (optional) (leer lassen erlaubt jede IP-Adresse) aus.
- Kopieren Sie das Token aus dem Dialogfeld Token Created Successfully Es wird nur einmal angezeigt und kann nicht erneut angezeigt werden; der Server speichert nur einen Hashwert.
Das Token beginnt mit tia_m2m_ Der Agentendesigner verfügt außerdem über einen Tab API mit der Generate API Key, der ein Token mit dem Gültigkeitsbereich agent:<id>:execute erstellt und vorgefertigte TypeScript- und Python-Beispiele curl anzeigt. Beachten Sie, dass die dort generierten Streaming-TypeScript- und Python-Beispiele chunk.type === "content" testen; der Server sendet den Text unter einer content Taste ohne type, wie oben gezeigt.
Die Bereichsprüfung im dev Zweig des Go-Authentifizierungsdienstes akzeptiert nur Berechtigungskatalogschlüssel, die in der folgenden Tabelle aufgeführten Bereiche sowie Spoke-Bereiche. Ich habe keine Regel gefunden, die einen ressourcenbezogenen Bereich wie agent:<id>:execute zulässt. Daher kann eine Anfrage von Generate API Key mit UNKNOWN_SCOPE (400) abgelehnt werden. Ich habe dies nicht mit einem produktiven Authentifizierungsdienst getestet. Falls die Anfrage abgelehnt wird, erstellen Sie auf der Seite „API-Tokens“ ein Token mit agents:execute und verwenden Sie dieses für den Aufruf-Endpunkt. Derselbe Zweig erfordert, dass ein Token eine Gültigkeitsdauer von 1 bis 90 Tagen hat, wenn es einen geschützten Berechtigungsschlüssel enthält. Nur ein angemeldeter Benutzer (kein anderes API-Token) kann ein Token erstellen.
Der Bildschirm ruft POST /api/v1/auth/api-tokens (mit einem Benutzer-JWT) mit name, description, scopes, expires_in_days, rate_limit und allowed_ips auf. Die Antwort enthält token, token_prefix, id, name und scopes.
Zielfernrohre
Der Geltungsbereich des Authentifizierungsdienstes:
| Gruppe | Zielfernrohre |
|---|---|
| Pipelines | pipelines:read, pipelines:write, pipelines:execute, pipelines:* |
| Hinrichtungen | executions:read, executions:write |
| Agenten | agents:read, agents:write, agents:execute, agents:* |
| Organisation und Nutzer | organization:read, organization:write, organization:*, users:read, users:write |
| Vorlagen | templates:read, templates:write |
| Graphen und Subagenten | graphs:read, graphs:write, graphs:execute, graphs:*, subagent:read, subagent:execute, subagent:* |
| Alles | * |
| Laufzeit (Speichen und Nabe) | spoke:register, spoke:heartbeat, spoke:config, spoke:messages, spoke:logs, spoke:bootstrap, spoke:*, hub:admin, hub:* |
Ressourcenbezogene Formen wie agent:<uuid>:execute und pipeline:<uuid>:execute werden ebenfalls berücksichtigt; die organisationsweite Gültigkeitsdauer desselben Typs (agents:execute, pipelines:*) erfüllt diese. Es gibt keine Gültigkeitsdauern fhir:read, fhir:write oder workflows:run.
Prüfen Sie, ob ein Token funktioniert
curl -X POST "https://<api-host>/api/v1/hydra-platform/execute" \
-H "Authorization: Bearer tia_m2m_..." -H "Content-Type: application/json" \
-d '{"pipeline_id": "<uuid>", "inputs": {}}'
Eine 200 oder 202 bedeutet, dass Token, Gültigkeitsbereich und Organisation korrekt sind.
Die Allowed IPs eines Tokens wird vom Authentifizierungsdienst anhand der erkannten Adresse überprüft. Das Gateway übermittelt Ihre Adresse bei der Tokenvalidierung, die Workflow-Engine validiert das Token jedoch erneut, ohne die Adresse des Aufrufers weiterzuleiten. Daher konnte ich das Verhalten eines eingeschränkten Tokens auf Workflow-Engine-Routen nicht bestätigen. Testen Sie ein eingeschränktes Token, bevor Sie es verwenden.
Fehlerbehebung
| Sie sehen | Ursache und Lösung |
|---|---|
401 {"detail":"Authentication required"} | Kein Authorization: Bearer Header auf einem nicht-öffentlichen Pfad |
401 {"detail":"Invalid or expired token"} | Das JWT oder API-Token ist ungültig. Widerrufene oder abgelaufene API-Tokens funktionieren hier nicht. |
401 {"error":"unauthorized: invalid token"} aus der Workflow-Engine | Sie haben ein API-Token an eine Route gesendet, die nur ein Benutzer-JWT akzeptiert (siehe Warnung oben). |
403 Forbidden bei Aufruf oder Ausführung | Das Token hat nicht den erforderlichen Gültigkeitsbereich, wurde widerrufen oder ist abgelaufen, oder die IP-Adresse des Aufrufers befindet sich nicht in der Liste der zulässigen Adressen. |
403 {"detail":"forbidden: not a member of the requested organization"} | X-Organization-ID nennt eine Organisation, der Sie nicht angehören. Entfernen Sie die Kopfzeile. |
404 {"error":"pipeline not found"} | Falsche ID, oder die Pipeline gehört zu einer anderen Organisation |
429 | Ratenbegrenzung. Warten Sie auf die Zurücksetzung (X-RateLimit-Reset vom Gateway, Retry-After von der Workflow-Engine). |
Der Synchronisierungsaufruf gibt 200 mit "status":"failed" zurück | Die Pipeline lief, aber ein Knoten ist ausgefallen. Lies error und node_results, behebe den Fehler und rufe dann POST /execute/retry auf. |
Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..