PraisonAI API Overview Complete API reference for PraisonAI servers with interactive playground
Next
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
bash # 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 8765Warning Security Note (PR #1597): PraisonAI API servers are now secure-by-default . Authentication is enabled and servers bind to 127.0.0.1 by default. If no token is provided, a random bearer token is generated and printed to stderr.
Server running at: http://127.0.0.1:8765
Authentication
Use the bearer token printed at startup:
bash curl http://127.0.0.1:8765/agents \
-H "Authorization: Bearer $PRAISONAI_API_TOKEN"Override defaults with environment variables:
Variable Default Description PRAISONAI_API_AUTHenabledSet to disabled to turn off authentication PRAISONAI_API_TOKENauto-generated Custom bearer token PRAISONAI_API_HOST127.0.0.1Bind host (use 0.0.0.0 for external access) PRAISONAI_API_PORT8765Port number
Warning Setting PRAISONAI_API_HOST=0.0.0.0 exposes the server on all interfaces. Always pair external binding with authentication or a fronting proxy.
Base URL
Note 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.
Environment Base URL Local (default) http://127.0.0.1:8765Local (localhost) http://localhost:8765Custom port http://127.0.0.1:{port}
Server Types
Server CLI Command Default Port Description Unified praisonai serve unified8765 All providers in one server Agents praisonai serve agents8000 Agent HTTP API Recipe praisonai serve recipe8765 Recipe runner MCP praisonai serve mcp8080 MCP protocol server Tools praisonai serve tools8081 Tools as MCP server A2A praisonai serve a2a8082 Agent-to-Agent protocol A2U praisonai serve a2u8083 Agent-to-User events OpenAI praisonai serve openai8765 OpenAI-compatible API
Discovery Endpoint
All servers expose a unified discovery endpoint:
bash curl http://127.0.0.1:8765/__praisonai__/discoveryResponse:
json {
"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
Method Endpoint Description GET /__praisonai__/discoveryDiscovery document GET /healthHealth check
Agents API
Method Endpoint Description POST /agentsInvoke agents workflow
Recipe API
Method Endpoint Description GET /v1/recipesList recipes GET /v1/recipes/{name}Describe recipe POST /v1/recipes/runRun recipe (sync) POST /v1/recipes/streamRun recipe (SSE)
MCP API
Method Endpoint Description GET /mcp/toolsList MCP tools POST /mcp/tools/callCall MCP tool
A2A API
Method Endpoint Description GET /.well-known/agent.jsonAgent card POST /a2aSend A2A message
A2U API
Method Endpoint Description 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)
Method Endpoint Description 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:
bash # Start with API key authentication
praisonai serve unified --api-key "your-secret-key"Warning serve unified and serve agents require --api-key (or PRAISONAI_SERVE_API_KEY) when binding to a non-localhost host — the tool-invocation routes are refused without one. The key is enforced by the shared _api_auth middleware on every route except /health.
Using API key: --api-key accepts either Authorization: Bearer or X-API-Key.
bash # Authorization header
curl -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8765/agents
# X-API-Key header
curl -H "X-API-Key: your-secret-key" http://127.0.0.1:8765/agentsThe async Jobs API uses a separate key — see Jobs API Authentication .
Common Options
Option Default Description --host127.0.0.1 Server host --port8765 Server port --reloadfalse Enable hot reload --api-key– API key. Required when --host is not localhost for serve unified / serve agents. Enforced on all routes except /health. --fileagents.yaml Agents config file
Safety Notes
Warning 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.
Warning CORS : By default, CORS is not configured. Add --cors-origins "*" for development only.
Next Steps