# DocMiral API Documentation DocMiral is a document generation platform that lets you create, manage, and export professional documents from reusable HTML/Tailwind CSS templates. This reference covers all available REST API endpoints. --- ## Base URL ``` https://api.docmiral.com/api ``` ## Authentication All requests require a Bearer token in the `Authorization` header. ``` Authorization: Bearer YOUR_API_KEY ``` ## Response Format All endpoints return a consistent JSON envelope: ```json { "status": 1, "data": { ... } } ``` List endpoints wrap results in a `num` + `list` structure: ```json { "status": 1, "data": { "num": 3, "list": [ ... ] } } ``` Build endpoints return a pre-signed URL to download the generated file: ```json { "status": 1, "data": { "url": "https://storage.docmiral.com/builds/...", "documentId": "a1b2c3d4e5f6a1b2c3d4e5f6" } } ``` --- ## Documents Documents are instances of a template populated with real data. They can be exported to PDF, PPTX, or image. --- ### List Documents ``` GET /entities ``` **Query Parameters** | Parameter | Type | Default | Description | |-----------|---------|---------|---------------------------| | limit | integer | 50 | Maximum number of results | | offset | integer | 0 | Number of results to skip | **Example Request** ```bash curl -X GET "https://api.docmiral.com/api/entities?limit=20&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "num": 2, "list": [ { "id": "a1b2c3d4e5f6a1b2c3d4e5f6", "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "categoryId": "c3d4e5f6c3d4e5f6c3d4e5f6", "category": "Finance", "template": "Invoice Template", "status": 1, "data": { "settings": { "size": "A4", "margin": "1in", "padding": "0", "background": "#FFFFFF", "color": "#000000", "fontSize": "12pt", "orientation": "portrait" }, "clientName": "Acme Corp", "amount": "1500.00" }, "messages": [], "e_sign_requests": [], "created_at": "2024-01-15T10:00:00.000Z" } ] } } ``` --- ### Get a Document ``` GET /entities/{id} ``` **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|-------------| | id | string | Yes | Document ID (MongoDB ObjectId) | **Example Request** ```bash curl -X GET "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "id": "a1b2c3d4e5f6a1b2c3d4e5f6", "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "categoryId": "c3d4e5f6c3d4e5f6c3d4e5f6", "category": "Finance", "template": "Invoice Template", "status": 1, "is_read_only": false, "read_only_reason": null, "data": { "settings": { "size": "A4", "margin": "1in", "padding": "0", "background": "#FFFFFF", "color": "#000000", "fontSize": "12pt", "orientation": "portrait", "fonts": ["Inter"], "pageWidth": null, "pageHeight": null }, "clientName": "Acme Corp", "amount": "1500.00", "dueDate": "2024-02-15" }, "messages": [], "e_sign_requests": [], "template_custom_fields": [], "created_at": "2024-01-15T10:00:00.000Z" } } ``` --- ### Create a Document ``` POST /entities/ ``` Creates a new document from a template. Field data and layout settings are nested inside the `data` object. Set `init` to `true` to create an empty document without any data. **Request Body** | Field | Type | Required | Description | |------------|---------|----------|---------------------------------------------------------------| | templateId | string | Yes | ID of the template to create the document from | | name | string | No | Optional name for the document | | init | boolean | No | `true` to create an empty document. Ignores `data` if set. | | data | object | No | Template field values. See data object below. | **The `data` object** | Field | Type | Description | |--------------------|--------|---------------------------------------------------| | data.settings | object | Layout overrides (see Settings object) | | data.\<fieldName\> | any | Template variable values — keys must match the template's variable names | **Settings object** | Field | Type | Example | Description | |-------------|--------|--------------|---------------------------------------| | size | string | `A4` | Page size (A4, Letter, Legal, etc.) | | background | string | `#FFFFFF` | Background color (CSS value) | | color | string | `#000000` | Text color (CSS value) | | margin | string | `1in` | Page margin | | padding | string | `0` | Page padding | | fontSize | string | `12pt` | Base font size | | orientation | string | `portrait` | Page orientation | | fonts | array | `["Inter"]` | Font family names to load | | pageWidth | string | `210mm` | Custom page width (overrides size) | | pageHeight | string | `297mm` | Custom page height (overrides size) | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/entities/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "name": "Invoice #1043", "data": { "settings": { "size": "A4", "margin": "1in" }, "clientName": "Bob Jones", "amount": "850.00", "dueDate": "2024-04-01" } }' ``` **Example Response** ```json { "status": 1, "data": { "id": "f6a1f6a1f6a1f6a1f6a1f6a1" } } ``` --- ### Update a Document ``` PUT /entities/{id} ``` Updates the field data of an existing document. Only the fields you provide are changed. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Document ID (MongoDB ObjectId) | **Request Body** | Field | Type | Description | |-------|--------|------------------------------------------------| | data | object | Fields to update (same structure as on create) | **Example Request** ```bash curl -X PUT "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "data": { "clientName": "Bob Jones Jr.", "amount": "900.00" } }' ``` --- ### Delete a Document ``` DELETE /entities/{id} ``` **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Document ID (MongoDB ObjectId) | **Example Request** ```bash curl -X DELETE "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "documentId": "a1b2c3d4e5f6a1b2c3d4e5f6", "deleted": true } } ``` --- ### Clone a Document ``` POST /entities/{id}/clone ``` Creates an identical copy of an existing document. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------------| | id | string | Yes | ID of document to clone | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6/clone" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "id": "e5f6e5f6e5f6e5f6e5f6e5f6", "name": "Invoice #1042 (Copy)", "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "data": { "clientName": "Acme Corp", "amount": "1500.00" }, "created_at": "2024-01-16T09:00:00.000Z" } } ``` --- ### Build Document as PDF ``` POST /entities/{id}/build/pdf ``` Renders the document and returns a pre-signed URL to download the generated PDF. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Document ID (MongoDB ObjectId) | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6/build/pdf" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "url": "https://storage.docmiral.com/builds/a1b2c3d4e5f6a1b2c3d4e5f6.pdf?token=presigned", "documentId": "a1b2c3d4e5f6a1b2c3d4e5f6" } } ``` --- ### Build Document as PPTX ``` POST /entities/{id}/build/pptx ``` Renders the document and returns a pre-signed URL to download the generated PowerPoint file. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Document ID (MongoDB ObjectId) | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6/build/pptx" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "url": "https://storage.docmiral.com/builds/a1b2c3d4e5f6a1b2c3d4e5f6.pptx?token=presigned", "documentId": "a1b2c3d4e5f6a1b2c3d4e5f6" } } ``` --- ### Build Document Page as Image ``` POST /entities/{id}/build/image ``` Renders a single page of the document as a PNG image and returns a pre-signed download URL. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Document ID (MongoDB ObjectId) | **Request Body** | Field | Type | Default | Description | |-------|---------|---------|-------------------------------| | page | integer | 1 | 1-based page number to render | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/entities/a1b2c3d4e5f6a1b2c3d4e5f6/build/image" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "page": 1 }' ``` **Example Response** ```json { "status": 1, "data": { "url": "https://storage.docmiral.com/builds/a1b2c3d4e5f6a1b2c3d4e5f6-p1.png?token=presigned", "documentId": "a1b2c3d4e5f6a1b2c3d4e5f6", "page": 1 } } ``` --- ## Templates Templates are reusable HTML documents styled with Tailwind CSS. They define the layout and the variable fields that documents are populated with. --- ### List Templates ``` GET /templates ``` **Query Parameters** | Parameter | Type | Default | Description | |------------|---------|---------|-----------------------------------------------------| | limit | integer | 50 | Maximum number of results | | offset | integer | 0 | Number of results to skip | | categoryId | string | — | Filter by category ID | | mylist | boolean | false | When `true`, returns only templates you own | **Example Request** ```bash curl -X GET "https://api.docmiral.com/api/templates?limit=10&mylist=true" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "num": 1, "list": [ { "id": "b2c3d4e5f6b2c3d4e5f6b2c3", "name": "Invoice Template", "categoryId": "c3d4e5f6c3d4e5f6c3d4e5f6", "category": "Finance", "status": "published", "author": "Jane Doe", "description": "A clean invoice template with itemized billing.", "version": "1.0", "tags": ["invoice", "finance"], "settings": { "size": "A4", "orientation": "portrait", "margin": "1in", "padding": "0", "background": "#FFFFFF", "color": "#000000", "fontSize": "12pt" }, "html_content": "

