The Personas REST API provides complete CRUD operations for managing conversational AI personas. Personas define the personality, knowledge, and behavior of your AI agents across different channels and use cases.
Base URL: https://your-api-name.mercury.ratiomachina.com Authentication: x-mercury-api-key: YOUR_API_KEY
No query parameters supported. Returns all personas.
{
"personas": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "sales-alex-v1",
"name": "Sales Assistant Alex",
"description": "Friendly sales representative specializing in software solutions",
"data": {
"tone": "professional_friendly",
"business_description": "We provide AI-powered conversation solutions",
"channel": "sms",
"identity": {
"name": "Alex",
"role": "Sales Representative"
},
"offers": [
{
"title": "Free Consultation",
"description": "30-minute strategy session"
}
],
"objections": [
{
"objection": "too expensive",
"response": "Let's explore flexible pricing options."
}
]
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
]
}{
"externalId": "support-specialist-v1",
"name": "Customer Support Specialist",
"description": "Expert customer support agent for technical inquiries",
"data": {
"tone": "helpful_professional",
"business_description": "We provide comprehensive technical support",
"channel": "email",
"identity": {
"name": "Sarah",
"role": "Senior Support Specialist"
},
"offers": [
{
"title": "Free Support Session",
"description": "30-minute troubleshooting session"
}
],
"objections": [
{
"objection": "too complex",
"response": "Let me break this down into simple steps."
}
]
}
}{
"persona": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "support-specialist-v1",
"name": "Customer Support Specialist",
"description": "Expert customer support agent for technical inquiries",
"data": {
"tone": "helpful_professional",
"business_description": "We provide comprehensive technical support",
"channel": "email",
"identity": {
"name": "Sarah",
"role": "Senior Support Specialist"
},
"offers": [
{
"title": "Free Support Session",
"description": "30-minute troubleshooting session"
}
],
"objections": [
{
"objection": "too complex",
"response": "Let me break this down into simple steps."
}
]
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}external_id - Persona external IDNo query parameters supported.
{
"persona": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "support-specialist-v1",
"name": "Customer Support Specialist",
"description": "Expert customer support agent for technical inquiries",
"data": {
"tone": "helpful_professional",
"business_description": "We provide comprehensive technical support",
"channel": "email",
"identity": {
"name": "Sarah",
"role": "Senior Support Specialist"
},
"offers": [
{
"title": "Free Support Session",
"description": "30-minute troubleshooting session"
}
],
"objections": [
{
"objection": "too complex",
"response": "Let me break this down into simple steps."
}
]
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}Updates a persona. Supports partial updates - only provided fields will be modified.
{
"name": "Enhanced Customer Support Specialist",
"description": "Advanced customer support agent with AI-powered insights",
"data": {
"tone": "empathetic_professional",
"business_description": "Enhanced technical support platform",
"channel": "email",
"identity": {
"name": "Sarah",
"role": "Senior Support Specialist"
},
"offers": [
{
"title": "AI-Powered Analysis",
"description": "Smart troubleshooting with AI insights"
}
],
"objections": [
{
"objection": "too technical",
"response": "I'll explain everything in simple terms."
}
]
}
}{
"persona": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "support-specialist-v1",
"name": "Enhanced Customer Support Specialist",
"description": "Advanced customer support agent with AI-powered insights",
"data": {
"tone": "empathetic_professional",
"business_description": "Enhanced technical support platform",
"channel": "email",
"identity": {
"name": "Sarah",
"role": "Senior Support Specialist"
},
"offers": [
{
"title": "AI-Powered Analysis",
"description": "Smart troubleshooting with AI insights"
}
],
"objections": [
{
"objection": "too technical",
"response": "I'll explain everything in simple terms."
}
]
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T11:45:00Z"
}
}⚠️ Warning: Deleting a persona will permanently remove it and all associated conversation history. This action cannot be undone.
external_id - Persona external IDNo query parameters supported.
{
"message": "Persona deleted successfully",
"persona": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "support-specialist-v1",
"name": "Customer Support Specialist",
"deleted": true
}
}Delete multiple personas by their external IDs. Personas with existing conversations cannot be deleted.
{
"external_ids": [
"sales-rep-team-lead",
"technical-sales-engineer"
]
}{
"message": "2 persona(s) deleted successfully",
"deletedCount": 2,
"deletedPersonas": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "sales-rep-team-lead",
"name": "Sales Team Lead"
},
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"externalId": "technical-sales-engineer",
"name": "Technical Sales Engineer"
}
],
"notFound": []
}Archive multiple personas by their external IDs instead of deleting them. Archived personas retain all data.
{
"external_ids": [
"sales-rep-team-lead",
"technical-sales-engineer"
]
}{
"message": "2 persona(s) archived successfully",
"archived": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "sales-rep-team-lead",
"name": "Sales Team Lead",
"archived": true
},
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"externalId": "technical-sales-engineer",
"name": "Technical Sales Engineer",
"archived": true
}
],
"archived_count": 2,
"already_archived": [],
"already_archived_count": 0,
"not_found": [],
"not_found_count": 0
}