API Reference

The Hydra Platform exposes a REST API for managing pipelines, agents, executions, and the AI copilot programmatically. All endpoints are available at your organization's API base URL.

Base URL:

https://api.tiet.ai/api

Authentication: All API requests require a bearer token. Generate an API key under Settings → Security → API Keys (see Administration).

Authorization: Bearer <your-api-key>
X-Organization-ID: <your-org-id>

Public agent invocation endpoints under /api/v1/ also accept API keys with agent/{uuid}:execute scopes.

Pipelines

Pipelines are the core workflow unit in TietAI. Each pipeline contains a graph of connected nodes that process clinical data.

List pipelines

GET /api/pipelines?limit=20&offset=0

Returns all pipelines in your organization.

Parameter	Type	Description
`limit`	integer	Max results per page (default: 20)
`offset`	integer	Number of results to skip

Response:

{
  "pipelines": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Epic Patient Sync",
      "description": "Daily sync of patient data from Epic",
      "status": "deployed",
      "version": 3,
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-04-10T14:30:00Z"
    }
  ],
  "total_count": 42
}

Create pipeline

POST /api/pipelines
Content-Type: application/json

{
  "name": "My Pipeline",
  "description": "Processes lab results and alerts care team",
  "definition": {
    "nodes": [...],
    "connections": [...]
  }
}

Response: 201 Created with the full pipeline object including the generated id.

Get pipeline

GET /api/pipelines/{id}

Returns the full pipeline definition including nodes, connections, and metadata.

Update pipeline

PUT /api/pipelines/{id}
Content-Type: application/json

{
  "name": "Updated Pipeline Name",
  "description": "Updated description",
  "definition": {
    "nodes": [...],
    "connections": [...]
  }
}

Delete pipeline

DELETE /api/pipelines/{id}

Returns 204 No Content. Deployed pipelines must be undeployed first.

Deploy / Undeploy pipeline

POST /api/pipelines/{id}/deploy
POST /api/pipelines/{id}/undeploy

Deploy makes the pipeline available for execution and scheduling. Undeploy stops any active schedules and sets the status back to active.

Pipeline execution

Execute a pipeline

POST /api/execute
Content-Type: application/json

{
  "pipeline_id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": {
    "patient_id": "12345",
    "date_range": "2026-01-01/2026-04-01"
  },
  "async": true,
  "test_mode": false
}

Field	Type	Description
`pipeline_id`	string	UUID of the pipeline to execute
`inputs`	object	Input data passed to the pipeline's input node
`async`	boolean	If `true`, returns immediately with an `execution_id` to poll. If `false`, waits for completion (default: `false`)
`test_mode`	boolean	If `true`, runs without writing to external systems

Response (async):

{
  "execution_id": "exec-7890",
  "status": "running"
}

Response (sync):

{
  "execution_id": "exec-7890",
  "status": "completed",
  "outputs": { ... },
  "node_results": {
    "node-1": { "status": "completed", "duration_ms": 1200 },
    "node-2": { "status": "completed", "duration_ms": 3400 }
  }
}

List executions

GET /api/executions?limit=20&offset=0

Returns execution history with status, timing, and error details.

Get execution details

GET /api/executions/{id}

Returns the full execution result including per-node inputs, outputs, timing, and logs.

Retry from failed node

POST /api/execute/retry
Content-Type: application/json

{
  "execution_id": "exec-7890",
  "node_id": "node-3",
  "inputs": { ... }
}

Re-runs the pipeline starting from the specified node, using outputs from previous successful nodes.

Step-by-step execution

For debugging, you can execute a pipeline one node at a time:

POST /api/execute/step
Content-Type: application/json

{
  "pipeline_id": "550e8400-e29b-41d4-a716-446655440000",
  "inputs": { ... }
}

Response:

{
  "session_id": "step-session-123",
  "current_node": "node-1",
  "status": "waiting"
}

Then advance to the next node:

POST /api/execute/step/{sessionId}
Content-Type: application/json

{
  "node_outputs": { ... }
}

Execution statistics

GET /api/stats

Returns aggregated execution metrics: success rate, average duration, error distribution by node type.

Agents

AI agents are configurable LLM-powered processors that can reason, use tools, and maintain conversation state.

List agents

GET /api/agents?limit=20&offset=0

Parameter	Type	Description
`limit`	integer	Max results per page
`offset`	integer	Number of results to skip
`base_templates`	boolean	If `true`, returns only base templates (catalog mode)
`type`	string	Filter by agent type
`is_active`	boolean	Filter by active status
`project_id`	string	Filter by project

Response:

{
  "agents": [
    {
      "id": "agent-uuid-123",
      "name": "Clinical Summarizer",
      "agent_type": "summarizer",
      "description": "Summarizes patient clinical history",
      "status": "active",
      "model_config": {
        "model": "claude-sonnet-4-5-20250514",
        "temperature": 0.3,
        "max_tokens": 4096
      }
    }
  ],
  "total_count": 15
}

Create agent

POST /api/agents
Content-Type: application/json

