> Source: https://builder-docs.ema.ai/api-reference/getting-started
> Title: API Getting Started

# API Getting Started

This guide walks you through the essential steps to begin using Ema's Builder Platform APIs: authenticating, creating a tenant, setting up an AI Employee, interacting via chat, and running dashboard workflows.

Ema provides two API paths: a **REST (HTTP/JSON) quickstart** for the most common operations, and a **gRPC-Web path** for advanced or lower-level endpoints. This guide covers the REST path first, with links to gRPC-Web alternatives where applicable.

## Prerequisites

-   Access to an Ema instance (e.g., `https://your-instance.ema.co`)
-   A valid API key (generated from the Ema UI or via the `GenerateApiKey` gRPC-Web endpoint)
-   `curl` or an HTTP client for making API requests

## Step 1: Generate an API Key

Create an API key by calling the `GenerateApiKey` gRPC-Web endpoint. This key is tied to a specific user and tenant.

> [INFO]
> **Note:** If this is your first time setting up the API and you do not yet have an access token, see [Access Token for Root Tenant API Key](/legacy-docs/api-reference/misc/root-tenant-token) for how to obtain one from your browser session.

Property

Value

URL

`/auth.v1.AuthService/GenerateApiKey`

HTTP Method

POST

Protocol

gRPC-Web over HTTP

**Request Fields:**

Field

Type

Required

Description

`email`

string

Yes

Email address of the user to create the key for

For detailed instructions on encoding and sending gRPC-Web requests, see [Handling gRPC-Web Requests](/legacy-docs/api-reference/misc/grpc-web).

**Response Fields:**

Field

Type

Description

`api_key`

string

The generated API key

## Step 2: Generate an Access Token

Exchange your API key for a short-lived access token (JWT). Pass your API key in the `x-ema-api-key` header.

Property

Value

URL

`/api/auth/generate_access_token`

HTTP Method

POST

Protocol

REST (HTTP/JSON)

### Headers

Header

Type

Required

Description

`x-ema-api-key`

string

Yes

Your Ema API key

`Content-Type`

string

Yes

`application/json`

```bash
curl -X POST https://your-instance.ema.co/api/auth/generate_access_token \
 -H "x-ema-api-key: your-api-key" \
 -H "Content-Type: application/json"
```

**Response:**

```json
{
 "access_token": "eyJhbGciOiJSUzI1NiIs...",
 "token_type": "bearer"
}
```

-   **Global API key tokens** expire after 24 hours.
-   **Chatbot API key tokens** expire after 30 minutes.

Use the access token in the `Authorization` header for all subsequent requests:

```
Authorization: Bearer <access_token>
```

> [INFO]
> **Legacy endpoint:** The older `/api/generate_access_token` endpoint (which accepts the API key in the JSON body) is still supported but deprecated. Use `/api/auth/generate_access_token` with the `x-ema-api-key` header for all new integrations.

See [Authentication](/legacy-docs/api-reference/authentication) for complete details on token types and lifecycle.

## Step 3: Create a Tenant

Create a child tenant under your organization. Tenants form a hierarchy where child tenants inherit configurations from their parent.

### REST Endpoint

Property

Value

URL

`/api/tenant`

HTTP Method

POST

Protocol

REST (HTTP/JSON)

```bash
curl -X POST https://your-instance.ema.co/api/tenant \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "tenant_name": "Acme Corp",
 "parent_id": "<parent-tenant-uuid>",
 "admin_email": "admin@acme.com"
 }'
```

**Request Fields:**

Field

Type

Required

Description

`tenant_name`

string

Yes

Display name for the tenant

`parent_id`

string

Yes

UUID of the parent tenant

`admin_email`

string

Yes

Email of the tenant admin

### gRPC-Web Alternative

The tenant creation endpoint is also available via gRPC-Web at `/tenant.v1.TenantService/CreateTenant`. See [Tenant Management](/legacy-docs/api-reference/tenant-management) for full gRPC-Web details and additional tenant operations.