...

", "header_content": null, "footer_content": null, "thumb_url": "https://storage.docmiral.com/thumbs/7a1b2c3d.png", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-10T00:00:00.000Z" } ] } } ``` --- ### Get a Template ``` GET /templates/{id} ``` **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Template ID (MongoDB ObjectId) | **Example Request** ```bash curl -X GET "https://api.docmiral.com/api/templates/b2c3d4e5f6b2c3d4e5f6b2c3" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "id": "b2c3d4e5f6b2c3d4e5f6b2c3", "name": "Invoice Template", "categoryId": "c3d4e5f6c3d4e5f6c3d4e5f6", "category": "Finance", "status": "published", "author": "Jane Doe", "description": "A clean invoice template with itemized billing.", "version": "1.0", "tags": ["invoice", "finance"], "settings": { "size": "A4", "orientation": "portrait", "margin": "1in", "padding": "0", "background": "#FFFFFF", "color": "#000000", "fontSize": "12pt" }, "html_content": "

", "header_content": null, "footer_content": null, "is_owner": true, "messages": [], "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-10T00:00:00.000Z" } } ``` --- ### Create a Template ``` POST /templates/ ``` **Request Body** | Field | Type | Description | |------------|--------|-------------------------------------------------------------------| | name | string | Template name. Pass `"suggest"` to auto-generate a name. | | categoryId | string | ID of the category to assign this template to | | html | string | Initial HTML content (supports Tailwind CSS classes) | | settings | object | Layout settings (see Settings object under Create a Document) | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/templates/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Monthly Report", "html": "

