AI Employee API
This page documents the REST API endpoints for creating, updating, and managing AI Employees (personas).
CreateAIEmployee
Create a new AI Employee within a tenant.
| Property | Value |
|---|
| URL | /api/personas/create_persona |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Display name of the AI Employee |
description | string | No | Description of the AI Employee's purpose |
template_id | string | Conditional | Template ID to base the AI Employee on. Provide exactly one of template_id or source_persona_id. |
source_persona_id | string | Conditional | Source AI Employee to clone from. Provide exactly one of template_id or source_persona_id. |
proto_config | object | No | Full protobuf configuration (widgets, display settings, etc.) |
trigger_type | string | No | Optional trigger type such as CHAT or DASHBOARD |
clone_data | boolean | No | When cloning from source_persona_id, also replicate uploaded files and scraped URLs |
Example
curl -X POST https://your-instance.ema.co/api/personas/create_persona \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "IT Support Agent",
"description": "Handles IT helpdesk tickets and troubleshooting",
"template_id": "<template-uuid>",
"trigger_type": "CHAT",
"proto_config": {
"widgets": [],
"display_settings": {
"display_type": "SINGLE_PAGE"
}
}
}'
Response
| Field | Type | Description |
|---|
persona_id | string | UUID of the created AI Employee |
state | string | Initial state of the created AI Employee |
workflow_id | string | Associated workflow ID, if one was created |
UpdateAIEmployee
Update an existing AI Employee's configuration.
| Property | Value |
|---|
| URL | /api/personas/update_persona |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
persona_id | string | Yes | UUID of the AI Employee (sent in the request body, not as a path parameter) |
name | string | No | Updated display name |
description | string | No | Updated description |
proto_config | object | Yes | Updated protobuf configuration |
workflow | object | No | Updated workflow definition when changing the associated workflow |
Example
curl -X POST https://your-instance.ema.co/api/personas/update_persona \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"persona_id": "<persona-uuid>",
"name": "Updated IT Support Agent",
"description": "Enhanced IT helpdesk support with broader knowledge base",
"proto_config": {
"widgets": []
}
}'
Response
Returns the updated PersonaDTO.
GetAccessLevel
Retrieve the current user's access level for a specific AI Employee.
| Property | Value |
|---|
| URL | /api/personas/{persona_id}/access_level |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Path Parameters
| Parameter | Type | Description |
|---|
persona_id | string | UUID of the AI Employee |
Example
curl -X GET https://your-instance.ema.co/api/personas/<persona_id>/access_level \
-H "Authorization: Bearer <access_token>"
Response
| Field | Type | Description |
|---|
id | string | UUID of the AI Employee |
access_level | string | The user's access level for this AI Employee |
GetPersonasForTenant
Retrieve all AI Employees for the authenticated tenant.
| Property | Value |
|---|
| URL | /api/personas/get_personas_for_tenant |
| HTTP Method | GET |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Example
curl -X GET https://your-instance.ema.co/api/personas/get_personas_for_tenant \
-H "Authorization: Bearer <access_token>"
Response
Returns a list of AI Employee objects for the tenant.
| Field | Type | Description |
|---|
personas | array | List of PersonaDTO objects |
Each PersonaDTO includes fields such as id, template_id, name, description, status, proto_config, access_level, and other metadata.
DeleteAIEmployee
Delete an AI Employee.
| Property | Value |
|---|
| URL | /api/personas/{persona_id} |
| HTTP Method | DELETE |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Path Parameters
| Parameter | Type | Description |
|---|
persona_id | string | UUID of the AI Employee |
Example
curl -X DELETE https://your-instance.ema.co/api/personas/<persona_id> \
-H "Authorization: Bearer <access_token>"