Skip to main content

​
Introduction

The Debate API creates real-time AI-powered debates between a user’s AI agent and selected opponent personas. The system orchestrates multi-round debates, streaming responses in real-time using Server-Sent Events (SSE), and provides comprehensive synthesis reports with winner determination.

​
Key Features

  • Real-time Streaming: All debate responses stream via SSE for immediate user feedback
  • Multi-round Debates: Configurable debate rounds (default: 5 rounds)
  • Intelligent Agent System: User agents adopt personality traits, interests, and communication styles from user profiles
  • Dynamic Opponent Selection: System selects appropriate opponent personas based on debate topics
  • Comprehensive Synthesis: AI-generated analysis including consensus points, disagreements, winner determination, and recommendations
  • Debate History: Persistent storage and retrieval of all debate sessions

​
Authentication

All Debate API endpoints require authentication via NextAuth session. Unauthenticated requests return 401 Unauthorized.

​
Rate Limits

Debate creation is rate-limited to 8 requests per minute per user per IP address.

​
Debate Flow

  1. Initialization: User submits topic and profile information
  2. Opponent Selection: System selects appropriate opponent based on topic
  3. Opening Statement: User’s AI agent presents opening argument
  4. Debate Rounds: Alternating responses between user agent and opponent (5 rounds)
  5. Synthesis: AI evaluates the debate and generates comprehensive analysis
  6. Completion: Debate saved to database with complete transcript and synthesis

​
Available Endpoints

Start Debate

POST /api/debate - Start a new AI-powered debate session

Debate History

GET /api/debate/history - Retrieve user’s debate history

​
Next Steps

Start a Debate

Learn how to initiate and stream debate sessions

View History

Retrieve and analyze past debates

Build docs developers (and LLMs) love

Get started for freeTalk to us