{
  "name": "Lab Result Interpreter",
  "agent_type": "clinical",
  "description": "Interprets lab results and flags abnormalities",
  "model_config": {
    "model": "claude-sonnet-4-5-20250514",
    "temperature": 0.2,
    "max_tokens": 2048
  },
  "prompt_template": "You are a clinical lab result interpreter. Given the following lab results, identify any abnormal values and provide a clinical interpretation.\n\n{{input}}",
  "tools": ["fhir-query", "drug-interaction-check"]
}

Get / Update / Delete agent

GET    /api/agents/{id}
PUT    /api/agents/{id}
DELETE /api/agents/{id}

Deploy / Undeploy agent

POST /api/agents/{id}/deploy
POST /api/agents/{id}/undeploy

Deployed agents are available for execution via pipelines and the public API.

Chat with agent

POST /api/agents/{id}/chat
Content-Type: application/json

{
  "message": "Summarize the latest lab results for patient 12345",
  "stream": true
}

When stream: true, the response is sent as Server-Sent Events (SSE) with real-time thinking/reasoning steps:

event: thinking
data: {"content": "Looking up patient 12345..."}

event: tool_call
data: {"tool": "fhir-query", "params": {"resource": "Observation", "patient": "12345"}}

event: tool_result
data: {"result": [...]}

event: message
data: {"content": "Based on the lab results from April 10..."}

event: done
data: {}

When stream: false, returns a complete response:

{
  "response": "Based on the lab results from April 10...",
  "reasoning_steps": [
    {"type": "thinking", "content": "Looking up patient 12345..."},
    {"type": "tool_call", "tool": "fhir-query", "result": [...]}
  ]
}

Public agent invocation

For external integrations, invoke an agent via the public API:

POST /api/v1/agents/{id}/invoke
Authorization: Bearer <api-key-with-agent-scope>
Content-Type: application/json

{
  "input_data": {
    "patient_id": "12345",
    "query": "What medications is this patient taking?"
  }
}

Requires an API key with agent/{uuid}:execute scope.

Agent conversations

Agents maintain conversation history for multi-turn interactions:

GET  /api/agents/{id}/conversations                    — List conversations
POST /api/agents/{id}/conversations                    — Create conversation
GET  /api/agents/{id}/conversations/{cid}              — Get conversation
GET  /api/agents/{id}/conversations/{cid}/messages     — List messages
POST /api/agents/{id}/conversations/{cid}/messages     — Send message
DELETE /api/agents/{id}/conversations/{cid}             — Delete conversation

Agent tools

Manage which tools an agent can use:

GET    /api/agents/{id}/tools              — List assigned tools
POST   /api/agents/{id}/tools              — Assign tool
DELETE /api/agents/{id}/tools/{toolId}     — Remove tool

Agent versions

GET  /api/agents/{id}/versions     — List versions
POST /api/agents/{id}/versions     — Create version snapshot

Copilot

The Hydra Copilot is an AI assistant that helps design, validate, and optimize pipelines and agents.

Chat with Copilot

POST /api/copilot/chat
Content-Type: application/json

{
  "message": "Create a pipeline that syncs patients from Epic, validates the data, and writes to our FHIR server",
  "stream": true,
  "context": {
    "pipeline_id": "optional-existing-pipeline-id"
  }
}

Response (streamed): SSE events with reasoning steps and the generated/modified pipeline definition.

Generate pipeline from description

POST /api/copilot/generate/pipeline
Content-Type: application/json

{
  "description": "Fetch all patients with diabetes from Epic, run a risk score model, and alert the care team for high-risk patients"
}

Response:

{
  "pipeline": {
    "name": "Diabetes Risk Alert Pipeline",
    "nodes": [...],
    "connections": [...]
  }
}

Validate pipeline

POST /api/copilot/validate/pipeline
Content-Type: application/json

{
  "definition": {
    "nodes": [...],
    "connections": [...]
  }
}

Response:

{
  "valid": false,
  "errors": [
    {"node_id": "node-3", "message": "Output type 'text' is not compatible with input type 'fhir-bundle'"}
  ],
  "warnings": [
    {"node_id": "node-1", "message": "No error handler configured for this node"}
  ]
}

Generate agent from description

POST /api/copilot/generate/agent
Content-Type: application/json

{
  "description": "An agent that reviews discharge summaries and extracts ICD-10 codes"
}

Generate FHIR queries

POST /api/copilot/generate/fhir-queries
Content-Type: application/json

{
  "description": "Find all patients over 65 with a hemoglobin A1c above 7% in the last 6 months"
}

Response:

{
  "queries": [
    "GET /Patient?birthdate=le1961-04-16",
    "GET /Observation?code=4548-4&value-quantity=gt7&date=ge2025-10-16"
  ]
}

Additional Copilot endpoints