", "settings": { "size": "A4", "margin": "1in" } }' ``` **Example Response** ```json { "status": 1, "data": { "id": "a2b3a2b3a2b3a2b3a2b3a2b3", "name": "Monthly Report", "categoryId": null, "status": "draft", "settings": { "size": "A4", "margin": "1in" }, "html_content": "

", "header_content": null, "footer_content": null, "created_at": "2024-01-15T10:00:00.000Z", "updated_at": "2024-01-15T10:00:00.000Z" } } ``` --- ### Update a Template ``` PUT /templates/{id} ``` **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Template ID (MongoDB ObjectId) | **Request Body** | Field | Type | Description | |----------------|--------|-------------------------------------------| | name | string | New template name | | html | string | New HTML body content | | header_content | string | HTML content for the page header | | footer_content | string | HTML content for the page footer | | settings | object | Layout settings overrides | **Example Request** ```bash curl -X PUT "https://api.docmiral.com/api/templates/b2c3d4e5f6b2c3d4e5f6b2c3" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Invoice Template v2", "settings": { "fontSize": "13pt" } }' ``` **Example Response** ```json { "status": 1, "data": { "id": "b2c3d4e5f6b2c3d4e5f6b2c3", "name": "Invoice Template v2", "categoryId": "c3d4e5f6c3d4e5f6c3d4e5f6", "settings": { "size": "A4", "fontSize": "13pt" }, "html_content": "

...

