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.

Request Fields:

For detailed instructions on encoding and sending gRPC-Web requests, see Handling gRPC-Web Requests.

Response Fields:

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.

Headers

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:

{
 "access_token": "eyJhbGciOiJSUzI1NiIs..."
}

• 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>

See 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

curl -X POST https://your-instance.ema.co/api/tenant \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "tenant": {
 "domain": "acme",
 "company_name": "Acme Corp",
 "email": "[email protected]"
 },
 "user_name": "Admin User",
 "user_email": "[email protected]",
 "user_create_api_key": true
 }'

Request Fields:

Response: { tenant: Tenant, api_keys: ApiKeyInfo[] } — the created Tenant plus any API keys generated for the seeded users.

gRPC-Web Alternative

The tenant creation endpoint is also available via gRPC-Web at /tenant.v1.TenantService/CreateTenant. See 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.

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",
 "template_id": "<template-uuid>"
 }'

Either template_id or source_persona_id is required — the new AI Employee is cloned from that template/persona. Optional fields: proto_config, welcome_messages, trigger_type, clone_data. See AI Employee API for the full schema.

See 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

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>"
 }'

Send a Message

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

curl -X POST https://your-instance.ema.co/api/dashboards/v1/upload-and-run-rows \
 -H "Authorization: Bearer <access_token>" \
 -F "[email protected]"

Get Row Results

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

See Dashboard HTTP API and Dashboard RPC Calls for all dashboard operations.

Quickstart Summary

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

Next Steps

• Authentication -- Detailed token lifecycle and key types
• AI Employee Overview -- Understand AI Employee architecture
• Workflow Overview -- Learn how workflows power AI Employee behavior
• Handling gRPC-Web Requests -- Guide for making gRPC-Web calls