## Step 4: Create an AI Employee

Create an AI Employee using the REST API.

Property

Value

URL

`/api/ai_employee/create_ai_employee`

HTTP Method

POST

Protocol

REST (HTTP/JSON)

```bash
curl -X POST https://your-instance.ema.co/api/ai_employee/create_ai_employee \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "Customer Support Agent",
 "description": "Handles customer support queries",
 "category": "CUSTOMER_SUPPORT",
 "behavior_type": "CHAT",
 "icon": "support-icon",
 "proto_config": {
 "widgets": [],
 "display_settings": {},
 "project_settings": {}
 }
 }'
```

> [INFO]
> **Legacy endpoint:** The older `/api/personas/create_persona` endpoint is still supported. The new `/api/ai_employee/create_ai_employee` endpoint is preferred for all new integrations.

See [AI Employee API](/legacy-docs/api-reference/ai-employees/ai-employee-api) for full endpoint details including update, delete, and list operations.

## Step 5: Start a Chat Conversation

Create a conversation and send messages to your AI Employee.

### Create a Conversation

Property

Value

URL

`/api/{tenantId}/chat/`

HTTP Method

POST

Protocol

REST (HTTP/JSON)

```bash
curl -X POST https://your-instance.ema.co/api/<tenant_id>/chat/ \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona-uuid>"
 }'
```

> [INFO]
> **Note:** The chat endpoint now includes the tenant ID in the path (`/api/{tenantId}/chat/`). The older `/api/chat/` endpoint without the tenant prefix is still supported for backward compatibility.

### Send a Message

```bash
curl -X POST https://your-instance.ema.co/api/<tenant_id>/chat/<conversation_id> \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "message": "How do I reset my password?"
 }'
```

See [Chat API](/legacy-docs/api-reference/chat/chat-api) for the full conversation lifecycle, including asynchronous messaging and feedback collection.

## Step 6: Interact with a Dashboard

Upload data rows and trigger workflow processing through the dashboard HTTP API.

### Upload and Run Rows

```bash
curl -X POST https://your-instance.ema.co/api/personas/<persona_id>/dashboard/upload-and-run-rows \
 -H "Authorization: Bearer <access_token>" \
 -F "file=@data.xlsx"
```

### Get Row Results

```bash
curl -X GET "https://your-instance.ema.co/api/personas/<persona_id>/dashboard/get-row-result?row_id=<row_id>" \
 -H "Authorization: Bearer <access_token>"
```

See [Dashboard HTTP API](/legacy-docs/api-reference/dashboard/http-api) and [Dashboard RPC Calls](/legacy-docs/api-reference/dashboard/rpc-calls) for all dashboard operations.

## Quickstart Summary

The table below summarizes the REST endpoints used in this guide:

Step

Endpoint

Method

Generate Access Token

`/api/auth/generate_access_token`

POST

Create Tenant

`/api/tenant`

POST

Create AI Employee

`/api/ai_employee/create_ai_employee`

POST

Create Chat Conversation

`/api/{tenantId}/chat/`

POST

Send Chat Message

`/api/{tenantId}/chat/{conversationId}`

POST

Upload Dashboard Rows

`/api/personas/{persona_id}/dashboard/upload-and-run-rows`

POST

Get Dashboard Row Result

`/api/personas/{persona_id}/dashboard/get-row-result`

GET

## Next Steps

-   [Authentication](/legacy-docs/api-reference/authentication) -- Detailed token lifecycle and key types
-   [AI Employee Overview](/legacy-docs/api-reference/ai-employees/overview) -- Understand AI Employee architecture
-   [Workflow Overview](/legacy-docs/api-reference/workflows/overview) -- Learn how workflows power AI Employee behavior
-   [Handling gRPC-Web Requests](/legacy-docs/api-reference/misc/grpc-web) -- Guide for making gRPC-Web calls