", "updated_at": "2024-01-16T12:00:00.000Z" } } ``` --- ### Delete a Template ``` DELETE /templates/{id} ``` **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Template ID (MongoDB ObjectId) | **Example Request** ```bash curl -X DELETE "https://api.docmiral.com/api/templates/b2c3d4e5f6b2c3d4e5f6b2c3" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "deleted": true } } ``` --- ### Clone a Template ``` POST /templates/{id}/clone ``` **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|---------------------------| | id | string | Yes | ID of template to clone | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/templates/b2c3d4e5f6b2c3d4e5f6b2c3/clone" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "id": "b3c4b3c4b3c4b3c4b3c4b3c4", "name": "Invoice Template (Copy)", "categoryId": "c3d4e5f6c3d4e5f6c3d4e5f6", "created_at": "2024-01-16T09:00:00.000Z" } } ``` --- ### Build Template as PDF ``` POST /templates/{id}/build/pdf ``` Renders the template with default/empty field values and returns a pre-signed URL to the PDF. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Template ID (MongoDB ObjectId) | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/templates/b2c3d4e5f6b2c3d4e5f6b2c3/build/pdf" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "url": "https://storage.docmiral.com/builds/b2c3d4e5f6b2c3d4e5f6b2c3.pdf?token=presigned", "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3" } } ``` --- ### Build Template Pages as Images ``` POST /templates/{id}/build/image ``` Renders every page of the template as PNG images. Returns a list of pre-signed URLs, one per page. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Template ID (MongoDB ObjectId) | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/templates/b2c3d4e5f6b2c3d4e5f6b2c3/build/image" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": { "list": [ "https://storage.docmiral.com/builds/b2c3d4e5f6b2c3d4e5f6b2c3-p1.png?token=presigned", "https://storage.docmiral.com/builds/b2c3d4e5f6b2c3d4e5f6b2c3-p2.png?token=presigned" ] } } ``` --- ### Get Template Schema ``` GET /templates/schema/{id} ``` Returns the variable schema for a template so you know exactly which fields to populate when creating a document. See the [AI Model Integration](#ai-model-integration) section for how to use this endpoint with LLMs. **Path Parameters** | Parameter | Type | Required | Description | |-----------|--------|----------|--------------------| | id | string | Yes | Template ID (MongoDB ObjectId) | **Query Parameters** | Parameter | Type | Required | Values | Description | |--------------|---------|----------|---------------------------------------------|---------------------------------------------------| | schemaFormat | string | Yes | `standard`, `jsonSchema`, `aimodel_openai` | Format of the returned schema | | output | string | Yes | `schema`, `sample` | Return the schema definition or a sample object | | defaultValue | boolean | No | `true`, `false` | When `output=sample`, include default values | **Example Request** ```bash curl -X GET "https://api.docmiral.com/api/templates/schema/b2c3d4e5f6b2c3d4e5f6b2c3?schemaFormat=jsonSchema&output=schema" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** (`schemaFormat=jsonSchema`) ```json { "status": 1, "data": { "result": { "type": "object", "properties": { "clientName": { "type": "string", "description": "Name of the client" }, "amount": { "type": "string", "description": "Total invoice amount" }, "dueDate": { "type": "string", "description": "Payment due date" } }, "required": ["clientName", "amount"], "additionalProperties": false } } } ``` **Example Response** (`schemaFormat=aimodel_openai`) ```json { "status": 1, "data": { "result": { "name": "fill_document", "description": "Fill the document fields with structured data", "parameters": { "type": "object", "properties": { "clientName": { "type": "string", "description": "Name of the client" }, "amount": { "type": "string", "description": "Total invoice amount" }, "dueDate": { "type": "string", "description": "Payment due date" } }, "required": ["clientName", "amount"] } } } } ``` --- ## Categories Categories let you organize templates into groups. --- ### List Categories ``` GET /categories ``` **Example Request** ```bash curl -X GET "https://api.docmiral.com/api/categories" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Example Response** ```json { "status": 1, "data": [ { "id": "c3d4e5f6c3d4e5f6c3d4e5f6", "name": "Finance & Invoicing" }, { "id": "d4e5f6d4e5f6d4e5f6d4e5f6", "name": "HR & Recruitment" } ] } ``` --- ## TARS AI TARS is the AI layer of DocMiral. It enables natural-language document filling, CV parsing, text extraction, and AI-powered document cloning. --- ### Fill Document with AI (Chat) ``` POST /tars/chat-layerer ``` Uses natural language to fill the fields of an existing document. Describe the data in plain English and TARS maps it to the correct template fields automatically. **Request Body** | Field | Type | Required | Description | |-----------|--------|----------|-----------------------------------------------------| | entity_id | string | Yes | ID of the document to fill | | message | string | Yes | Natural language description of the data to fill in | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/tars/chat-layerer" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "entity_id": "a1b2c3d4e5f6a1b2c3d4e5f6", "message": "Name is Alice Smith, she works at Google as a Senior Engineer. Salary is $120,000." }' ``` **Example Response** ```json { "status": 1, "data": { "id": "a1b2c3d4e5f6a1b2c3d4e5f6", "data": { "name": "Alice Smith", "company": "Google", "role": "Senior Engineer", "salary": "$120,000" }, "updatedAt": "2024-01-15T11:00:00.000Z" } } ``` --- ### Parse a CV or Resume ``` POST /tars/parse-cv ``` Extracts structured data from a CV or resume file. Upload the file as `multipart/form-data`. **Request Body (multipart/form-data)** | Field | Type | Required | Description | |-------|------|----------|----------------------------------------| | file | file | Yes | The CV or resume file (PDF recommended)| **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/tars/parse-cv" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@/path/to/resume.pdf" ``` **Example Response** ```json { "status": 1, "data": { "name": "Alice Smith", "email": "alice@example.com", "phone": "+1 555 000 1234", "summary": "Experienced software engineer with 4 years at Google.", "skills": ["JavaScript", "React", "Node.js"], "experience": [ { "company": "Google", "role": "Software Engineer", "from": "2020-01", "to": "2024-01" } ], "education": [ { "institution": "MIT", "degree": "B.Sc. Computer Science", "year": 2019 } ] } } ``` --- ### Extract Text from a File ``` POST /tars/extract-text ``` Uploads any document file and returns the raw extracted plain text. **Request Body (multipart/form-data)** | Field | Type | Required | Description | |-------|------|----------|-------------------------------| | file | file | Yes | The file to extract text from | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/tars/extract-text" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@/path/to/document.pdf" ``` **Example Response** ```json { "status": 1, "data": { "text": "INVOICE\n\nClient: Acme Corp\nDate: January 15, 2024\nAmount Due: $1,500.00\n\nThank you for your business." } } ``` --- ### Smart Clone a Document with AI ``` POST /tars/smartclone ``` Clones an existing document and uses AI to transform its content based on a natural language instruction. **Request Body** | Field | Type | Required | Description | |-----------|--------|----------|---------------------------------------------------------------------| | entity_id | string | Yes | ID of the document to clone | | message | string | Yes | Natural language instruction describing how to transform the clone | | category | string | No | ID of the category to assign the cloned document to | **Example Request** ```bash curl -X POST "https://api.docmiral.com/api/tars/smartclone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "entity_id": "a1b2c3d4e5f6a1b2c3d4e5f6", "message": "Change the candidate name to Bob Jones and update the company to Microsoft", "category": "d4e5f6d4e5f6d4e5f6d4e5f6" }' ``` **Example Response** ```json { "status": 1, "data": { "id": "c4d5c4d5c4d5c4d5c4d5c4d5", "name": "Invoice (Smart Clone)", "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "data": { "clientName": "Bob Jones", "company": "Microsoft", "amount": "1500.00" }, "createdAt": "2024-01-16T10:00:00.000Z" } } ``` --- ## AI Model Integration This section explains how to use DocMiral's template schema endpoint to connect any LLM (GPT-4, Claude, Gemini, etc.) to your document generation pipeline. The key idea is simple: the schema tells the AI exactly what fields the template expects, and the AI returns data in the exact shape needed to fill the document — no manual field mapping required. --- ### Why Template Schema Matters for AI Workflows Templates define their own variable fields in their HTML (e.g. `{{clientName}}`, `{{amount}}`). Without knowing the schema, you would have to hard-code field names or guess them. The `/templates/schema/{id}` endpoint solves this by exposing those fields in machine-readable formats, including a format purpose-built for OpenAI function calling (`aimodel_openai`) and a standard JSON Schema format compatible with any LLM that supports structured output. This means: - **No prompt engineering for field names** — the schema is the single source of truth. - **Validated output** — the AI is constrained to return only fields the template actually uses. - **Works with any template** — change the template and the schema updates automatically. --- ### Flow: LLM to Document ``` 1. GET /templates/schema/{id}?schemaFormat=aimodel_openai&output=schema ↓ schema (OpenAI function definition) 2. Pass schema to your LLM as a tool / function definition ↓ LLM returns structured JSON matching the schema 3. POST /entities/ (create document with the LLM output as `data`) ↓ document ID 4. POST /entities/{id}/build/pdf (or /build/pptx, /build/image) ↓ pre-signed download URL 5. Download the file ``` --- ### Step 1 — Fetch the Schema Fetch the schema in OpenAI tool format: ```bash curl -X GET "https://api.docmiral.com/api/templates/schema/b2c3d4e5f6b2c3d4e5f6b2c3?schemaFormat=aimodel_openai&output=schema" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Response: ```json { "status": 1, "data": { "result": { "name": "fill_document", "description": "Fill the document fields with structured data", "parameters": { "type": "object", "properties": { "clientName": { "type": "string", "description": "Full name of the client" }, "amount": { "type": "string", "description": "Total invoice amount" }, "dueDate": { "type": "string", "description": "Payment due date (YYYY-MM-DD)" }, "items": { "type": "array", "description": "List of line items", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unitPrice": { "type": "number" } } } } }, "required": ["clientName", "amount"] } } } } ``` --- ### Step 2 — Pass the Schema to Your LLM Use the schema's `parameters` object directly as the JSON Schema for structured output or function calling. The AI will return data that exactly matches what the template expects. **OpenAI example (Python)** ```python import openai, requests # 1. fetch schema schema_res = requests.get( "https://api.docmiral.com/api/templates/schema/b2c3d4e5f6b2c3d4e5f6b2c3", params={"schemaFormat": "aimodel_openai", "output": "schema"}, headers={"Authorization": "Bearer YOUR_API_KEY"} ) tool_def = schema_res.json()["data"]["result"] # ready-made OpenAI tool definition # 2. call the LLM client = openai.OpenAI() completion = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "user", "content": "Create an invoice for Alice at Acme Corp, $1,500 due 2024-02-15"} ], tools=[{"type": "function", "function": tool_def}], tool_choice={"type": "function", "function": {"name": "fill_document"}} ) import json doc_data = json.loads( completion.choices[0].message.tool_calls[0].function.arguments ) # doc_data = {"clientName": "Alice", "amount": "1500.00", "dueDate": "2024-02-15", ...} ``` --- ### Step 3 — Create the Document Pass the AI output directly as the `data` body of the create request: ```python create_res = requests.post( "https://api.docmiral.com/api/entities/", json={ "templateId": "b2c3d4e5f6b2c3d4e5f6b2c3", "data": doc_data # the LLM output, no transformation needed }, headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } ) doc_id = create_res.json()["data"]["id"] ``` --- ### Step 4 — Export the Document ```python pdf_res = requests.post( f"https://api.docmiral.com/api/entities/{doc_id}/build/pdf", headers={"Authorization": "Bearer YOUR_API_KEY"} ) download_url = pdf_res.json()["data"]["url"] # download the file file_bytes = requests.get(download_url).content with open("invoice.pdf", "wb") as f: f.write(file_bytes) ``` --- ### Using `output=sample` for Prompting If you prefer to use free-form prompting instead of tool calling, fetch the schema as a sample object and include it in your system prompt to show the LLM what shape to return: ```bash curl "https://api.docmiral.com/api/templates/schema/b2c3d4e5f6b2c3d4e5f6b2c3?schemaFormat=jsonSchema&output=sample&defaultValue=true" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Response: ```json { "status": 1, "data": { "result": { "clientName": "Acme Corp", "amount": "1,500.00", "dueDate": "2024-02-15", "items": [ { "description": "Consulting services", "quantity": 10, "unitPrice": 150 } ] } } } ``` Embed this sample in your system prompt: > "Return a JSON object that matches the following sample exactly. Fill it with real values extracted from the user's message: `{ "clientName": "Acme Corp", "amount": "1,500.00", ... }`" --- ### Schema Format Reference | `schemaFormat` | Best for | |-------------------|-----------------------------------------------------------------------| | `standard` | Human-readable reference; inspect field names and types quickly | | `jsonSchema` | Any LLM with structured output support (Claude, Gemini, Mistral, etc.) | | `aimodel_openai` | OpenAI function calling / tool use — plug directly into `tools[]` | | `output` | Returns | |-----------|-----------------------------------------------------------------------| | `schema` | The schema definition (types, descriptions, required fields) | | `sample` | A filled example object — useful for few-shot prompting | --- ## Error Handling When a request fails the response body contains a message describing the error. ```json { "status": 0, "message": "Document not found" } ``` Common HTTP status codes: | Code | Meaning | |------|------------------------------------------------------------| | 200 | Success | | 400 | Bad request — check your request body or query parameters | | 401 | Unauthorized — invalid or missing API key | | 404 | Not found — the resource does not exist | | 500 | Server error |

{{title}}

{{title}}

{{title}}