> Source: https://builder-docs.ema.ai/api-reference/ai-employees/ai-employee-api
> Title: AI Employee API

# 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)

### Headers

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

```bash
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)

### Headers

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

```bash
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)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Path Parameters

Parameter

Type

Description

`persona_id`

string

UUID of the AI Employee

### Example

```bash
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)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Example

```bash
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)

### Headers

Header

Type

Required

Description

`Authorization`

string

Yes

Bearer token

### Path Parameters

Parameter

Type

Description

`persona_id`

string

UUID of the AI Employee

### Example

```bash
curl -X DELETE https://your-instance.ema.co/api/personas/<persona_id> \
 -H "Authorization: Bearer <access_token>"
```

## Related

-   [AI Employee Overview](/legacy-docs/api-reference/ai-employees/overview) -- Core concepts
-   [AI Employee Data Model](/legacy-docs/api-reference/ai-employees/data-model) -- Data structures
-   [Template API](/legacy-docs/api-reference/ai-employees/template-api) -- Template management