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.

All requests on this page require a JWT or tenant API key, 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.

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:

{
  "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).

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.

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.

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:

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}

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.

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

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 — edit the DAG, start runs, and inspect run history.
• Chat API — converse with a chat-modality AI Employee.
• Triggering AI Employees — every way to start a published AI Employee.