Dashboard HTTP API

This page documents the REST HTTP endpoints for dashboard operations. All endpoints are prefixed with /api/dashboards/v1/ and identify the AI Employee via a persona_id parameter (passed in the query string for GET requests and in the JSON body for POST/DELETE requests).

All endpoints support an optional callback_url parameter. When provided, Ema sends the result to the callback URL upon completion instead of requiring polling.

Upload and Run Rows

Create a row from one or more input documents and trigger workflow processing on it.

Property	Value
URL	`/api/dashboards/v1/upload-and-run-rows`
HTTP Method	POST
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`inputs`	array	Yes	Array of `Input` objects supplying the row's input values
`callback_url`	string	No	URL to receive results upon completion
`expire_after_seconds`	integer	No	Time-to-live for the row, in seconds

Each Input object has the shape:

Field	Type	Description
`name`	string	The input column name
`string_value`	string	String value (use exactly one of `string_value` / `number_value` / `boolean_value` / `document_value`)
`number_value`	number	Numeric value
`boolean_value`	boolean	Boolean value
`document_value`	array	Array of `FileInfo` objects (`name`, `contents`, `is_base64_encoded`, `mime_type`)

Example

curl -X POST https://your-instance.ema.co/api/dashboards/v1/upload-and-run-rows \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona_id>",
 "inputs": [
 {
 "name": "source_document",
 "document_value": [
 {
 "name": "data.xlsx",
 "contents": "<base64-encoded-file-contents>",
 "is_base64_encoded": true,
 "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 }
 ]
 }
 ],
 "callback_url": "https://your-server.com/webhook"
 }'

Response

Field	Type	Description
`row_id`	string	UUID of the created row

Get Row Result

Retrieve the result of a single processed row.

Property	Value
URL	`/api/dashboards/v1/get-row-result`
HTTP Method	GET
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token

Query Parameters

Parameter	Type	Required	Description
`row_id`	string	Yes	UUID of the row
`persona_id`	string	Yes	UUID of the AI Employee
`include_file_contents`	boolean	No	When `true`, includes inline file contents for document columns

Example

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

Response

Field	Type	Description
`row`	object	The dashboard row, serialized as JSON (includes the row's state and all column values)
`additional_column_details`	array	Per-column extras computed by the service. Each entry: `column_name`, `documents` (array of `FileInfo`), `ema_ui_url`.

Get All Row Results

Retrieve results for all rows in the dashboard.

Property	Value
URL	`/api/dashboards/v1/get-all-row-results`
HTTP Method	GET
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token

Query Parameters

Parameter	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`include_file_contents`	boolean	No	When `true`, includes inline file contents for document columns

Example

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

Response

Field	Type	Description
`rows`	array	Array of row result objects, each with the same shape as Get Row Result's response (`row` + `additional_column_details`).

Add Row

Create an empty row in the dashboard. To populate values for the row, follow this with Update Row; to trigger workflow processing on it, use Trigger Row.

Property	Value
URL	`/api/dashboards/v1/add-row`
HTTP Method	POST
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`expire_after_seconds`	integer	No	Time-to-live for the row, in seconds

Example

curl -X POST https://your-instance.ema.co/api/dashboards/v1/add-row \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona_id>"
 }'

Response

Field	Type	Description
`row_id`	string	UUID of the new row

Update Row

Update the input values of an existing row.

Property	Value
URL	`/api/dashboards/v1/update-row`
HTTP Method	POST
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`row_id`	string	Yes	UUID of the row to update
`inputs`	array	Yes	Array of `Input` objects (see Upload and Run Rows for the `Input` shape)

Example

curl -X POST https://your-instance.ema.co/api/dashboards/v1/update-row \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona_id>",
 "row_id": "<row-uuid>",
 "inputs": [
 { "name": "company_name", "string_value": "Acme Corporation" }
 ]
 }'

Response

Field	Type	Description
`success`	boolean	`true` if the row was updated

Delete Rows

Delete one or more rows from the dashboard.

Property	Value
URL	`/api/dashboards/v1/delete-rows`
HTTP Method	DELETE
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`row_ids`	array	Yes	List of row UUIDs to delete

Example

curl -X DELETE https://your-instance.ema.co/api/dashboards/v1/delete-rows \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona_id>",
 "row_ids": ["<row-uuid-1>", "<row-uuid-2>"]
 }'

Response

Field	Type	Description
`success`	boolean	`true` if the rows were deleted

Trigger Row

Trigger workflow processing for a specific row.

Property	Value
URL	`/api/dashboards/v1/trigger-row`
HTTP Method	POST
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`row_id`	string	Yes	UUID of the row to trigger
`callback_url`	string	No	URL to receive results

Example

curl -X POST https://your-instance.ema.co/api/dashboards/v1/trigger-row \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona_id>",
 "row_id": "<row-uuid>",
 "callback_url": "https://your-server.com/webhook"
 }'

Response

Field	Type	Description
`success`	boolean	`true` if the row was queued for processing

Get Continuation Message

Retrieve the HITL continuation message for a paused row.

Property	Value
URL	`/api/dashboards/v1/get-continuation-message`
HTTP Method	GET
Protocol	REST (HTTP/JSON)

Query Parameters

Parameter	Type	Required	Description
`row_id`	string	Yes	UUID of the paused row
`persona_id`	string	Yes	UUID of the AI Employee

Example

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

Response

Field	Type	Description
`continuation_message`	object	The HITL prompt (form, buttons, or text) the workflow is waiting on
`row_state`	string	Current state of the row

Continue Row

Submit a HITL response to resume a paused workflow.

Property	Value
URL	`/api/dashboards/v1/continue-row`
HTTP Method	POST
Protocol	REST (HTTP/JSON)

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token
`Content-Type`	string	Yes	`application/json`

Request Body

Field	Type	Required	Description
`persona_id`	string	Yes	UUID of the AI Employee
`row_id`	string	Yes	UUID of the paused row
`continuation_message`	object	Yes	The user's response to the HITL prompt (shape mirrors the prompt returned by Get Continuation Message)

Example

curl -X POST https://your-instance.ema.co/api/dashboards/v1/continue-row \
 -H "Authorization: Bearer <access_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "persona_id": "<persona_id>",
 "row_id": "<row-uuid>",
 "continuation_message": {
 "approved": true,
 "comment": "Looks good, proceed."
 }
 }'

Response

Field	Type	Description
`success`	boolean	`true` if the row resumed processing

Dashboard Overview -- Concepts and architecture
Dashboard Data Model -- Row, column, and schema structures
Dashboard RPC Calls -- gRPC-Web endpoints for dashboard operations

Dashboard HTTP API

Upload and Run Rows

Headers

Request Body

Example

Response

Get Row Result

Headers

Query Parameters

Example

Response

Get All Row Results

Headers

Query Parameters

Example

Response

Add Row

Headers

Request Body

Example

Response

Update Row

Headers

Request Body

Example

Response

Delete Rows

Headers

Request Body

Example

Response

Trigger Row

Headers

Request Body

Example

Response

Get Continuation Message

Query Parameters

Example

Response

Continue Row

Headers

Request Body

Example

Response

Related