API Reference
The Ema platform exposes a REST API so you can do programmatically everything you can do in the AI Employee builder — create and publish AI Employees (AIEs), run their workflows, manage knowledge bases and agents, and hold multi-turn chat conversations. This section documents the builder-facing surface of that API: how to authenticate, and the endpoints for AI Employees, workflows, chat, knowledge and ingestion, evaluation, document generation, and integrations.
One base URL, many services. Behind the scenes the platform is a set of microservices (auth, workflow, agent, chat, and others). You never call them directly. A single gateway — the UI proxy — sits in front of all of them and routes every request by path prefix. You only need to know one host and the /api/v1/... prefixes below.
Base URL
Every API call goes to your tenant's platform host, under the /api/v1 path. Throughout this section, examples use https://your-tenant.ema.co as the host — replace it with the host you use to reach the builder.
https://your-tenant.ema.co/api/v1The gateway matches the path prefix and forwards the request to the right service. The prefix determines which service handles the call:
| Prefix | Service | What it covers |
|---|---|---|
/api/v1/auth | Auth | Sign-in, token refresh, users, tenants, API keys, SSO |
/api/v1/ai-employees | Workflow | AI Employee lifecycle (create, clone, publish, versions) |
/api/v1/workflow | Workflow | Workflow CRUD, runs, run history, HITL, schedules, triggers |
/api/v1/agent | Agent | Agent definitions, agent-type catalog, test execution |
/api/v1/chat | Chat | Conversation sessions, messages, streaming, feedback |
/api/v1/ingestion | Ingestion | Connections, knowledge bases, documents, taxonomies |
/api/v1/integrations | Integrations | Integration catalog, installs, credentials, Tools, MCP servers |
/api/v1/eval | Evaluation | Datasets, rubrics, eval configs, runs, and results |
/api/v1/docgen | Docgen | Documents, versions, generation, export, templates |
A request path is the service prefix plus the path documented for that service. For example, the workflow service documents a "start a run" endpoint at /workflows/{id}/run, so the full URL is:
POST https://your-tenant.ema.co/api/v1/workflow/workflows/{id}/runAI Employee vs. workflow. An AI Employee is a workflow plus its modality, knowledge, and configuration. The two share the same service, so a workflow ID and the ID of the AI Employee that owns it are the same value. The /api/v1/ai-employees prefix is an alias that emits AI-Employee-flavored audit events; the canonical CRUD lives under /api/v1/workflow.
Authentication model
Every endpoint except a small set of public sign-in and health routes requires authentication. The platform accepts two credential types, and a request must carry exactly one of them:
- Bearer JWT — short-lived access token issued when a user signs in. Sent as
Authorization: Bearer <access_token>. This is what the builder UI uses; it stores the token in an HttpOnly cookie that the gateway promotes to a Bearer header on every backend call. - Tenant API key — a long-lived key minted by an administrator for programmatic, machine-to-machine access. Sent as the
X-API-Keyheader.
When a request carries an Authorization header, the platform validates it as a JWT and never falls back to the API key. When there is no Authorization header, it validates the X-API-Key header instead. If neither is present, the request is rejected with 401 Unauthorized.
GET https://your-tenant.ema.co/api/v1/workflow/workflows
X-API-Key: ema_sk_live_2f9c...redactedSee Authentication for how to obtain and use each credential.
Conventions
These conventions hold across every service in this section.
- JSON in, JSON out. Request and response bodies are
application/json, except file uploads (multipart/form-data), file downloads (binary), and streaming (text/event-stream). - IDs are UUIDs. Workflows, runs, sessions, agents, and users are all identified by UUID strings.
- Pagination. List endpoints take
page(1-indexed) andpage_sizequery parameters. The server capspage_sizeat 100. Paginated responses return an envelope withitems,total,page,page_size, and — on most list endpoints —has_more. - Asynchronous runs. Starting a workflow run returns
202 Acceptedwith a run object. The run continues in the background; stream or poll it to follow progress. - Errors. Failures return a JSON body of the shape
{"error": {"code": "...", "message": "..."}}with a matching HTTP status. Common statuses are400(bad request),401(unauthenticated),403(forbidden — authenticated but lacking the capability),404(not found, also used to hide cross-tenant resources),409(conflict), and422(validation failed). - Tenant isolation. Your credential fixes your tenant. You can only read and write resources in that tenant; references to another tenant's resources return
404.
What's next
- Authentication — sign in for a JWT, or create and use a tenant API key.
- AI Employee API — create, configure, clone, publish, and version AI Employees and their agents.
- Workflow API — manage workflow DAGs, start and inspect runs, and respond to human-in-the-loop pauses.
- Chat API — open conversation sessions, send messages, and stream responses.
- Knowledge & Ingestion API — manage connections, knowledge bases, documents, syncs, and taxonomies.
- Evaluation API — score AI Employees and agents against datasets with LLM rubric-based judging.
- Document Generation API — create and version documents, generate content, export, and manage templates.
- Integrations API — browse the catalog, install integrations, store credentials, and execute Tools.
- Triggering AI Employees — the full set of ways to start a run: UI, API, schedule, chat, documents, and external channels.