PraisonAI API Overview

Complete API reference for PraisonAI servers with interactive playground

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

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:

curl http://127.0.0.1:8765/agents \
  -H "Authorization: Bearer $PRAISONAI_API_TOKEN"

Override defaults with environment variables:

Variable	Default	Description
PRAISONAI_API_AUTH	enabled	Set to disabled to turn off authentication
PRAISONAI_API_TOKEN	auto-generated	Custom bearer token
PRAISONAI_API_HOST	127.0.0.1	Bind host (use 0.0.0.0 for external access)
PRAISONAI_API_PORT	8765	Port number

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

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	8000	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
OpenAI	praisonai serve openai	8765	OpenAI-compatible API

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

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"

Using API key: --api-key accepts either Authorization: Bearer or X-API-Key.

# 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/agents

The async Jobs API uses a separate key — see Jobs API Authentication.

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

Discovery API

Unified discovery endpoint

Agents API

Agent invocation endpoints

Recipe API

Recipe runner endpoints

A2U API

Event streaming endpoints