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

# AI Employee API

An AI Employee (AIE) is a workflow plus everything that makes it operational — its modality, knowledge bases, connected Tools, and configuration. The AI Employee API lets you create one, shape its agents, save and publish versions, and clone or archive it, all programmatically. Because an AI Employee _is_ a workflow, its endpoints live in the workflow service; the individual agents inside it are managed through the agent service.

> [INFO]
> **Two prefixes, one resource.** AI Employee lifecycle endpoints are exposed under `/api/v1/ai-employees` (an alias that emits AI-Employee-flavored audit events) and the canonical workflow CRUD lives under `/api/v1/workflow`. A workflow ID and the ID of the AI Employee that owns it are the same UUID. This page uses whichever prefix the platform mounts the route under.

All requests on this page require a [JWT or tenant API key](/builder/v2/api-reference/authentication), and `Content-Type: application/json` for bodies. Examples use `https://your-tenant.ema.co` as the host.

## Create an AI Employee

Create a new AI Employee (a draft workflow) with `POST /api/v1/workflow/workflows`. Only `name` is required; `interaction_type` chooses the modality and defaults to `form`.

```http
POST https://your-tenant.ema.co/api/v1/workflow/workflows
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "name": "Support Triage",
  "description": "Routes inbound tickets and drafts a first reply.",
  "interaction_type": "chat",
  "icon": "headphones",
  "category": "Customer Support"
}
```

`interaction_type` is one of `chat`, `form`, `dashboard`, or `voice`. The response is the full workflow:

```json
{
  "id": "3f7a...",
  "tenant_id": "a4d2...",
  "name": "Support Triage",
  "interaction_type": "chat",
  "status": "draft",
  "latest_version": 1,
  "icon": "headphones",
  "category": "Customer Support"
}
```

A freshly created AI Employee is a `draft` with an empty DAG. Note `latest_version` (a counter bumped on every save and publish) versus `active_version` (the version number that is currently live — omitted until you publish).

> [TIP]
> **Start from a template.** Instead of building from scratch, clone a template: `GET /api/v1/workflow/templates` lists the templates visible to your tenant, and `POST /api/v1/workflow/templates/{id}/create-workflow` snapshots a template's DAG and modality into a new independent draft.

## Read and list AI Employees

-   **List:** `GET /api/v1/workflow/workflows` — paginated with `page` and `page_size`. Filter by modality with `interaction_type` (`chat`, `form`, `dashboard`, `voice`), search by `q` (fuzzy over name and description), or list archived AIEs with `archived=true`.
-   **Get one:** `GET /api/v1/workflow/workflows/{id}` — returns the full workflow including its `dag_definition`.

```http
GET https://your-tenant.ema.co/api/v1/workflow/workflows?interaction_type=chat&page=1&page_size=20
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
```

The list response is the standard paginated envelope (`items`, `total`, `page`, `page_size`, `has_more`, `next_cursor`).

## Update an AI Employee

Two ways to update, depending on how much you're changing:

-   **Replace:** `PUT /api/v1/workflow/workflows/{id}` with the full `UpdateWorkflowRequest` (name, description, `dag_definition`, interaction type, icon, category).
-   **Patch:** `PATCH /api/v1/workflow/workflows/{id}` to change only the fields you send.

```http
PATCH https://your-tenant.ema.co/api/v1/workflow/workflows/3f7a...
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{ "description": "Now also tags tickets by product area." }
```

To set the category, send a non-empty `category`; send `""` to clear it (moving the AIE to Uncategorized); omit the field to leave it unchanged.

### Configuration

An AI Employee carries configuration beyond its DAG — model selection, optimization priority, data protection, and chat-UX settings:

-   **Full config:** `GET` / `PUT /api/v1/workflow/workflows/{id}/config`.
-   **LLM-only merge:** `PATCH /api/v1/workflow/workflows/{id}/llm-config` updates just the model-related fields — `llm_mode` (`ALL`, `SELECTED`, `CUSTOM`), `selected_model_ids`, `custom_model_config`, `optimization_priority` (`MOST_ACCURATE`, `CHEAPEST`, `BALANCED`, `AUTO`, `FASTEST`), `data_protection_fields`, and `use_own_providers` — while leaving chat-UX fields untouched.

EmaFusion™ chooses the model per call within whatever the `llm_mode` and `selected_model_ids` allow.

## Manage the agents inside an AI Employee

The work an AI Employee does is performed by agents wired into its workflow DAG. The agent service manages those agents and their reusable definitions, under `/api/v1/agent`.

### Agent types

Every agent is one of five configurable types, plus a custom escape hatch:

Type

What it does

`intent_classification`

Classifies the input into one of a configured set of intents (optionally gated by per-intent eligibility rules).

`search_respond`

Retrieves from knowledge bases and answers with citations.

`extraction`

Extracts structured fields from the input against a schema.

`rule_validation`