Endpoint	Method	Description
`/api/copilot/suggestions`	POST	Get improvement suggestions for a pipeline
`/api/copilot/suggestions/{id}/apply`	POST	Apply a suggested change
`/api/copilot/analyze`	POST	Analyze a pipeline or agent for issues
`/api/copilot/insights/{agentId}`	GET	Get usage patterns and recommendations for an agent
`/api/copilot/refine/pipeline`	POST	Optimize an existing pipeline
`/api/copilot/modify/pipeline`	POST	Modify a pipeline with a natural language request
`/api/copilot/auto-configure/pipeline`	POST	Auto-configure unconfigured nodes
`/api/copilot/configure/node`	POST	Generate configuration for a specific node type
`/api/copilot/generate/code`	POST	Generate code snippets for custom nodes
`/api/copilot/generate/hl7-mapping`	POST	Generate HL7 field mapping rules
`/api/copilot/generate/pipeline-docs`	POST	Auto-generate pipeline documentation
`/api/copilot/infer/schema`	POST	Infer JSON schema from sample data
`/api/copilot/health`	GET	Copilot service health check

Node catalog

Query the available processing nodes that can be used in pipelines.

List all nodes

GET /api/node-catalog

Parameter	Type	Description
`category`	string	Filter by category: `healthcare`, `ai`, `data`, `output`, `control`, `claims`

Response:

{
  "nodes": [
    {
      "id": "epic-fhir",
      "name": "Epic FHIR",
      "category": "healthcare",
      "description": "Fetches patient data from Epic via FHIR R4",
      "inputs": [{"name": "trigger", "type": "trigger-event"}],
      "outputs": [{"name": "bundle", "type": "fhir-bundle"}],
      "config_schema": { ... }
    }
  ],
  "categories": ["healthcare", "ai", "data", "output", "control", "claims"],
  "total_count": 128
}

Search nodes

GET /api/node-catalog/search/{query}

Search nodes by name, description, or keywords. Example: /api/node-catalog/search/fhir

Get node details

GET /api/node-catalog/{nodeId}

Returns the full node schema including all configuration fields, input/output port definitions, and documentation.

Tools

Tools are capabilities that can be assigned to agents — FHIR queries, drug interaction checks, code lookups, etc.

GET    /api/tools              — List available tools
POST   /api/tools              — Create custom tool
GET    /api/tools/{id}         — Get tool details and schema
PUT    /api/tools/{id}         — Update tool
DELETE /api/tools/{id}         — Delete tool

Connectors

Connectors are configured links to external systems (EHRs, FHIR servers, etc.).

GET    /api/connectors              — List configured connectors
POST   /api/connectors              — Create connector
GET    /api/connectors/{id}         — Get connector details
PUT    /api/connectors/{id}         — Update connector
DELETE /api/connectors/{id}         — Delete connector
GET    /api/connectors/types        — List supported connector types

Create connector example:

{
  "name": "Epic Production",
  "type": "epic-fhir",
  "endpoint": "https://epic.hospital.org/fhir/r4",
  "credentials": {
    "client_id": "...",
    "client_secret": "..."
  }
}

LLM models

GET /api/llm-models

Returns the list of available language models for agent configuration. Each model includes its capabilities, context window size, and pricing tier.

Error responses

All error responses follow a consistent format:

{
  "error": {
    "code": "PIPELINE_NOT_FOUND",
    "message": "Pipeline with ID 550e8400-... was not found",
    "status": 404
  }
}

HTTP Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid authentication token
`403`	Insufficient permissions for this operation
`404`	Resource not found
`409`	Conflict (e.g., deleting a deployed pipeline)
`429`	Rate limit exceeded
`500`	Internal server error

Rate limits

Scope	Limit
API requests (per org)	1000 requests/minute
Pipeline executions (per org)	100 concurrent
Agent chat (per user)	60 requests/minute
Copilot requests (per user)	30 requests/minute
Bulk Data exports (per org)	5 concurrent

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1713292800

Pipelines​

List pipelines​

Create pipeline​

Get pipeline​

Update pipeline​

Delete pipeline​

Deploy / Undeploy pipeline​

Pipeline execution​

Execute a pipeline​

List executions​

Get execution details​

Retry from failed node​

Step-by-step execution​

Execution statistics​

Agents​

List agents​

Create agent​

Get / Update / Delete agent​

Deploy / Undeploy agent​

Chat with agent​

Public agent invocation​

Agent conversations​

Agent tools​

Agent versions​

Copilot​

Chat with Copilot​

Generate pipeline from description​

Validate pipeline​

Generate agent from description​

Generate FHIR queries​

Additional Copilot endpoints​

Node catalog​

List all nodes​

Search nodes​

Get node details​

Tools​

Connectors​

LLM models​

Error responses​

Rate limits​

Pipelines

List pipelines

Create pipeline

Get pipeline

Update pipeline

Delete pipeline

Deploy / Undeploy pipeline

Pipeline execution

Execute a pipeline

List executions

Get execution details

Retry from failed node

Step-by-step execution

Execution statistics

Agents

List agents

Create agent

Get / Update / Delete agent

Deploy / Undeploy agent

Chat with agent

Public agent invocation

Agent conversations

Agent tools

Agent versions

Copilot

Chat with Copilot

Generate pipeline from description

Validate pipeline

Generate agent from description

Generate FHIR queries

Additional Copilot endpoints

Node catalog

List all nodes

Search nodes

Get node details

Tools

Connectors

LLM models

Error responses

Rate limits