Personas API

Conversational AI Configurations

Store and version conversational AI configurations with full API access. Build chat interfaces, AI agents, and multi-turn dialogue systems with model flexibility and version control.

Get API Access View API Docs
1

Create Persona Config

Define behavior, tone, expertise via Dashboard or API

2

Integrate via API

Call Personas API from your chat application

3

Test New Versions

Create new versions and test in parallel

4

Switch Instantly

Update version number to deploy new persona

Built for Conversational AI

Everything developers need for production chat interfaces. Versioning, model switching, and multi-turn dialogue support.

Full Version Control

Same versioning capabilities as Prompts API. Maintain 10+ versions of persona configurations. Test new versions without breaking production.

  • 10+ versions per persona configuration
  • Version-specific API calls
  • Production-safe testing
  • Instant rollback to any version
  • Complete audit trail

Model Provider Flexibility

Switch between OpenAI, Anthropic, Google Gemini, and more without changing your application code. Optimize for cost, quality, or speed.

  • OpenAI (GPT-4, GPT-3.5)
  • Anthropic (Claude 3.5 Sonnet, Opus)
  • Google (Gemini Pro, Ultra)
  • Meta (Llama models)
  • Switch providers instantly

Conversational AI Optimizations

Built specifically for multi-turn dialogue. Context management, conversation history, and stateful interactions out of the box.

  • Multi-turn conversation support
  • Context window management
  • Conversation history tracking
  • Stateful dialogue flows
  • Natural back-and-forth exchanges

Persona Configuration

Define conversational behavior, personality, expertise, and constraints. Create AI agents with distinct personas for different use cases.

  • Personality and tone settings
  • Domain expertise configuration
  • Conversation constraints
  • Behavioral guidelines
  • Role-specific instructions

API-First Architecture

RESTful API with TypeScript SDK available now. Python and C# SDKs coming soon. Build chat interfaces, AI agents, and conversational applications programmatically.

  • RESTful API with API key authentication
  • TypeScript/JavaScript SDK (available now)
  • Python SDK (coming soon)
  • C# SDK (coming soon)
  • Server-Sent Events (SSE) for streaming
  • Complete API documentation

Enterprise Security

API keys with granular permissions, rate limiting, and audit logs. Enterprise-grade security with encryption at rest and in transit.

  • API key management
  • Granular permission controls
  • Rate limiting and quotas
  • Detailed audit logs
  • Enterprise security standards

Conversations API Methods

Complete API for creating conversations, sending messages with streaming, and managing conversation state.

Creating Conversations

General Conversation

POST /conversations

Create a new conversation with custom system prompt and model. Parameters: system, model, externalUserId.

Persona Conversation

POST /conversations/persona

Start a conversation with a predefined persona. Parameters: personaId, externalUserId.

Sending Messages

Non-Streaming

POST /conversations/{id}/continue

Get complete response in one call. Best for batch processing.

HTTP/2 Streaming

POST /conversations/{id}/continue-stream

Stream responses using HTTP/2 protocol for real-time chat.

SSE Streaming

POST /conversations/{id}/continue-sse

Server-Sent Events for browser EventSource API compatibility.

Retrieving Conversations

GET /conversations

List all conversations

GET /conversations/user/{userId}

Get user's conversations

GET /conversations/persona/{personaId}

Get persona conversations

GET /conversations/{id}

Get specific conversation

Managing Conversations

PATCH /conversations/{id}/set-active

Set as active conversation

PATCH /conversations/{id}/set-metadata

Update metadata

PATCH /conversations/{id}/set-conversation-name

Set conversation name

PATCH /conversations/{id}/set-conversation-status

Update status

Full API Reference

For complete details on request/response formats, parameters, error codes, and advanced usage, visit our comprehensive API documentation.

View Complete API Documentation

Simple REST API Integration

