@epilot/sdk 2.20.25 → 2.20.27

package/definitions/document.json

@@ -0,0 +1,972 @@
+{
+  "openapi": "3.0.2",
+  "info": {
+    "title": "Document API",
+    "version": "1.0.0",
+    "description": "A document generation API that allows you to generate documents from templates with variables.\n\n[Feature Documentation](https://docs.epilot.io/docs/files/document-generation)\n"
+  },
+  "tags": [
+    {
+      "name": "Documents",
+      "description": "Document Generation"
+    }
+  ],
+  "security": [
+    {
+      "EpilotAuth": []
+    }
+  ],
+  "paths": {
+    "/v2/documents:meta": {
+      "post": {
+        "operationId": "getTemplateMeta",
+        "summary": "getTemplateMeta",
+        "description": "Get metadata for a document template\n\nSupported input document types:\n- .docx\n",
+        "tags": [
+          "Documents"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DocumentMetaRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Document metadata",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentMetaResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Unsupported media type",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/documents:generate": {
+      "post": {
+        "operationId": "generateDocumentV2",
+        "summary": "generateDocumentV2",
+        "description": "Generates documents from templates with variables.\n\nSupported document types as input:\n- .docx\n- .ics\n\nSupported document types as output:\n- .pdf\n- .docx but limited to only text based variables\n- .ics\n\nUses [Template Variables API](https://docs.epilot.io/api/template-variables) to replace variables in the input document.\n",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "job_id",
+            "description": "Job ID for tracking the status of document generation action",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "mode",
+            "description": "Type of mode used for document generation flow:\n- partial_generation will have a intermediate step for users to validate and replace the variable values before generating the final document.\n- full_generation, goes through all the steps for the full generation of final document\n",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "partial_generation",
+                "full_generation"
+              ],
+              "description": "- partial_generation: Generates a partial document for user validation before final generation\n- full_generation: Completes the entire document generation process in one step\n",
+              "default": "full_generation"
+            }
+          },
+          {
+            "in": "query",
+            "name": "preview_mode",
+            "description": "Type of mode used for document generation preview:\n- open - preview_url provides a link to open the file in a browser\n- download - preview_url provides a link to download the file\n",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "open",
+                "download"
+              ],
+              "description": "- open: Preview URL opens the file directly in browser\n- download: Preview URL triggers a download of the file\n",
+              "default": "open"
+            }
+          }
+        ],
+        "tags": [
+          "Documents"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DocumentGenerationV2Request"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Generated document output",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DocumentGenerationV2Response"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/documents:convert": {
+      "post": {
+        "operationId": "convertDocument",
+        "summary": "convertDocument",
+        "description": "Converts a document to a different format.\n\nSupported input document types:\n- .docx\n\nSupported output document types:\n- .pdf\n",
+        "tags": [
+          "Documents"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConvertDocumentRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Conversion job output",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConvertDocumentResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v2/templates:validate": {
+      "post": {
+        "operationId": "validateTemplate",
+        "summary": "validateTemplate",
+        "description": "Validates a document template's variable syntax and, optionally, proposes a hotfixed copy of it.\n\nThe endpoint compiles the template with docxtemplater's core parser (the xlsx module for\nspreadsheets), so a delimiter or tag error reported here is one generation would fail on.\nFailures specific to the image or HTML modules are not covered. Every problem it can repair\nunambiguously — a missing brace, an extra brace, a smart quote or a non-breaking space that\nWord substituted inside a tag — is applied to a **copy** of the template, which is uploaded\nand returned as `fixed_document`.\n\nThe original template is never modified. Accepting the fix is an explicit, separate step:\nthe caller shows the user `issues` (each with its `before`/`after`), lets them download\n`fixed_document.preview_url`, and only then replaces the template.\n\nSupported input document types:\n- .docx, .docm, .dotx\n- .xlsx, .xlsm\n- .pptx\n",
+        "tags": [
+          "Documents"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TemplateValidationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Validation result, with the hotfixed template when one could be produced",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TemplateValidationResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "Template larger than the validator accepts (25 MB)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Unsupported media type",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorOutput"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "S3Reference": {
+        "type": "object",
+        "properties": {
+          "bucket": {
+            "type": "string",
+            "example": "document-api-prod"
+          },
+          "key": {
+            "type": "string",
+            "example": "uploads/my-template.pdf"
+          }
+        },
+        "required": [
+          "bucket",
+          "key"
+        ]
+      },
+      "ErrorOutput": {
+        "type": "object",
+        "properties": {
+          "error_message": {
+            "description": "Error message",
+            "type": "string"
+          },
+          "error_code": {
+            "$ref": "#/components/schemas/ErrorCode"
+          },
+          "error_details": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/InvalidCustomVariableErrorDetails"
+              },
+              {
+                "$ref": "#/components/schemas/InternalErrorDetails"
+              },
+              {
+                "$ref": "#/components/schemas/DocxTemplaterErrorDetails"
+              }
+            ]
+          }
+        }
+      },
+      "InvalidCustomVariableErrorDetails": {
+        "description": "Error details for invalid custom variables. This error will appear under 'PARSE_ERROR' error code.",
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/InvalidCustomVariableErrorDetail"
+        }
+      },
+      "InvalidCustomVariableErrorDetail": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "explanation": {
+            "description": "Explanation for the error",
+            "type": "string"
+          },
+          "context": {
+            "description": "Context for the error",
+            "type": "object",
+            "properties": {
+              "invalid_variables": {
+                "description": "List of invalid variables",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "description": "Invalid variable",
+                  "properties": {
+                    "variable": {
+                      "description": "Variable name",
+                      "type": "string"
+                    },
+                    "error": {
+                      "description": "Explanation for the error",
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "InternalErrorDetails": {
+        "description": "Error details for internal error. This error will appear under 'INTERNAL_ERROR' error code.",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "$ref": "#/components/schemas/InternalErrorDetail"
+            }
+          }
+        }
+      },
+      "InternalErrorDetail": {
+        "type": "object",
+        "description": "Internal error detail",
+        "properties": {
+          "name": {
+            "description": "Name of the error",
+            "type": "string"
+          },
+          "message": {
+            "description": "Error message",
+            "type": "string"
+          },
+          "stack": {
+            "description": "Stack trace",
+            "type": "string"
+          },
+          "cause": {
+            "description": "Cause of the error",
+            "type": "string"
+          }
+        }
+      },
+      "DocxTemplaterErrorDetails": {
+        "description": "Error details for DocxTemplater error. This error will appear under 'PARSE_ERROR' error code.\nSee https://docxtemplater.com/docs/errors/#error-schema for more details.\n",
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/DocxTemplaterErrorDetail"
+        }
+      },
+      "DocxTemplaterErrorDetail": {
+        "type": "object",
+        "description": "DocxTemplater error detail",
+        "properties": {
+          "id": {
+            "description": "Id of the error",
+            "type": "string"
+          },
+          "context": {
+            "description": "Context of the error",
+            "type": "string"
+          },
+          "explanation": {
+            "description": "Explanation of the error",
+            "type": "string"
+          }
+        }
+      },
+      "ErrorCode": {
+        "description": "Error codes for document generation:\n- PARSE_ERROR - Error while parsing the document. Normally related with a bad template using the wrong DocxTemplater syntax.\n- DOC_TO_PDF_CONVERT_ERROR - Error while converting the document to PDF. Normally related with a ConvertAPI failure.\n- INTERNAL_ERROR - Internal error. Please contact support.\n- INVALID_TEMPLATE_FORMAT - Invalid template format (only .docx is supported). This can happen due to a bad word file or an unsupported file extension.\n- TEMPLATE_NOT_FOUND - Template file was not found in S3. This indicates the template was likely deleted.\n",
+        "type": "string",
+        "enum": [
+          "PARSE_ERROR",
+          "DOC_TO_PDF_CONVERT_ERROR",
+          "INTERNAL_ERROR",
+          "INVALID_TEMPLATE_FORMAT",
+          "TEMPLATE_NOT_FOUND"
+        ]
+      },
+      "TemplateValidationRequest": {
+        "type": "object",
+        "required": [
+          "template_document"
+        ],
+        "properties": {
+          "template_document": {
+            "description": "Input template document",
+            "type": "object",
+            "required": [
+              "s3ref"
+            ],
+            "properties": {
+              "filename": {
+                "type": "string",
+                "description": "Document original filename, used to name the fixed copy",
+                "example": "Umzugsmeldung.xlsx"
+              },
+              "s3ref": {
+                "$ref": "#/components/schemas/S3Reference"
+              }
+            }
+          },
+          "fix": {
+            "description": "Attempt to produce a hotfixed copy of the template. When false, the template is only\ninspected and no file is written.\n",
+            "type": "boolean",
+            "default": true
+          },
+          "fix_level": {
+            "description": "How far the hotfix may go:\n- safe - only repairs where the author's intent is unambiguous from the syntax\n  (unbalanced or duplicated braces, editor-substituted characters inside a tag).\n- aggressive - additionally promotes single-brace placeholders such as `{contact.name}`\n  to `{{contact.name}}`. These are common in customer templates but indistinguishable\n  from prose that uses braces, so they are reported with `confidence: low`.\n",
+            "type": "string",
+            "enum": [
+              "safe",
+              "aggressive"
+            ],
+            "default": "safe"
+          }
+        }
+      },
+      "TemplateValidationResponse": {
+        "type": "object",
+        "properties": {
+          "valid": {
+            "description": "Whether the template compiled cleanly before any repair was attempted",
+            "type": "boolean",
+            "example": false
+          },
+          "fixed": {
+            "description": "Whether a corrected copy of the template could be produced",
+            "type": "boolean",
+            "example": true
+          },
+          "issues": {
+            "description": "Everything found in the template, whether or not it could be repaired",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TemplateIssue"
+            }
+          },
+          "unresolved_errors": {
+            "description": "Parser errors that remain after the hotfix (or the original errors when nothing was\nfixed). Empty when the template is valid.\n",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DocxTemplaterErrorDetail"
+            }
+          },
+          "fixed_document": {
+            "description": "The corrected copy, for the user to review and accept. Absent when no repair was\napplied. The original template is left untouched.\n",
+            "type": "object",
+            "properties": {
+              "s3ref": {
+                "$ref": "#/components/schemas/S3Reference"
+              },
+              "filename": {
+                "type": "string",
+                "example": "Umzugsmeldung (fixed).xlsx"
+              },
+              "preview_url": {
+                "description": "Short-lived download link for the corrected copy",
+                "type": "string",
+                "format": "uri"
+              }
+            }
+          }
+        }
+      },
+      "TemplateIssue": {
+        "type": "object",
+        "description": "A single template syntax problem, and the repair proposed for it",
+        "properties": {
+          "id": {
+            "description": "Problem kind. Reuses docxtemplater's error vocabulary where one exists\n(`unopened_tag`, `unclosed_tag`, `duplicate_open_tag`, `duplicate_close_tag`), plus\n`malformed_tag` for single-brace placeholders and `typographic_characters` for\neditor-substituted characters inside an otherwise valid tag.\n",
+            "type": "string",
+            "example": "unopened_tag"
+          },
+          "file": {
+            "description": "Zip part the problem was found in",
+            "type": "string",
+            "example": "xl/sharedStrings.xml"
+          },
+          "location": {
+            "description": "Where the user can find it — a cell reference for spreadsheets, a part label\n(`Document body`, `Header 1`, `Slide 3`) otherwise.\n",
+            "type": "string",
+            "example": "Tabelle1!N4"
+          },
+          "context": {
+            "description": "The offending text with surrounding context",
+            "type": "string",
+            "example": "…Datum: {system.date}} Unterschrift…"
+          },
+          "explanation": {
+            "description": "Why the template parser rejects it",
+            "type": "string",
+            "example": "The tag is missing an opening brace."
+          },
+          "fixable": {
+            "description": "Whether the proposed repair was applied to the fixed copy",
+            "type": "boolean",
+            "example": true
+          },
+          "confidence": {
+            "description": "How sure we are that the repair is what the author meant",
+            "type": "string",
+            "enum": [
+              "high",
+              "medium",
+              "low"
+            ]
+          },
+          "rule": {
+            "description": "The repair rule that produced `after`",
+            "type": "string",
+            "example": "balance_opening_delimiter"
+          },
+          "before": {
+            "description": "The text as it is in the template",
+            "type": "string",
+            "example": "{system.date}}"
+          },
+          "after": {
+            "description": "The text as it would be in the fixed copy",
+            "type": "string",
+            "example": "{{system.date}}"
+          }
+        }
+      },
+      "TemplateSettings": {
+        "type": "object",
+        "description": "Template Settings for document generation",
+        "properties": {
+          "custom_margins": {
+            "description": "Custom margins for the document",
+            "type": "object",
+            "properties": {
+              "top": {
+                "description": "Top margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "bottom": {
+                "description": "Bottom margin in cm",
+                "type": "number",
+                "example": 2.54
+              }
+            }
+          },
+          "suggested_margins": {
+            "description": "Suggested margins for the document",
+            "type": "object",
+            "properties": {
+              "top": {
+                "description": "Top margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "bottom": {
+                "description": "Bottom margin in cm",
+                "type": "number",
+                "example": 2.54
+              }
+            }
+          },
+          "display_margin_guidelines": {
+            "description": "Display margin guidelines (applicable to partial generation only)",
+            "type": "boolean",
+            "example": true
+          },
+          "enable_data_table_margin_autofix": {
+            "description": "Enable data table margin autofix",
+            "type": "boolean",
+            "example": false
+          },
+          "template_with_datatable": {
+            "description": "A flag that indicates whether the template has 1 or more data tables in it",
+            "type": "boolean",
+            "example": false
+          },
+          "enabled_template_settings_persistence": {
+            "description": "Enables the persistance of template settings",
+            "type": "boolean",
+            "example": false
+          },
+          "misconfigured_margins": {
+            "description": "An indication that the page margins are misconfigured",
+            "type": "boolean",
+            "example": false
+          },
+          "file_entity_id": {
+            "description": "The file entity id, used when persisting a new template version with updated settings",
+            "type": "string",
+            "format": "uuid",
+            "example": "123e4567-e89b-12d3-a456-426614174000"
+          }
+        }
+      },
+      "DocumentMetaRequest": {
+        "type": "object",
+        "properties": {
+          "template_document": {
+            "description": "Input template document",
+            "type": "object",
+            "properties": {
+              "s3ref": {
+                "$ref": "#/components/schemas/S3Reference"
+              }
+            }
+          }
+        }
+      },
+      "DocumentMetaResponse": {
+        "type": "object",
+        "properties": {
+          "page_margins": {
+            "description": "Page margins for the document",
+            "type": "object",
+            "properties": {
+              "top": {
+                "description": "Top margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "bottom": {
+                "description": "Bottom margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "left": {
+                "description": "Left margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "right": {
+                "description": "Right margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "header": {
+                "description": "Header margin in cm",
+                "type": "number",
+                "example": 2.54
+              },
+              "footer": {
+                "description": "Footer margin in cm",
+                "type": "number",
+                "example": 2.54
+              }
+            }
+          },
+          "variables": {
+            "description": "List of variables in the document",
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "order.billing_contact.0.salutation",
+              "order.billing_contact.0.title",
+              "order_table",
+              "stayHardStatic",
+              "opportunity[attribute_name]",
+              "opportunity[\"attribute_name\"]",
+              "opportunity.[attribute_name]",
+              "attribute_name",
+              "opportunities.0.attribute_name",
+              "opportunities[0].attribute_name",
+              "contact.opportunities[0].attribute_name",
+              "opportunities[Primary].attribute_name"
+            ]
+          }
+        }
+      },
+      "DocumentGenerationV2Request": {
+        "type": "object",
+        "properties": {
+          "template_document": {
+            "description": "Input template document",
+            "type": "object",
+            "properties": {
+              "filename": {
+                "type": "string",
+                "description": "Document original filename",
+                "example": "my-template-{{order.order_number}}.docx"
+              },
+              "s3ref": {
+                "$ref": "#/components/schemas/S3Reference"
+              }
+            }
+          },
+          "context_entity_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Entity to use for variable context",
+            "example": "bcd0aab9-b544-42b0-8bfb-6d449d02eacc"
+          },
+          "user_id": {
+            "type": "string",
+            "description": "User Id for variable context",
+            "example": "100321"
+          },
+          "language": {
+            "type": "string",
+            "description": "Language",
+            "example": "de"
+          },
+          "variable_payload": {
+            "description": "Custom values for variables in the template. Takes the higher precedence than others.",
+            "type": "object",
+            "properties": {
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          },
+          "context_data": {
+            "description": "Custom values for variables in the template. Takes the higher precedence than others.",
+            "type": "object",
+            "properties": {
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          },
+          "template_settings": {
+            "$ref": "#/components/schemas/TemplateSettings"
+          }
+        },
+        "required": [
+          "template_document"
+        ]
+      },
+      "DocumentGenerationV2Response": {
+        "type": "object",
+        "properties": {
+          "job_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "job_status": {
+            "description": "Status of the job",
+            "type": "string",
+            "enum": [
+              "STARTED",
+              "PROCESSING",
+              "SUCCESS",
+              "FAILED"
+            ]
+          },
+          "message": {
+            "description": "A message explaining the progress",
+            "type": "string"
+          },
+          "ics_output": {
+            "type": "object",
+            "properties": {
+              "output_document": {
+                "type": "object",
+                "properties": {
+                  "filename": {
+                    "description": "Generated document filename for ICS",
+                    "type": "string",
+                    "example": "my-appointment-OR-001.ics"
+                  },
+                  "s3ref": {
+                    "$ref": "#/components/schemas/S3Reference"
+                  }
+                },
+                "example": {
+                  "s3ref": {
+                    "bucket": "document-api-preview-prod",
+                    "key": "preview/my-appointment.ics"
+                  }
+                }
+              }
+            }
+          },
+          "pdf_output": {
+            "type": "object",
+            "properties": {
+              "preview_url": {
+                "description": "Pre-signed S3 GET URL for PDF preview",
+                "type": "string",
+                "example": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.pdf"
+              },
+              "output_document": {
+                "type": "object",
+                "properties": {
+                  "filename": {
+                    "description": "Generated document filename for PDF",
+                    "type": "string",
+                    "example": "my-template-OR-001.pdf"
+                  },
+                  "s3ref": {
+                    "$ref": "#/components/schemas/S3Reference"
+                  }
+                },
+                "example": {
+                  "s3ref": {
+                    "bucket": "document-api-preview-prod",
+                    "key": "preview/my-template.pdf"
+                  }
+                }
+              }
+            }
+          },
+          "docx_output": {
+            "type": "object",
+            "properties": {
+              "preview_url": {
+                "description": "Pre-signed S3 GET URL for DOCX preview",
+                "type": "string",
+                "example": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.docx"
+              },
+              "output_document": {
+                "type": "object",
+                "properties": {
+                  "filename": {
+                    "description": "Generated document filename for DOCX",
+                    "type": "string",
+                    "example": "my-template-OR-001.docx"
+                  },
+                  "s3ref": {
+                    "$ref": "#/components/schemas/S3Reference"
+                  }
+                },
+                "example": {
+                  "s3ref": {
+                    "bucket": "document-api-preview-prod",
+                    "key": "preview/my-template.docx"
+                  }
+                }
+              }
+            }
+          },
+          "xlsx_output": {
+            "type": "object",
+            "properties": {
+              "preview_url": {
+                "description": "Pre-signed S3 GET URL for XLSX preview",
+                "type": "string",
+                "example": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/my-template-OR-001.xlsx"
+              },
+              "output_document": {
+                "type": "object",
+                "properties": {
+                  "filename": {
+                    "description": "Generated document filename for XLSX",
+                    "type": "string",
+                    "example": "my-template-OR-001.xlsx"
+                  },
+                  "s3ref": {
+                    "$ref": "#/components/schemas/S3Reference"
+                  }
+                },
+                "example": {
+                  "s3ref": {
+                    "bucket": "document-api-preview-prod",
+                    "key": "preview/my-template.xlsx"
+                  }
+                }
+              }
+            }
+          },
+          "error_output": {
+            "$ref": "#/components/schemas/ErrorOutput"
+          },
+          "variable_payload": {
+            "description": "List of variables and its corresponding replaced values from the document template",
+            "type": "object",
+            "properties": {
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          },
+          "template_settings": {
+            "$ref": "#/components/schemas/TemplateSettings"
+          }
+        }
+      },
+      "ConvertDocumentRequest": {
+        "type": "object",
+        "properties": {
+          "language": {
+            "type": "string",
+            "description": "Language",
+            "example": "de"
+          },
+          "input_document": {
+            "description": "Input document",
+            "type": "object",
+            "properties": {
+              "s3ref": {
+                "$ref": "#/components/schemas/S3Reference"
+              }
+            },
+            "required": [
+              "s3ref"
+            ]
+          },
+          "output_format": {
+            "description": "Output format of the document",
+            "type": "string",
+            "enum": [
+              "pdf"
+            ]
+          },
+          "output_filename": {
+            "description": "Filename of the output document (optional)",
+            "type": "string",
+            "example": "converted.pdf"
+          }
+        },
+        "required": [
+          "input_document",
+          "output_format"
+        ]
+      },
+      "ConvertDocumentResponse": {
+        "type": "object",
+        "properties": {
+          "output_document": {
+            "type": "object",
+            "properties": {
+              "preview_url": {
+                "description": "Pre-signed URL for the converted document",
+                "type": "string",
+                "example": "https://document-api-prod.s3.eu-central-1.amazonaws.com/preview/converted.pdf"
+              },
+              "s3ref": {
+                "$ref": "#/components/schemas/S3Reference"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://document.sls.epilot.io"
+    }
+  ]
+}