Deploy API: Agents Server

HTTP API endpoints for agent servers

Two Different API Servers: This page documents the Agent.launch() HTTP server. For the auto-generated API server created by praisonai deploy run --type api, see API Server Authentication.

HTTP REST API endpoints for agents deployed via Agent.launch() or Agents.launch().

Base URL

http://localhost:{port}

Default port is 8000.

Endpoints

POST /

Send a query to the agent(s).

Request:

curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "What is AI?"}'

Request Body:

Field	Type	Required	Description
query	string	Yes	The message to send

Response:

{
  "response": "Artificial intelligence (AI) refers to..."
}

Response Fields:

Field	Type	Description
response	string	Agent’s response

POST //

Call a specific agent in multi-agent setup.

Request:

curl -X POST http://localhost:8000/content/researcher \
  -H "Content-Type: application/json" \
  -d '{"query": "Research AI trends"}'

Response:

{
  "agent": "Researcher",
  "query": "Research AI trends",
  "response": "Current AI trends include..."
}

GET //list

List available agents.

Request:

curl http://localhost:8000/content/list

Response:

{
  "agents": [
    {"name": "Researcher", "id": "researcher"},
    {"name": "Writer", "id": "writer"}
  ]
}

GET /health

Health check endpoint.

Request:

curl http://localhost:8000/health

Response:

{
  "status": "ok",
  "endpoints": ["/ask", "/content"]
}

GET /

Root endpoint with welcome message.

Request:

curl http://localhost:8000/

Response:

{
  "message": "Welcome to PraisonAI Agents API on port 8000. See /docs for usage.",
  "endpoints": ["/ask", "/content"]
}

GET /docs

Swagger UI documentation.

Request: Open in browser: http://localhost:8000/docs

Error Responses

Status	Description
400	Bad request - invalid JSON or missing query
401	Unauthorized - invalid or missing API key
500	Internal server error

Error Format:

{
  "detail": "Missing 'query' field in request"
}

Authentication

The Agent.launch() API server uses X-API-Key authentication when configured. When api_key is set in launch():

curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"query": "Hello"}'

Python Client

import requests

response = requests.post(
    "http://localhost:8000/ask",
    json={"query": "What is machine learning?"},
    headers={"Content-Type": "application/json"}
)

print(response.json()["response"])

Related

• Agents Server - Deploy agents as HTTP server
• MCP API - MCP server endpoints
• A2A API - A2A protocol endpoints