Build chat interfaces with a few simple HTTP requests. Streaming, conversation history, and context management included.

  • Streaming Responses
    Real-time token streaming for natural conversation feel
  • Conversation Continuity
    Maintain context across multiple turns with conversation IDs
  • Version Control
    Test new persona versions without breaking live conversations
# Step 1: Create a persona conversation
curl -X POST 'https://api.hyperleapai.com/conversations/persona' \
  -H 'Content-Type: application/json' \
  -H 'x-hl-api-key: YOUR_API_KEY' \
  -d '{
    "personaId": "your-persona-id",
    "externalUserId": "user-123"
  }'

# Response: {"conversationId": "conv-abc123", ...}

# Step 2: Send message with SSE streaming
curl -X POST 'https://api.hyperleapai.com/conversations/conv-abc123/continue-sse' \
  -H 'Content-Type: application/json' \
  -H 'x-hl-api-key: YOUR_API_KEY' \
  -d '{
    "message": "I need help with my order"
  }'

# Or create a general conversation with custom system prompt
curl -X POST 'https://api.hyperleapai.com/conversations' \
  -H 'Content-Type: application/json' \
  -H 'x-hl-api-key: YOUR_API_KEY' \
  -d '{
    "system": "You are a helpful customer support agent",
    "model": "gpt-4",
    "externalUserId": "user-123"
  }'

# Retrieve conversation history
curl -X GET 'https://api.hyperleapai.com/conversations/conv-abc123' \
  -H 'x-hl-api-key: YOUR_API_KEY'

Prompts API vs Personas API

Choose the right API for your use case

Prompts API
Single-task execution
Personas API
Multi-turn conversations
Primary Use
Prompts API:Single-task execution
Personas API:Multi-turn conversations
Interface Style
Prompts API:Input → Output
Personas API:Dialogue-based
Versioning
Prompts API:10+ versions
Personas API:10+ versions
Model Switching
Prompts API:Full flexibility
Personas API:Full flexibility
Live Sources
Prompts API:Not available
Personas API:Not available (one-time setup)

When to use Prompts API: Single-task execution (e.g., "Generate blog post", "Extract data from invoice").

When to use Personas API: Multi-turn dialogue (e.g., customer support, sales qualification, training simulations).

Built for Conversational Applications

From customer support to training simulators, Personas API powers production chat

Customer Support Bots

Multi-turn support conversations

Version personas for different products

Sales Assistants

Lead qualification and discovery

A/B test conversation flows

Training Simulators

Role-play scenarios for skill building

Switch models for different difficulty

Virtual Advisors

Financial, legal, or technical advice

Roll back risky prompt changes

Why Developers Choose Personas API

Conversation Management

Multi-turn dialogue out of the box. Context windows, conversation history, and stateful interactions managed for you.

Production Safety

Test new personas in staging, A/B test conversation styles, roll back instantly if users report issues.

Model Flexibility

Switch between GPT-4, Claude, Gemini based on cost, quality, or latency requirements. No code changes needed.

Frequently Asked Questions

Everything you need to know

What is a Persona?

A Persona is a configuration for a conversational AI agent. It defines the system prompt, model, behavior, and constraints for multi-turn dialogues.

How do I switch models?

You can switch models (e.g., from GPT-4 to Claude 3) instantly in the dashboard or via API configuration. No code changes are required in your application.

Is it compatible with OpenAI SDK?

We provide our own typescript SDK that simplifies state management, but our API structure is familiar to developers used to OpenAI's chat completions.

How does versioning work?

You can save multiple versions of a Persona. Your API calls can reference a specific version ID or use the 'latest' alias.

Can I stream responses?

Yes, we support Server-Sent Events (SSE) and HTTP/2 streaming for real-time token generation, providing a snappy user experience.

Still have questions?

Contact our support team

Start Building Conversational AI

Version-controlled personas, model switching, multi-turn dialogue. Everything you need for production chat. Start with our free plan.

Get API Access Read Documentation