API Reference¶
Hayhooks provides a comprehensive REST API for managing and executing Haystack pipelines and agents.
Base URL¶
http://localhost:1416
Authentication¶
Currently, Hayhooks does not include built-in authentication. Consider implementing:
- Reverse proxy authentication
- Network-level security
- Custom middleware
Endpoints¶
Pipeline Management¶
Deploy Pipeline (files)¶
POST /deploy_files
Request Body:
{
"name": "pipeline_name",
"files": {
"pipeline_wrapper.py": "...file content...",
"other.py": "..."
},
"save_files": true,
"overwrite": false
}
Response:
{
"status": "success",
"message": "Pipeline deployed successfully"
}
Deploy YAML Pipeline¶
POST /deploy-yaml
Deploy a pipeline from a Haystack YAML definition.
Request Body:
{
"name": "pipeline_name",
"source_code": "components:\n llm:\n type: ...",
"description": "Optional description",
"overwrite": false,
"skip_mcp": false,
"save_file": true
}
Response:
{
"name": "pipeline_name",
"success": true,
"endpoint": "/pipeline_name/run"
}
Automatic Output Handling
When deploying YAML pipelines, Hayhooks automatically configures the pipeline to return outputs from all components referenced in the outputs section, including intermediate components (e.g., retrievers).
This is done by extracting component names from the outputs mapping and passing them to Haystack's include_outputs_from parameter.
For more details, see YAML Pipeline Deployment.
Undeploy Pipeline¶
POST /undeploy/{pipeline_name}
Remove a deployed pipeline.
Response:
{
"status": "success",
"message": "Pipeline undeployed successfully"
}
Get Pipeline Status¶
GET /status/{pipeline_name}
Check the status of a specific pipeline.
Response:
{
"status": "Up!",
"pipeline": "pipeline_name"
}
Get All Pipeline Statuses¶
GET /status
Get status of all deployed pipelines.
Response:
{
"pipelines": [
"pipeline1",
"pipeline2"
],
"status": "Up!"
}
Pipeline Execution¶
Run Pipeline¶
POST /{pipeline_name}/run
Execute a deployed pipeline.
Request Body:
{
"query": "What is the capital of France?"
}
Response:
{
"result": "The capital of France is Paris."
}
OpenAI Compatibility¶
Chat Completion¶
POST /chat/completions
POST /v1/chat/completions
OpenAI-compatible chat completion endpoint.
Request Body:
{
"model": "pipeline_name",
"messages": [
{
"role": "user",
"content": "Hello, how are you?"
}
],
"stream": false
}
Response:
{
"id": "chat-123",
"object": "chat.completion",
"created": 1677652288,
"model": "pipeline_name",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! I'm doing well, thank you for asking."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 20,
"total_tokens": 32
}
}
Streaming Chat Completion¶
Use the same endpoints with "stream": true. Hayhooks streams chunks in OpenAI-compatible format.
MCP Server¶
MCP runs in a separate Starlette app when invoked via
hayhooks mcp run. Use the configured Streamable HTTP endpoint/mcpor SSE/ssedepending on your client. See the MCP feature page for details.
Interactive API Documentation¶
Hayhooks provides interactive API documentation for exploring and testing endpoints:
- Swagger UI:
http://localhost:1416/docs- Interactive API explorer with built-in request testing - ReDoc:
http://localhost:1416/redoc- Clean, responsive API documentation
OpenAPI Schema¶
Get OpenAPI Schema¶
GET /openapi.json
GET /openapi.yaml
Get the complete OpenAPI specification for programmatic access or tooling integration.
Error Handling¶
Error Response Format¶
{
"error": {
"message": "Error description",
"type": "invalid_request_error",
"code": 400
}
}
Common Error Codes¶
- 400 Bad Request: Invalid request parameters
- 404 Not Found: Pipeline or endpoint not found
- 500 Internal Server Error: Server-side error
Rate Limiting¶
Currently, Hayhooks does not include built-in rate limiting. Consider implementing:
- Reverse proxy rate limiting
- Custom middleware
- Request throttling
Examples¶
Running a Pipeline¶
curl -X POST http://localhost:1416/chat_pipeline/run \
-H 'Content-Type: application/json' \
-d '{"query": "Hello!"}'
import requests
response = requests.post(
"http://localhost:1416/chat_pipeline/run",
json={"query": "Hello!"}
)
print(response.json())
hayhooks pipeline run chat_pipeline --param 'query="Hello!"'
OpenAI-Compatible Chat Completion¶
curl -X POST http://localhost:1416/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "chat_pipeline",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
import requests
response = requests.post(
"http://localhost:1416/v1/chat/completions",
json={
"model": "chat_pipeline",
"messages": [
{"role": "user", "content": "Hello!"}
]
}
)
print(response.json())
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:1416/v1",
api_key="not-needed" # Hayhooks doesn't require auth by default
)
response = client.chat.completions.create(
model="chat_pipeline",
messages=[
{"role": "user", "content": "Hello!"}
]
)
print(response.choices[0].message.content)
Next Steps¶
- Environment Variables - Configuration options
- Logging - Logging configuration