Skip to main content
GET
http://127.0.0.1:8765
/
v1
/
recipes
Recipe API
curl --request GET \
  --url http://127.0.0.1:8765/v1/recipes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "recipe": "<string>",
  "input": {}
}
'

​
Recipe API

The Recipe API provides endpoints for listing, describing, and executing recipes.

​
Overview

Recipes are reusable agent configurations that can be invoked via HTTP. The recipe server provides both synchronous and streaming execution modes.

​
When to Use

  • Reusable workflows: Execute pre-defined agent workflows
  • Streaming output: Get real-time progress via SSE
  • Batch processing: Run multiple recipes programmatically

​
Base URL + Playground

# Start recipe server
praisonai serve recipe --host 127.0.0.1 --port 8765
Base URL: http://127.0.0.1:8765

​
Endpoints

​
GET /v1/recipes

List all available recipes.
​
none
none
No parameters required.
curl http://127.0.0.1:8765/v1/recipes
Response: 
{
  "recipes": [
    {"name": "research", "description": "Deep research agent"},
    {"name": "code-review", "description": "Code review agent"}
  ]
}

​
GET /v1/recipes/

Get detailed information about a recipe.
​
name
string
required
Recipe name
curl http://127.0.0.1:8765/v1/recipes/research
Response: 
{
  "name": "research",
  "description": "Deep research agent",
  "schema": {
    "type": "object",
    "properties": {
      "topic": {"type": "string"}
    },
    "required": ["topic"]
  }
}

​
POST /v1/recipes/run

Execute a recipe synchronously.
​
recipe
string
required
Recipe name to execute
​
input
object
Input data for the recipe
curl -X POST http://127.0.0.1:8765/v1/recipes/run \
  -H "Content-Type: application/json" \
  -d '{"recipe": "research", "input": {"topic": "AI agents"}}'
Response: 
{
  "result": "Research findings on AI agents...",
  "duration_ms": 5432
}

​
POST /v1/recipes/stream

Execute a recipe with SSE streaming.
​
recipe
string
required
Recipe name to execute
​
input
object
Input data for the recipe
curl -X POST http://127.0.0.1:8765/v1/recipes/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"recipe": "research", "input": {"topic": "AI agents"}}'
SSE Events: 
event: progress
data: {"step": "Researching...", "percentage": 25}

event: progress
data: {"step": "Analyzing...", "percentage": 50}

event: result
data: {"result": "Research findings..."}

​
POST /v1/recipes/validate

Validate recipe input without executing.
​
recipe
string
required
Recipe name
​
input
object
required
Input data to validate
curl -X POST http://127.0.0.1:8765/v1/recipes/validate \
  -H "Content-Type: application/json" \
  -d '{"recipe": "research", "input": {"topic": "AI"}}'
Response: 
{
  "valid": true,
  "errors": []
}

​
Errors

StatusDescription
200Success
400Invalid request or validation error
404Recipe not found
429Rate limit exceeded
500Server error

​
CLI Equivalent

# List recipes
praisonai recipes list

# Run a recipe
praisonai recipes run research --input '{"topic": "AI"}'

# Describe a recipe
praisonai recipes describe research

​
Configuration

Recipe server configuration via serve.yaml: 
host: 127.0.0.1
port: 8765
auth: api-key
api_key: your-secret-key
recipes:
  - research
  - code-review
preload: true
rate_limit: 100

​
Notes

  • Streaming uses Server-Sent Events (SSE)
  • Rate limiting is configurable per server
  • Recipes are discovered from the template registry