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
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.
| Environment | Base URL |
|---|
| Local (default) | http://127.0.0.1:8765 |
| Local (localhost) | http://localhost:8765 |
| Custom port | http://127.0.0.1:{port} |
Server Types
| Server | CLI Command | Default Port | Description |
|---|
| Unified | praisonai serve unified | 8765 | All providers in one server |
| Agents | praisonai serve agents | 8765 | Agent HTTP API |
| Recipe | praisonai serve recipe | 8765 | Recipe runner |
| MCP | praisonai serve mcp | 8080 | MCP protocol server |
| Tools | praisonai serve tools | 8081 | Tools as MCP server |
| A2A | praisonai serve a2a | 8082 | Agent-to-Agent protocol |
| A2U | praisonai serve a2u | 8083 | Agent-to-User events |
Discovery Endpoint
All servers expose a unified discovery endpoint:
curl http://127.0.0.1:8765/__praisonai__/discovery
{
"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__/discovery | Discovery document |
| GET | /health | Health check |
Agents API
| Method | Endpoint | Description |
|---|
| POST | /agents | Invoke agents workflow |
Recipe API
| Method | Endpoint | Description |
|---|
| GET | /v1/recipes | List recipes |
| GET | /v1/recipes/{name} | Describe recipe |
| POST | /v1/recipes/run | Run recipe (sync) |
| POST | /v1/recipes/stream | Run recipe (SSE) |
MCP API
| Method | Endpoint | Description |
|---|
| GET | /mcp/tools | List MCP tools |
| POST | /mcp/tools/call | Call MCP tool |
A2A API
| Method | Endpoint | Description |
|---|
| GET | /.well-known/agent.json | Agent card |
| POST | /a2a | Send A2A message |
A2U API
| Method | Endpoint | Description |
|---|
| GET | /a2u/info | A2U server info |
| POST | /a2u/subscribe | Subscribe to stream |
| GET | /a2u/events/{stream} | Stream events (SSE) |
| GET | /a2u/health | A2U health check |
Jobs API (Async)
| Method | Endpoint | Description |
|---|
| POST | /api/v1/runs | Submit job |
| GET | /api/v1/runs | List jobs |
| GET | /api/v1/runs/{id} | Get job status |
| GET | /api/v1/runs/{id}/result | Get job result |
| POST | /api/v1/runs/{id}/cancel | Cancel job |
| DELETE | /api/v1/runs/{id} | Delete job |
| GET | /api/v1/runs/{id}/stream | Stream job progress |
Authentication
Authentication is optional and configurable per server:
# Start with API key authentication
praisonai serve unified --api-key "your-secret-key"
curl -H "X-API-Key: your-secret-key" http://127.0.0.1:8765/health
Common Options
| Option | Default | Description |
|---|
--host | 127.0.0.1 | Server host |
--port | 8765 | Server port |
--reload | false | Enable hot reload |
--api-key | - | API key for auth |
--file | agents.yaml | Agents 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
