Document Generation API
This page documents the REST API endpoints for creating, retrieving, regenerating, and updating documents produced by AI Employees.
All endpoints are prefixed with /api/document-generation/{ai_employee_id}/.
Before these endpoints will work, make sure the AI Employee is fully set up:
- Its workflow is configured correctly and runs without errors.
- The AI Employee is Enabled (the toggle next to its name in the builder).
- The AI Employee is allowed to be embedded as an agent — open the Permissions tab and switch on Enable this AI Employee as an agent in your workspace.
Create Document
Submit a document generation request.
| Property | Value |
|---|
| URL | /api/document-generation/{ai_employee_id}/documents |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
instructions | string | Yes | Free-form natural-language instructions for the document generator (topic, audience, data sources, formatting hints, etc.) |
Example
curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Q4 2025 Sales Summary covering 2025-10-01 through 2025-12-31, sourced from Salesforce. Audience: executive team."
}'
Response
| Field | Type | Description |
|---|
document_id | string | UUID of the created document |
project_id | string | UUID of the parent document project (required by Retrieve Document and Regenerate Document) |
status | string | Initial status (typically TRIGGERED) |
Retrieve Document
Retrieve the current status and content of a document. Use this endpoint to poll for completion.
| Property | Value |
|---|
| URL | /api/document-generation/{ai_employee_id}/documents/retrieve |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
document_id | string | Yes | UUID of the document |
project_id | string | Yes | UUID of the parent document project (returned by Create Document) |
Example
curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/retrieve \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"document_id": "<document-uuid>",
"project_id": "<project-uuid>"
}'
Response
| Field | Type | Description |
|---|
document_id | string | UUID of the document |
project_id | string | UUID of the parent document project |
status | string | Current status (TRIGGERED, PROCESSING, COMPLETED, FAILED) |
content | string | Generated document content (when COMPLETED) |
error_message | string | Error message (when FAILED) |
Polling Pattern
# Poll every 5 seconds until status is COMPLETED or FAILED
while true; do
RESPONSE=$(curl -s -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/retrieve \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"document_id": "<document-uuid>", "project_id": "<project-uuid>"}')
STATUS=$(echo $RESPONSE | jq -r '.status')
if [ "$STATUS" = "COMPLETED" ] || [ "$STATUS" = "FAILED" ]; then
echo $RESPONSE | jq .
break
fi
echo "Status: $STATUS. Waiting..."
sleep 5
done
Regenerate Document (Preview)
Regenerate a document without replacing the original. This creates a preview that can be reviewed before finalizing.
| Property | Value |
|---|
| URL | /api/document-generation/{ai_employee_id}/documents/regenerate |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
document_id | string | Yes | UUID of the original document |
project_id | string | Yes | UUID of the parent document project |
selection | string | Yes | The portion of the document the user has selected for regeneration |
query | string | Yes | Natural-language instruction describing what to change in the selection |
selected_html | string | No | Original HTML of the selection (used to preserve surrounding formatting) |
user_specified_source_names | array | No | Limit regeneration to citations from these sources |
Example
curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/regenerate \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"document_id": "<document-uuid>",
"project_id": "<project-uuid>",
"selection": "Revenue rose 12% year-over-year.",
"query": "Rewrite to highlight the contribution from enterprise accounts and add a Q1 forecast."
}'
Response
| Field | Type | Description |
|---|
regenerated_document | string | The regenerated HTML for the selection |
show_work | array | List of ShowWorkEntry objects describing the steps the generator took |
Update Document
Finalize changes to a document (e.g., after reviewing a preview).
| Property | Value |
|---|
| URL | /api/document-generation/{ai_employee_id}/documents/update |
| HTTP Method | POST |
| Protocol | REST (HTTP/JSON) |
| Header | Type | Required | Description |
|---|
Authorization | string | Yes | Bearer token |
Content-Type | string | Yes | application/json |
Request Body
| Field | Type | Required | Description |
|---|
document_id | string | Yes | UUID of the document to update |
content | string | No | Updated content |
metadata | object | No | Updated metadata |
Example
curl -X POST https://your-instance.ema.co/api/document-generation/<ai_employee_id>/documents/update \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"document_id": "<document-uuid>",
"content": "Updated document content here..."
}'
Document Status Values
| Status | Description |
|---|
TRIGGERED | Request accepted, queued for processing |
PROCESSING | AI Employee is generating the document |
COMPLETED | Document generated successfully |
FAILED | Generation failed (check error field for details) |