Skip to main content
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:
FieldTypeRequiredDescription
querystringYesThe message to send
Response: 
{
  "response": "Artificial intelligence (AI) refers to..."
}
Response Fields:
FieldTypeDescription
responsestringAgent’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

StatusDescription
400Bad request - invalid JSON or missing query
401Unauthorized - invalid or missing API key
500Internal server error
Error Format: 
{
  "detail": "Missing 'query' field in request"
}

​
Authentication

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"])