> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
```

<Warning>
  **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.
</Warning>

**Server running at:** `http://127.0.0.1:8765`

### Authentication

Use the bearer token printed at startup:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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                                   |

<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.
</Warning>

## 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.
</Note>

| 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl http://127.0.0.1:8765/__praisonai__/discovery
```

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start with API key authentication
praisonai serve unified --api-key "your-secret-key"
```

**Using API key:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<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>

<Warning>
  **CORS**: By default, CORS is not configured. Add `--cors-origins "*"` for development only.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Discovery API" icon="compass" href="/docs/deploy/api/discovery-api">
    Unified discovery endpoint
  </Card>

  <Card title="Agents API" icon="robot" href="/docs/deploy/api/agents-api">
    Agent invocation endpoints
  </Card>

  <Card title="Recipe API" icon="book" href="/docs/deploy/api/recipe-api">
    Recipe runner endpoints
  </Card>

  <Card title="A2U API" icon="stream" href="/docs/deploy/api/a2u-api">
    Event streaming endpoints
  </Card>
</CardGroup>