RolePlay API
Build AI character integrations with our simple, powerful API. Create, manage, and automate your character catalog.
Overview
The RolePlay Character API provides programmatic access to create, manage, and automate AI characters.
RESTful API
Simple HTTP endpoints with JSON responses for easy integration.
Secure by Default
API key authentication with account-scoped permissions.
Fast & Reliable
Optimized for batch operations and production workloads.
https://api.roleplaychat.ai
Bearer Token
JSON
Key Features
- Resource ownership tied to API key owner account
- JSON responses optimized for queue/job processing
- Explicit visibility and share behavior controls
- Partial updates supported for efficient mutations
Quickstart
Get started with the RolePlay API in under 5 minutes.
Get your API key
Generate an API key from the API settings page. Store it securely in your environment.
Make your first request
Use the code examples below to create your first character.
# Create your first character
curl -X POST "https://api.roleplaychat.ai/apiCreateCharacter" \
-H "Authorization: Bearer $ROLEPLAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Luna",
"subtitle": "A helpful AI assistant",
"description": "Warm, concise, and useful in every reply.",
"definition": "You are Luna, a friendly assistant.",
"greetings": ["Hello! How can I help you today?"]
}'import requests
api_key = "rp_your_api_key"
endpoint = "https://api.roleplaychat.ai/apiCreateCharacter"
response = requests.post(
endpoint,
headers={"Authorization": f"Bearer {api_key}"},
json={
"name": "Luna",
"subtitle": "A helpful AI assistant",
"description": "Warm, concise, and useful.",
"definition": "You are Luna, a friendly assistant.",
"greetings": ["Hello! How can I help you today?"]
},
timeout=30
)
print(response.json())const response = await fetch('https://api.roleplaychat.ai/apiCreateCharacter', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Luna',
subtitle: 'A helpful AI assistant',
description: 'Warm, concise, and useful.',
definition: 'You are Luna, a friendly assistant.',
greetings: ['Hello! How can I help you today?']
})
});
const data = await response.json();
console.log(data);Authentication
Secure your API requests with Bearer token authentication.
All API requests require authentication using a Bearer token in the Authorization header.
Authorization: Bearer rp_your_api_key_hereBest Practices
- Use separate keys for each environment (dev, staging, prod)
- Rotate keys periodically and during incident response
- Never embed keys in client-side code or public repos
- Store keys in environment variables or secret managers
Pricing
Simple, transparent pricing for developers.
Creator
Perfect for getting started and personal projects.
- Full API access
- Standard rate limits
- Community support
Enterprise
For teams with custom requirements.
- Custom rate limits
- Priority support
- SLA guarantees
- Integration assistance
Character Model
Understand the structure of character data.
namedefinitiongreetingssubtitledescriptionvisibilityprivate | unlisted | publictagsavatarVisibility States
Control who can discover and access your characters.
Private
Only visible to you. Use for drafts and personal characters.
Unlisted
Accessible via direct link, but not shown in public feeds.
Public
Visible to everyone. Shown in discovery and search results.
Error Handling
Handle API errors gracefully in your integration.
Retry Strategy
// Recommended retry delays with jitter
delays: [1s, 2s, 4s, 8s]
max_retries: 4
// Never retry: 400, 401, 403Rate Limits
Understand and work within API rate limits.
Rate limits protect the API from abuse and ensure fair usage. Limits vary by plan and endpoint.
Best Practices
- Use queueing for batch operations
- Monitor 429 response rates
- Implement exponential backoff
- Persist failed requests for replay
API Endpoints
Complete reference for all available endpoints.
/apiCreateCharacter
Create a new character with the specified attributes.
Request Body
{
"name": "Luna",
"subtitle": "A helpful AI assistant",
"definition": "You are Luna...",
"greetings": ["Hello!"],
"visibility": "private"
}/apiListCharacters
List all characters owned by the authenticated account.
/apiUpdateCharacter
Update an existing character. Supports partial updates.
Request Body
{
"characterId": "char_abc123",
"visibility": "public"
}/apiDeleteCharacter
Permanently delete a character by ID.
Request Body
{
"characterId": "char_abc123"
}Code Examples
Production-ready code samples in multiple languages.
Create a Character
curl -X POST "https://api.roleplaychat.ai/apiCreateCharacter" \
-H "Authorization: Bearer $ROLEPLAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Nora",
"subtitle": "Cyberpunk fixer",
"definition": "Stay in-character and concise.",
"greetings": ["Need a job done right?"],
"visibility": "unlisted"
}'import requests
api_key = "rp_your_key_here"
endpoint = "https://api.roleplaychat.ai/apiCreateCharacter"
payload = {
"name": "Nora",
"subtitle": "Cyberpunk fixer",
"definition": "Stay in-character and concise.",
"greetings": ["Need a job done right?"],
"visibility": "unlisted",
}
response = requests.post(
endpoint,
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=30,
)
print(response.json())const response = await fetch('https://api.roleplaychat.ai/apiCreateCharacter', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Nora',
subtitle: 'Cyberpunk fixer',
definition: 'Stay in-character and concise.',
greetings: ['Need a job done right?'],
visibility: 'unlisted'
})
});
const data = await response.json();
console.log(data);List Characters
curl -X GET "https://api.roleplaychat.ai/apiListCharacters" \
-H "Authorization: Bearer $ROLEPLAY_API_KEY"response = requests.get(
"https://api.roleplaychat.ai/apiListCharacters",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
print(response.json())Security
Best practices for securing your API integration.
Key Management
- Keep API keys server-side only
- Rotate keys on a regular schedule
- Revoke compromised keys immediately
- Use separate keys for each environment
Monitoring
- Apply secret scanning in CI and source control
- Alert on unusual API traffic patterns
- Log API calls with request metadata for audit
Changelog
Recent updates and changes to the API.
Share IDs & URLs
Added share IDs and share URLs to character outputs for easier distribution.
Expanded Update Payload
Enhanced update payload support with improved validation behavior.
Initial Release
Launch of create, list, update, and delete API endpoints.
Frequently Asked Questions
Common questions about the RolePlay API.
Why doesn't my private character link work for others?
Private visibility blocks non-owner reads by design. Change the character's visibility to unlisted or public to allow access.
Can I publish a character after creating it as private?
Yes! Use the update endpoint to change the visibility to public or unlisted at any time.
Should I call APIs directly from browser apps?
No. Always use your backend as a trusted proxy so API keys are never exposed to users. Client-side API calls expose your key and violate security best practices.
How should I migrate thousands of characters?
Use queue workers with batched retries and checkpointed progress. Avoid unbounded parallel writes. Start with a small batch to test, then gradually increase throughput.
What happens if I exceed rate limits?
You'll receive a 429 response. Implement exponential backoff and queue pending requests. For sustained high volume, contact us about enterprise limits.