Validates input against rules and can emit an Excel report.

`respond`

Generates a direct response from Instructions.

`custom`

A builder-defined agent for behavior the standard types don't cover.

List the agent-type catalog (each type's live version and schemas) with `GET /api/v1/agent/agent-types`, and fetch a single `(type, version)` with `GET /api/v1/agent/agent-types/{type}/{version}`. Versions follow the pattern `v0`, `v1`, …; a workflow node pins the version it runs against.

### Agent definitions

A reusable agent is an _agent definition_ — a saved agent type, Instructions (`system_prompt_template`), input schema, LLM config, and type-specific config.

-   **Create:** `POST /api/v1/agent/agent-definitions`
-   **List:** `GET /api/v1/agent/agent-definitions` (paginated)
-   **Get / update / delete:** `GET` / `PUT` / `DELETE /api/v1/agent/agent-definitions/{id}`

```http
POST https://your-tenant.ema.co/api/v1/agent/agent-definitions
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "name": "Ticket classifier",
  "agent_type": "intent_classification",
  "system_prompt_template": "Classify the ticket into one of the support queues.",
  "input_schema": { "type": "object", "properties": { "ticket": { "type": "string" } } },
  "type_config": {
    "intents": ["billing", "technical", "account"]
  }
}
```

### Test an agent before you wire it in

`POST /api/v1/agent/agents/test-execute` runs an inline agent configuration once against sample inputs, without saving anything to the workflow. Use it to iterate on Instructions and schema. You can attach `knowledge_bases` and `action_ids`, set `is_dry_run`, and pass a `workflow_id` for production-equivalent context.

```http
POST https://your-tenant.ema.co/api/v1/agent/agents/test-execute
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Content-Type: application/json

{
  "agent_config": {
    "agent_type": "search_respond",
    "system_prompt_template": "Answer using only the HR knowledge base.",
    "input_schema": { "type": "object", "properties": { "question": { "type": "string" } } }
  },
  "inputs": { "question": "How many vacation days do I get?" }
}
```

The response is a `TestExecution` with `status` (`running`, `completed`, `failed`), the agent's `output`, `tokens_used` (and a per-model `token_breakdown`), and an `error` when it fails. A `search_respond` agent returns its citations inside `output`. Past test executions are listed with `GET /api/v1/agent/agents/test-executions` and fetched by ID at `GET /api/v1/agent/agents/test-executions/{id}`.

## Publish and versioning

An AI Employee runs against a _published_ version. Saving the DAG creates draft checkpoints (bumping `latest_version`); publishing makes a version live (setting `active_version`).

### Publish

```http
POST https://your-tenant.ema.co/api/v1/ai-employees/{id}/publish
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
```

(The canonical route `POST /api/v1/workflow/workflows/{id}/publish` is equivalent.) Publish runs the full validation matrix — DAG structure, LLM provider availability, HITL assignees, MCP servers, per-tool config, and the agent-type version each node pins. On failure it returns `422` with either a flat error or a wrapped `error.issues[]` listing the offending agent-type versions (deprecated, deleted, broken, unknown, or pre-release).

### Versions

-   **List versions:** `GET /api/v1/ai-employees/{id}/versions`
-   **Get a version:** `GET /api/v1/ai-employees/{id}/versions/{version}`
-   **Rename / describe:** `PATCH /api/v1/ai-employees/{id}/versions/{version}`
-   **Delete:** `DELETE /api/v1/ai-employees/{id}/versions/{version}` (cannot delete the active version)
-   **Promote a version to live:** `POST /api/v1/ai-employees/{id}/versions/{version}/promote`
-   **Revert to a past published version:** `POST /api/v1/ai-employees/{id}/versions/{version}/revert`

Both promote and revert return the `VersionResponse` for the now-active version. Revert additionally reports `data_revert_dispatch` (`ok` / `failed`), indicating whether knowledge-base reconciliation was dispatched to the ingestion service.

## Clone, archive, and restore

-   **Clone:** `POST /api/v1/ai-employees/{id}/clone` — copies the AI Employee into a new draft. Pass an optional `name`; when omitted the copy is named `<source name> (Copy)`.
-   **Archive (soft delete):** `DELETE /api/v1/workflow/workflows/{id}` — archives the AIE. Archived AIEs are hidden from the default list and surface only with `archived=true`.
-   **Restore:** `POST /api/v1/ai-employees/{id}/restore` (or `POST /api/v1/workflow/workflows/{id}/restore`). Returns `404` if the AIE doesn't exist or isn't currently archived.

## What's next

-   [Workflow API](/builder/v2/api-reference/workflow-api) — edit the DAG, start runs, and inspect run history.
-   [Chat API](/builder/v2/api-reference/chat-api) — converse with a chat-modality AI Employee.
-   [Triggering AI Employees](/builder/v2/api-reference/triggers) — every way to start a published AI Employee.