Zum Hauptinhalt springen

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.

So durchläuft eine Anfrage das Gateway: Prüfung des öffentlichen Pfads, Token-Verifizierung, Organisations-, IP- und Ratenbegrenzungsprüfungen, dann der Dienst

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:

TokenWie das Gateway es erkenntWo man es bekommt
Benutzer JWTEnthält PunkteAnmeldung beim Produkt
API-TokenKeine 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.

API-Token funktionieren nur auf bestimmten Workflow-Engine-Routen.

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
healthGesundheitscheck
node-catalog und alles darunterMetadaten 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_minute ersetzt den Wert „600“ (die Admin-Konsole hat kein Feld für diese Zahl). Bei Überschreitung des Limits werden 429 mit {"detail":"Rate limit exceeded"} und den Headern X-RateLimit-Limit, X-RateLimit-Remaining (0) und X-RateLimit-Reset gesendet. 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 429 mit einem Retry-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.

QuelleFormatBeispiel
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-Handlerreiner Textkörperagent 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:

EndpunktParameterStandardAntwortschlüssel
GET /pipelinespage, page_size oder limit, offset (expliziter limit / offset -Sieg)Seite 1, Größe 10pipelines, total, page, page_size
GET /executionslimit, offset10, 0entries, total, limit, offset, organization_id
GET /agents, GET /connectorslimit, offset20, 0agents oder connectors, total_count, limit, offset
GET /llm-modelslimit, offset20, 0items, 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 PfadZweckErfolg
GET /pipelinesListen Sie die Pipelines Ihrer Organisation auf200
POST /pipelinesErstellen Sie eine Pipeline201
GET /pipelines/{id}Holen Sie sich eine Pipeline200
PUT /pipelines/{id}Teilaktualisierung200
DELETE /pipelines/{id}Löschen204
POST /pipelines/{id}/deployIn einer Umgebung bereitstellen200
POST /pipelines/{id}/undeploySetzen Sie den Status wieder auf active200
GET /pipelines/{id}/executionsAusführungen dieser Pipeline200
GET /pipelines/{id}/historyWer 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": {}
}'
FeldBedeutungStandard
nameErforderlich
descriptionFreitextleer
versionSemver-Zeichenkette1.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
variablesEntweder 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:

StatusKörperUrsache
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.

Abfolge der drei Ausführungsergebnisse: synchrones Ergebnis, ein wartender Lauf, der fortgesetzt wird, und ein asynchroner Lauf, der abgefragt wird

FeldBedeutungStandard
pipeline_idErforderlich
inputsObjekt mit Eingabewerten. input wird als Alias akzeptiert. Eine explizite null gibt 400 input is required zurück.{}
asynctrue gibt sofort einen Wert zurück und läuft im Hintergrund.false (läuft inline)
environmentUmgebungs-Slug. Der Header X-Hydra-Environment wird verwendet, wenn dieser leer ist, andernfalls der Standardwert der Organisation.Standardumgebung
test_modetrue 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 PfadZweck
GET /executionsVerlauf. 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}/cancelAsynchronen Lauf abbrechen
POST /execute/retryErneuter Start von einem ausgefallenen Knoten
GET /statsAggregate 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 PfadZweck
POST /execute/stepSitzung starten. Körper {"pipeline_id": "...", "inputs": {}}
POST /execute/step/{sessionId}/nextFü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 PfadZweck
GET /agentsListen Sie die Vertreter Ihrer Organisation auf.
GET /agents?base_templates=trueAgentenliste (Basisvorlage)
POST /agentsAgenten erstellen, 201
GET /agents/{id}, PUT /agents/{id}, DELETE /agents/{id}Lesen, aktualisieren, löschen
POST /agents/{id}/deploy, POST /agents/{id}/undeployBereitstellen oder entfernen
POST /agents/{id}/instantiateErstellen Sie Ihren eigenen Agenten anhand einer Basisvorlage. Textkörper {"project_id": "...", "name": "..."} (project_id erforderlich)
POST /agents/{id}/chatFühren Sie den Agenten aus (siehe unten).
GET, POST /agents/{id}/conversationsKonversationen. Auch /conversations/{cid}, /messages, /steps
GET /agents/{id}/executionsLaufverlauf. Auch /executions/{execId}/steps und /events
GET /agents/{id}/versionsVersionslebenszyklus (/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
}'
FeldBedeutungStandard
nameErforderlich
agent_typeconversational, task, hybrid oder reactconversational
prompt_templateSystemaufforderung. {{KEY}} Token werden zur Laufzeit von variables aufgefüllt.
slugKleinbuchstaben, Ziffern und Bindestriche
temperatureGanze Zahl von 0 bis 100
compliance_levelhipaa, fda, soc2, gdpr oder none
Anderemodel_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:

