Platform Getting Started

Install, run server, and make your first API call to PraisonAI Platform

Walk from zero to a running PraisonAI Platform server with your first API call — no prior knowledge assumed.

from praisonaiagents import Agent

agent = Agent(
    name="Platform Helper",
    instructions="Assist with workspace setup tasks.",
)

agent.start("Create a sample issue for my new project.")

The user installs the platform, authenticates, then drives workspaces and issues from the API or SDK.

What is the PraisonAI Platform?

PraisonAI Platform is a multi-tenant workspace for organizing AI agent work. It provides issue tracking, project management, and team collaboration — all built for AI agents. Access everything through a REST API and Python SDK.

Prerequisites

1. System Requirements

   • Python 3.10 or higher
   • pip or uv package manager
   • Terminal (macOS/Linux/Windows)

---

Install

1. Install PraisonAI Platform

   Copy-paste this one-liner into your terminal:

   pip install praisonai-platform
   

   This installs the complete platform package including the API server and CLI tools.

---

Start the Server

1. Launch the Platform Server

   Start the server with this command:

   uvicorn praisonai_platform.api.app:create_app --factory --port 8000
   

   What happens:

   • SQLite database auto-created in current directory
   • Server listens on port 8000
   • All endpoints available at http://localhost:8000

   Expected output:

   INFO:     Started server process [12345]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
   
2. Verify Server Health

   Test the server is running:

   curl http://localhost:8000/health
   

   Expected response:

   {"status": "ok"}
   

   Your Platform server is now ready for API calls.

If you instead use python -m praisonai_platform, the default bind is 127.0.0.1. Set PLATFORM_HOST=0.0.0.0 or pass --host 0.0.0.0 to allow remote connections.

---

Configure the Database (Optional)

1. Default: In-Memory SQLite

   By default, the platform uses an in-memory SQLite database — your data is lost when the server restarts.

   This is perfect for testing and development:

   # No configuration needed
   uvicorn praisonai_platform.api.app:create_app --factory --port 8000
   
2. Persistent SQLite

   To keep your data between server restarts, set a database URL:

   export DATABASE_URL="sqlite+aiosqlite:///./platform.db"
   uvicorn praisonai_platform.api.app:create_app --factory --port 8000
   

   The database file will be created automatically on first use.

3. Production PostgreSQL

   For production, use PostgreSQL:

   # Install PostgreSQL driver
   pip install asyncpg
   
   # Set database URL
   export DATABASE_URL="postgresql+asyncpg://user:password@localhost/platform"
   
   # Initialize tables (one-time)
   python -c "import asyncio; from praisonai_platform.db import init_db; asyncio.run(init_db())"
   
   # Start server
   uvicorn praisonai_platform.api.app:create_app --factory --port 8000
   

   For complete database schema documentation, see the Data Model page.

---

Register Your First User

1. Create User Account

   Register a new user account:

   curl -s -X POST http://localhost:8000/api/v1/auth/register \
     -H "Content-Type: application/json" \
     -d '{"email":"[e-mail]","password":"mypassword","name":"My Name"}' \
     --max-time 10
   

   Expected response:

   {
     "access_token": "eyJhbGciOiJIUzI1NiIs...",
     "token_type": "bearer",
     "user": {
       "id": 1,
       "email": "[e-mail]",
       "name": "My Name"
     }
   }
   

   Save the token! Copy the access_token value — you’ll use it for all future API requests.

---

Create Your First Workspace

1. Set Your Token

   Export your token as an environment variable:

   TOKEN="paste-your-token-here"
   

   Replace paste-your-token-here with your actual token from the registration response.

2. Create Workspace

   Create your first workspace:

   curl -s -X POST http://localhost:8000/api/v1/workspaces/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"My First Workspace"}' \
     --max-time 10
   

   Expected response:

   {
     "id": 1,
     "name": "My First Workspace",
     "created_at": "2024-01-15T10:30:00Z",
     "owner_id": 1
   }
   

   Your workspace is ready for organizing AI agent projects.

---

Create Your First Issue

1. Set Workspace ID

   Export your workspace ID:

   WS_ID="1"
   

   Use the id value from your workspace creation response.

2. Create Issue

   Create your first issue in the workspace:

   curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"title":"Hello from the platform!","priority":"medium"}' \
     --max-time 10
   

   Expected response:

   {
     "id": 1,
     "identifier": "ISS-1",
     "title": "Hello from the platform!",
     "priority": "medium",
     "status": "open",
     "workspace_id": 1,
     "created_at": "2024-01-15T10:35:00Z"
   }
   

   Notice the auto-generated identifier field: ISS-1. This is your issue’s human-readable ID for tracking and reference.

---

Next Steps

You now have a running PraisonAI Platform with your first workspace and issue. Here’s what to explore next:

Quick Tutorial

Learn core Platform concepts with hands-on examples

Agent Management

Connect and manage AI agents in your workspace

Python SDK

Use the Python SDK for programmatic Platform access

API Reference

Complete REST API documentation and examples

Key Concepts Explained

What is a token?

A token is your authentication credential — like a password for API requests. Include it in the Authorization: Bearer <token> header for all API calls.

What is an endpoint?

An endpoint is a URL that accepts API requests. For example, POST /api/v1/workspaces/ creates a new workspace. Each endpoint performs a specific action.

What is JSON?

JSON is a data format for sending structured information. It uses key-value pairs like {"name": "value"}. APIs often accept and return JSON data.

What does curl do?

curl is a command-line tool for making HTTP requests. The -X POST sends data to create something, -H adds headers, and -d sends the JSON data.