Skip to main content

​
PraisonAI API

PraisonAI provides a unified HTTP API for all server capabilities. Start a local server and test endpoints directly in this documentation.

​
Quick Start

# Install with serve dependencies
pip install "praisonai[serve]"

# Set your API key
export OPENAI_API_KEY="your-key"

# Start the unified server
praisonai serve unified --host 127.0.0.1 --port 8765
Server running at: http://127.0.0.1:8765

​
Base URL

All examples use http://127.0.0.1:8765 as the base URL. Change the port if you started the server on a different port.
EnvironmentBase URL
Local (default)http://127.0.0.1:8765
Local (localhost)http://localhost:8765
Custom porthttp://127.0.0.1:{port}

​
Server Types

ServerCLI CommandDefault PortDescription
Unifiedpraisonai serve unified8765All providers in one server
Agentspraisonai serve agents8765Agent HTTP API
Recipepraisonai serve recipe8765Recipe runner
MCPpraisonai serve mcp8080MCP protocol server
Toolspraisonai serve tools8081Tools as MCP server
A2Apraisonai serve a2a8082Agent-to-Agent protocol
A2Upraisonai serve a2u8083Agent-to-User events

​
Discovery Endpoint

All servers expose a unified discovery endpoint: 
curl http://127.0.0.1:8765/__praisonai__/discovery
Response: 
{
  "schema_version": "1.0.0",
  "server_name": "praisonai-unified",
  "providers": [
    {"type": "agents-api", "name": "Agents API"},
    {"type": "recipe", "name": "Recipe Runner"},
    {"type": "mcp", "name": "MCP Server"},
    {"type": "a2a", "name": "A2A Protocol"},
    {"type": "a2u", "name": "A2U Event Stream"}
  ]
}

​
API Endpoints Summary

​
Core Endpoints

MethodEndpointDescription
GET/__praisonai__/discoveryDiscovery document
GET/healthHealth check

​
Agents API

MethodEndpointDescription
POST/agentsInvoke agents workflow

​
Recipe API

MethodEndpointDescription
GET/v1/recipesList recipes
GET/v1/recipes/{name}Describe recipe
POST/v1/recipes/runRun recipe (sync)
POST/v1/recipes/streamRun recipe (SSE)

​
MCP API

MethodEndpointDescription
GET/mcp/toolsList MCP tools
POST/mcp/tools/callCall MCP tool

​
A2A API

MethodEndpointDescription
GET/.well-known/agent.jsonAgent card
POST/a2aSend A2A message

​
A2U API

MethodEndpointDescription
GET/a2u/infoA2U server info
POST/a2u/subscribeSubscribe to stream
GET/a2u/events/{stream}Stream events (SSE)
GET/a2u/healthA2U health check

​
Jobs API (Async)

MethodEndpointDescription
POST/api/v1/runsSubmit job
GET/api/v1/runsList jobs
GET/api/v1/runs/{id}Get job status
GET/api/v1/runs/{id}/resultGet job result
POST/api/v1/runs/{id}/cancelCancel job
DELETE/api/v1/runs/{id}Delete job
GET/api/v1/runs/{id}/streamStream job progress

​
Authentication

Authentication is optional and configurable per server: 
# Start with API key authentication
praisonai serve unified --api-key "your-secret-key"
Using API key: 
curl -H "X-API-Key: your-secret-key" http://127.0.0.1:8765/health

​
Common Options

OptionDefaultDescription
--host127.0.0.1Server host
--port8765Server port
--reloadfalseEnable hot reload
--api-key-API key for auth
--fileagents.yamlAgents config file

​
Safety Notes

Binding to 0.0.0.0: Only bind to 0.0.0.0 if you need external access. For local development, use 127.0.0.1.
CORS: By default, CORS is not configured. Add --cors-origins "*" for development only.

​
Next Steps

Discovery API

Unified discovery endpoint

Agents API

Agent invocation endpoints

Recipe API

Recipe runner endpoints

A2U API

Event streaming endpoints