Recipe API

HTTP API endpoints for recipe runner server

GET /v1/recipes

Recipe API

cURL

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": {}
}
'

import requests

url = "http://127.0.0.1:8765/v1/recipes"

payload = {
    "recipe": "<string>",
    "input": {}
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({recipe: '<string>', input: {}})
};

fetch('http://127.0.0.1:8765/v1/recipes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/v1/recipes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'recipe' => '<string>',
    'input' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:8765/v1/recipes"

	payload := strings.NewReader("{\n  \"recipe\": \"<string>\",\n  \"input\": {}\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("http://127.0.0.1:8765/v1/recipes")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"recipe\": \"<string>\",\n  \"input\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/v1/recipes")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"recipe\": \"<string>\",\n  \"input\": {}\n}"

response = http.request(request)
puts response.read_body

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

curl http://127.0.0.1:8765/v1/recipes

import requests

response = requests.get("http://127.0.0.1:8765/v1/recipes")
recipes = response.json()
for recipe in recipes["recipes"]:
    print(f"- {recipe['name']}: {recipe['description']}")

const response = await fetch("http://127.0.0.1:8765/v1/recipes");
const { recipes } = await response.json();
recipes.forEach(r => console.log(`- ${r.name}: ${r.description}`));

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

curl http://127.0.0.1:8765/v1/recipes/research

import requests

response = requests.get("http://127.0.0.1:8765/v1/recipes/research")
recipe = response.json()
print(recipe)

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

curl -X POST http://127.0.0.1:8765/v1/recipes/run \
  -H "Content-Type: application/json" \
  -d '{"recipe": "research", "input": {"topic": "AI agents"}}'

import requests

response = requests.post(
    "http://127.0.0.1:8765/v1/recipes/run",
    json={"recipe": "research", "input": {"topic": "AI agents"}}
)
result = response.json()
print(result["result"])

const response = await fetch("http://127.0.0.1:8765/v1/recipes/run", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({recipe: "research", input: {topic: "AI agents"}})
});
const result = await response.json();
console.log(result.result);

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

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"}}'

import requests

response = requests.post(
    "http://127.0.0.1:8765/v1/recipes/stream",
    json={"recipe": "research", "input": {"topic": "AI agents"}},
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())

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

Status	Description
200	Success
400	Invalid request or validation error
404	Recipe not found
429	Rate limit exceeded
500	Server 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

Related

• Recipe CLI - CLI for recipes
• Agents API - Agent endpoints