FeldBedeutung
messageErforderlich, es sei denn, es wird attachments gesendet
streamtrue für serverseitig gesendete Ereignisse
historyFrühere Runden als {role, content}
variablesEin Objekt von Zeichenketten, die {{KEY}} in der Eingabeaufforderung ausfüllen.
thinking, attachments, response_language, groundingOptional

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.

StatusKörperUrsache
400message or attachments requiredLeerer Körper
401Authorization header required / Invalid authorization header formatFehlender oder fehlerhafter Header
403ForbiddenToken ungültig, widerrufen, abgelaufen, falscher Gültigkeitsbereich oder nicht zulässige IP-Adresse
403Access denied / Agent is not activeDer Agent gehört einer anderen Organisation an oder ist inaktiv.
404Agent not foundUnbekannte ID
503Service temporarily unavailableDer 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 PfadZweck
GET /node-catalogAlle 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 PfadZweck
GET /connectors/typesDie Steckertypen und ob für jeden ein Treiber vorhanden ist (Available)
GET /connectorsListe. Filter: connector_type, is_template, scope, project_id, limit, offset
POST /connectorsErstellen, 201
GET, PUT, DELETE /connectors/{id}Lesen, aktualisieren, löschen

Body erstellen:

FeldBedeutung
nameErforderlich
connector_typeErforderlich. Einer der Typen von GET /connectors/types, zum Beispiel hl7_fhir_r4, rest_api, postgres, s3, sftp oder kafka
configurationObjekt. Die erforderlichen Felder hängen vom Typ ab; der Endpunkt gehört hierher, nicht in ein Feld der obersten Ebene.
credentialsObjekt mit Zeichenkettenwerten ({"token": "..."}). Wird separat von der Konfiguration gespeichert.
scopeorganization (Standard) oder project. project erfordert project_id
description, tags, is_template, is_public, reasonOptional
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.

WegZweck
copilot/chatChat. message erforderlich; stream: true Stream.
copilot/generate/pipeline, validate/pipeline, refine/pipeline, modify/pipeline, auto-configure/pipeline, configure/node, generate/pipeline-docs, generate/agentPipeline- und Agenten-Erstellungshilfen
copilot/pipeline-assistant, agent-assistant, graph-assistant, board-assistantAssistenten im Inneren der Bauarbeiter
copilot/route-agent, copilot/compose-pipelineBody {"task": "...", "catalog": "..."}, beide erforderlich. Gibt {"raw": "..."} zurück.
GET copilot/capabilities, GET copilot/healthFähigkeiten und Gesundheit
Nicht implementiert

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​

  1. Öffnen Sie die Admin-Konsole und gehen Sie zu Platform, dann zu API Tokens. Für diesen Bildschirm wird ein Organisationsadministrator benötigt.
  2. 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.
  3. 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.

Agentenspezifische Bereiche im Entwicklerauthentifizierungsdienst

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:

GruppeZielfernrohre
Pipelinespipelines:read, pipelines:write, pipelines:execute, pipelines:*
Hinrichtungenexecutions:read, executions:write
Agentenagents:read, agents:write, agents:execute, agents:*
Organisation und Nutzerorganization:read, organization:write, organization:*, users:read, users:write
Vorlagentemplates:read, templates:write
Graphen und Subagentengraphs: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.

Zulässige IPs

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 sehenUrsache 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-EngineSie haben ein API-Token an eine Route gesendet, die nur ein Benutzer-JWT akzeptiert (siehe Warnung oben).
403 Forbidden bei Aufruf oder AusführungDas 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
429Ratenbegrenzung. 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ückDie 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..