Ownership model
Every mutation is tied to the account that created the API key. Visibility and share behavior are applied exactly as if the creator made the change in-product.
Build unique AI personas with custom personalities
Continue conversations and build deeper stories
Build and manage characters programmatically
Continue where you left off
What would you like to create?
definition.
Select a character from Discover to begin a conversation.
@username
Manage your public, unlisted, and private characters from one place.
Delete your scenes here after moving or removing any default characters you still need.
Set a default persona and switch personas during chat.
Delete your account and all associated data from the app.
Link Google or Apple to turn this guest account into a permanent login without losing your profile or chats.
API REFERENCE
Production-ready endpoints for creating, listing, updating, and deleting RolePlay characters with account-scoped API keys.
The Character API is a control surface for your account catalog. The same account that owns the API key owns the characters the API creates.
Loading...
Every mutation is tied to the account that created the API key. Visibility and share behavior are applied exactly as if the creator made the change in-product.
Use it for creator dashboards, internal CMS tools, queue-based imports, and scheduled moderation or publishing workflows.
Treat this as a server-to-server integration. Keep keys off the client, log character IDs, and retry only transient failures.
The fastest safe path is: generate key, store it server-side, create one character, then use list and update for your management tooling.
Authorization: Bearer rp_... on every request.name, definition, greetings, and an avatar.id for list, update, and delete operations.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",
"description": "Sharp, stylish, and always one step ahead.",
"definition": "Stay in-character and concise.",
"greetings": ["Need a job done right?"],
"visibility": "unlisted",
"avatar": "data:image/png;base64,..."
}'
Keys are account-scoped and revocable. They should live in a trusted backend only, never in a public client bundle.
Authorization: Bearer rp_your_key_here
Treat keys like passwords. Use separate labels for environments and integrations so revocation is targeted.
These URLs are rendered from the current environment configuration and are the canonical routes to use.
Create a new character with required metadata, greetings, and a validated image payload.
Loading...
name, definition, greetings, and avatar.issue_share_id and explicit visibility.Return the authenticated account's existing characters for management flows and admin tooling.
Loading...
Partially update an existing character by id without rewriting the full
document.
Loading...
Remove an owned character by id. Use your own audit layer if human review
is required before deletion.
Loading...
Use this panel to validate payload shape, image rules, and raw create responses before wiring your own backend.
HTTP status plus JSON body from the create endpoint.
Ready.
Work against existing character IDs from one place. Update calls are partial, so leave fields blank when you do not want to change them.
Use list output to capture IDs, then run update or delete against the same key owner.
Ready.
apiCreateCharacter accepts avatar as a base64 image data URL.Build AI character integrations with our simple, powerful API. Create, manage, and automate your character catalog.
The RolePlay Character API provides programmatic access to create, manage, and automate AI characters.
Simple HTTP endpoints with JSON responses for easy integration.
API key authentication with account-scoped permissions.
Optimized for batch operations and production workloads.
Loading...
Bearer Token
JSON
Get started with the RolePlay API in under 5 minutes.
Generate an API key from the API settings page. Store it securely in your environment.
Use the code examples below to create your first character.
# Create your first character
curl -X POST "$API_ENDPOINT/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?"],
"avatar": "data:image/png;base64,..."
}'
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 in every reply.",
"definition": "You are Luna, a friendly assistant.",
"greetings": ["Hello! How can I help you today?"],
"avatar": "data:image/png;base64,..."
},
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 in every reply.',
definition: 'You are Luna, a friendly assistant.',
greetings: ['Hello! How can I help you today?'],
avatar: 'data:image/png;base64,...'
})
});
const data = await response.json();
console.log(data);
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_here
Simple, transparent pricing for developers.
Perfect for getting started and personal projects.
For teams with custom requirements.
Understand the structure of character data.
nameavatarsubtitlegreetingsdescriptiondefinitionmessage_examplesvisibilityprivate | unlisted | publiccharacter_collectionscard_version2.0idcreator_idcreator_tagshare_idissue_share_id is requested on a non-private charactermessage_countused_countControl who can discover and access your characters.
Only visible to you. Use for drafts and personal characters.
Accessible via direct link, but not shown in public feeds.
Visible to everyone. Shown in discovery and search results.
Handle API errors gracefully in your integration.
// Recommended retry delays with jitter
delays: [1s, 2s, 4s, 8s]
max_retries: 4
// Never retry: 400, 401, 403
Understand and work within API rate limits.
Rate limits protect the API from abuse and ensure fair usage. Limits vary by plan and endpoint.
Complete reference for all available endpoints.
/apiCreateCharacter
Create a new character with the specified attributes.
{
"name": "Luna",
"subtitle": "A helpful AI assistant",
"description": "Warm, concise, and useful in every reply.",
"definition": "You are Luna...",
"greetings": ["Hello!"],
"avatar": "data:image/png;base64,...",
"visibility": "private"
}
/apiListCharacters
List all characters owned by the authenticated account.
/apiUpdateCharacter
Update an existing character. Supports partial updates.
{
"id": "6e6b2e77-7cb0-4986-b903-489fd2132d65",
"visibility": "public"
}
/apiDeleteCharacter
Permanently delete a character by ID.
{
"id": "6e6b2e77-7cb0-4986-b903-489fd2132d65"
}
Production-ready code samples in multiple languages.
curl -X POST "$API_ENDPOINT/apiCreateCharacter" \
-H "Authorization: Bearer $ROLEPLAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Nora",
"subtitle": "Cyberpunk fixer",
"description": "Sharp, stylish, and always one step ahead.",
"definition": "Stay in-character and concise.",
"greetings": ["Need a job done right?"],
"avatar": "data:image/png;base64,...",
"visibility": "unlisted"
}'
import requests
api_key = "rp_your_key_here"
endpoint = "https://api.roleplaychat.ai/apiCreateCharacter"
payload = {
"name": "Nora",
"subtitle": "Cyberpunk fixer",
"description": "Sharp, stylish, and always one step ahead.",
"definition": "Stay in-character and concise.",
"greetings": ["Need a job done right?"],
"avatar": "data:image/png;base64,...",
"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',
description: 'Sharp, stylish, and always one step ahead.',
definition: 'Stay in-character and concise.',
greetings: ['Need a job done right?'],
avatar: 'data:image/png;base64,...',
visibility: 'unlisted'
})
});
const data = await response.json();
console.log(data);
curl -X GET "$API_ENDPOINT/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())
Best practices for securing your API integration.
Recent updates and changes to the API.
Added share IDs and share URLs to character outputs for easier distribution.
Enhanced update payload support with improved validation behavior.
Launch of create, list, update, and delete API endpoints.
Common questions about the RolePlay API.
Private visibility blocks non-owner reads by design. Change the character's visibility to unlisted or public to allow access.
Yes! Use the update endpoint to change the visibility to public or unlisted at any time.
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.
Use queue workers with batched retries and checkpointed progress. Avoid unbounded parallel writes. Start with a small batch to test, then gradually increase throughput.
You'll receive a 429 response. Implement exponential backoff and queue pending requests. For sustained high volume, contact us about enterprise limits.
Use Google, Apple, or a temporary guest account to start chatting.
Choose how your account should appear.
Choose a persona for this thread.