RATIO MACHINA STARTER logo

MERCURY

Conversation Design REST API

The Conversation Design REST API provides traditional CRUD operations for managing personas, contacts, conversations, messages, and skills. These endpoints follow RESTful conventions and support standard HTTP methods.

Base URL & Authentication

Base URL: https://your-api-name.mercury.ratiomachina.com
Authentication: x-mercury-api-key: YOUR_API_KEY

Personas

List All Personas

GET/personas

Query Parameters

  • limit - Number of results (default: 50)
  • offset - Skip results for pagination
  • role - Filter by persona role
  • archived - Include archived personas

Response Example

{
  "personas": [
    {
      "id": "uuid-here",
      "externalId": "sales-alex-v1",
      "name": "Sales Assistant Alex",
      "data": {
        "role": "sales",
        "tone": "professional_friendly"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0
  }
}

Create Persona

POST/personas

Request Body

{
  "name": "Customer Support Bot",
  "externalId": "support-bot-v1",
  "data": {
    "role": "customer_support",
    "tone": "empathetic_helpful",
    "business_description": "Technical support",
    "channel": "email",
    "identity": {
      "name": "Sarah",
      "role": "Support Specialist"
    }
  }
}

Response Example

{
  "persona": {
    "id": "uuid-here",
    "externalId": "support-bot-v1",
    "name": "Customer Support Bot",
    "data": {
      "role": "customer_support",
      "tone": "empathetic_helpful",
      "business_description": "Technical support",
      "channel": "email",
      "identity": {
        "name": "Sarah",
        "role": "Support Specialist"
      }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Get Persona by External ID

GET/personas/{external_id}

Path Parameters

  • external_id - Persona's external identifier

Response Example

{
  "persona": {
    "id": "uuid-here",
    "externalId": "sales-alex-v1",
    "name": "Sales Assistant Alex",
    "data": {
      "role": "sales",
      "tone": "professional_friendly",
      "offers": [...],
      "objections": [...]
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Update Persona

PUT/personas/{external_id}

Updates persona configuration. Only provided fields will be updated (partial updates supported).

Request Body

{
  "name": "Updated Sales Assistant",
  "data": {
    "tone": "professional_consultative",
    "offers": [
      {
        "title": "Free Demo",
        "description": "30-min product demo"
      }
    ]
  }
}

Response Example

{
  "persona": {
    "id": "uuid-here",
    "externalId": "sales-alex-v1",
    "name": "Updated Sales Assistant",
    "data": {
      "role": "sales",
      "tone": "professional_consultative",
      "offers": [...]
    },
    "updatedAt": "2024-01-15T11:30:00Z"
  }
}

Delete Persona

DELETE/personas/{external_id}

⚠️ Warning: Deleting a persona will permanently remove it and all associated conversations and messages. This action cannot be undone.

Path Parameters

  • external_id - Persona's external identifier

Response Example

{
  "message": "Persona deleted successfully",
  "deletedPersona": {
    "id": "uuid-here",
    "externalId": "sales-alex-v1"
  }
}

Contacts

List All Contacts

GET/contacts

Query Parameters

  • limit - Number of results (default: 50)
  • offset - Skip results for pagination
  • search - Search by name or email
  • archived - Include archived contacts

Response Example

{
  "contacts": [
    {
      "id": "uuid-here",
      "externalId": "customer_12345",
      "name": "John Smith",
      "data": {
        "email": "john@example.com",
        "phone": "+1234567890",
        "lead_source": "website_form"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0
  }
}

Create Contact

POST/contacts

Request Body

{
  "name": "Jane Doe",
  "externalId": "crm_contact_567",
  "data": {
    "email": "jane@company.com",
    "phone": "+1987654321",
    "company": "Acme Corp",
    "lead_source": "trade_show",
    "preferences": {
      "channel": "email",
      "frequency": "weekly"
    }
  }
}

Response Example

{
  "contact": {
    "id": "uuid-here",
    "externalId": "crm_contact_567",
    "name": "Jane Doe",
    "data": {
      "email": "jane@company.com",
      "phone": "+1987654321",
      "company": "Acme Corp",
      "lead_source": "trade_show",
      "preferences": {
        "channel": "email",
        "frequency": "weekly"
      }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Conversations

List All Conversations

GET/conversations

Query Parameters

  • limit - Number of results (default: 50)
  • offset - Skip results for pagination
  • persona_id - Filter by persona
  • contact_id - Filter by contact
  • channel - Filter by communication channel
  • archived - Include archived conversations

Response Example

{
  "conversations": [
    {
      "id": "uuid-here",
      "externalId": "conv_website_john_smith",
      "personaId": "persona-uuid",
      "contactId": "contact-uuid",
      "channel": "sms",
      "messageCount": 12,
      "lastMessageAt": "2024-01-15T14:22:00Z",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 3420,
    "limit": 50,
    "offset": 0
  }
}

Messages

List Messages in Conversation

GET/conversations/{external_id}/messages

Path Parameters

  • external_id - Conversation's external identifier

Query Parameters

  • limit - Number of messages (default: 100)
  • before - Messages before timestamp
  • after - Messages after timestamp

Response Example

{
  "messages": [
    {
      "id": "uuid-here",
      "conversationId": "conv-uuid",
      "content": "Hello, I'm interested in your product.",
      "sender": "contact",
      "data": {
        "attachments": [],
        "metadata": {}
      },
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "uuid-here-2",
      "conversationId": "conv-uuid",
      "content": "Thank you for your interest! I'd be happy to help you learn more about our solutions.",
      "sender": "persona",
      "data": {
        "generated": true,
        "confidence": 0.95
      },
      "createdAt": "2024-01-15T10:30:15Z"
    }
  ],
  "conversation": {
    "id": "conv-uuid",
    "externalId": "conv_website_john_smith"
  }
}

Create Message in Conversation

POST/conversations/{external_id}/messages

Request Body

{
  "content": "Can you tell me more about pricing?",
  "sender": "contact",
  "data": {
    "channel": "sms",
    "urgency": "normal"
  }
}

Response Example

{
  "message": {
    "id": "uuid-here",
    "conversationId": "conv-uuid",
    "content": "Can you tell me more about pricing?",
    "sender": "contact",
    "data": {
      "channel": "sms",
      "urgency": "normal"
    },
    "createdAt": "2024-01-15T10:35:00Z"
  }
}

Skills

List All Skills

GET/skills

Query Parameters

  • limit - Number of results (default: 50)
  • offset - Skip results for pagination
  • role - Filter by skill role
  • archived - Include archived skills

Response Example

{
  "skills": [
    {
      "id": "uuid-here",
      "externalId": "sentiment_analyzer_v1",
      "name": "Sentiment Analyzer",
      "data": {
        "role": "sentiment_analysis",
        "description": "Analyzes customer sentiment",
        "inputSchema": {...},
        "outputSchema": {...}
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0
  }
}

Create Skill

POST/skills

Request Body

{
  "name": "Knowledge Base Lookup",
  "externalId": "kb_lookup_v1",
  "data": {
    "role": "knowledge",
    "description": "Searches internal knowledge base",
    "apiEndpoint": "https://api.example.com/kb/search",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": {"type": "string"}
      }
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "results": {"type": "array"}
      }
    }
  }
}

Response Example

{
  "skill": {
    "id": "uuid-here",
    "externalId": "kb_lookup_v1",
    "name": "Knowledge Base Lookup",
    "data": {
      "role": "knowledge",
      "description": "Searches internal knowledge base",
      "apiEndpoint": "https://api.example.com/kb/search",
      "inputSchema": {...},
      "outputSchema": {...}
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Get Skill Executions

GET/skills/{id}/executions

Retrieves execution history for a specific skill, including inputs, outputs, and performance metrics.

Query Parameters

  • limit - Number of executions (default: 50)
  • status - Filter by execution status
  • from - Executions after date
  • to - Executions before date

Response Example

{
  "executions": [
    {
      "id": "exec-uuid",
      "skillId": "skill-uuid",
      "conversationId": "conv-uuid",
      "input": {
        "query": "pricing information"
      },
      "output": {
        "results": [...]
      },
      "status": "success",
      "executionTime": 245,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 50,
    "offset": 0
  }
}

Batch Delete Operations

⚠️ Warning: Batch delete operations permanently remove multiple resources. These actions cannot be undone. Always verify your selection criteria before executing.

Batch Delete Personas

DELETE/personas

Request Body

{
  "criteria": {
    "role": "sales",
    "createdBefore": "2024-01-01T00:00:00Z"
  },
  "dryRun": true
}

Criteria Options

  • ids - Array of specific persona IDs
  • externalIds - Array of external IDs
  • role - Filter by persona role
  • createdBefore - Delete personas created before date
  • createdAfter - Delete personas created after date
  • dryRun - Return what would be deleted without deleting

Response Example

{
  "message": "Batch delete completed",
  "deletedCount": 15,
  "deletedPersonas": [
    {
      "id": "uuid-1",
      "externalId": "old-sales-bot-1",
      "name": "Old Sales Bot 1"
    },
    {
      "id": "uuid-2", 
      "externalId": "old-sales-bot-2",
      "name": "Old Sales Bot 2"
    }
  ],
  "dryRun": false
}

Batch Archive Operations

📦 Archive: Archive operations move resources to an archived state where they are hidden from normal operations but can be restored if needed.

Archive Personas

POST/personas/archive

Request Body

{
  "criteria": {
    "role": "customer_support",
    "lastUsedBefore": "2023-12-01T00:00:00Z"
  },
  "archiveReason": "Seasonal campaign ended"
}

Response Example

{
  "message": "Batch archive completed",
  "archivedCount": 8,
  "archivedPersonas": [
    {
      "id": "uuid-1",
      "externalId": "winter-support-bot",
      "name": "Winter Support Bot",
      "archivedAt": "2024-01-15T10:30:00Z",
      "archiveReason": "Seasonal campaign ended"
    }
  ]
}

Common Response Formats

Success Responses

All successful responses follow a consistent structure with the resource name as the root key:

Single Resource

{
  "persona": {
    "id": "uuid-here",
    "externalId": "sales-alex-v1",
    "name": "Sales Assistant Alex",
    ...
  }
}

Multiple Resources

{
  "personas": [...],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0,
    "hasNext": true
  }
}

Error Responses

Validation Error (400)

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "name",
    "message": "Name is required"
  }
}

Not Found (404)

{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "details": {
    "resource": "persona",
    "identifier": "non-existent-id"
  }
}

Next Steps

Now that you understand the REST API endpoints, explore the RPC API for more complex operations like conversation creation with automatic resource upserts.

Conversation Design RPC →Monitoring REST API →
Transcend the hype with MERCURY by Ratio Machina