> Source: https://builder.ema.ai/v2/api-reference
> Title: API Reference

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

> [INFO]
> **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.

```text
https://your-tenant.ema.co/api/v1
```

The 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:

```http
POST https://your-tenant.ema.co/api/v1/workflow/workflows/{id}/run
```

> [TIP]
> **AI 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-Key` header.

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`.

```http
GET https://your-tenant.ema.co/api/v1/workflow/workflows
X-API-Key: ema_sk_live_2f9c...redacted
```

See [Authentication](/builder/v2/api-reference/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) and `page_size` query parameters. The server caps `page_size` at 100. Paginated responses return an envelope with `items`, `total`, `page`, `page_size`, and — on most list endpoints — `has_more`.
-   **Asynchronous runs.** Starting a workflow run returns `202 Accepted` with 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 are `400` (bad request), `401` (unauthenticated), `403` (forbidden — authenticated but lacking the capability), `404` (not found, also used to hide cross-tenant resources), `409` (conflict), and `422` (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](/builder/v2/api-reference/authentication) — sign in for a JWT, or create and use a tenant API key.
-   [AI Employee API](/builder/v2/api-reference/ai-employee-api) — create, configure, clone, publish, and version AI Employees and their agents.
-   [Workflow API](/builder/v2/api-reference/workflow-api) — manage workflow DAGs, start and inspect runs, and respond to human-in-the-loop pauses.
-   [Chat API](/builder/v2/api-reference/chat-api) — open conversation sessions, send messages, and stream responses.
-   [Knowledge & Ingestion API](/builder/v2/api-reference/knowledge-ingestion-api) — manage connections, knowledge bases, documents, syncs, and taxonomies.
-   [Evaluation API](/builder/v2/api-reference/evaluation-api) — score AI Employees and agents against datasets with LLM rubric-based judging.
-   [Document Generation API](/builder/v2/api-reference/document-generation-api) — create and version documents, generate content, export, and manage templates.
-   [Integrations API](/builder/v2/api-reference/integrations-api) — browse the catalog, install integrations, store credentials, and execute Tools.
-   [Triggering AI Employees](/builder/v2/api-reference/triggers) — the full set of ways to start a run: UI, API, schedule, chat, documents, and external channels.