{ "openapi": "3.0.1", "info": { "title": "ConvertAPI", "description": "# High-Performance File Conversion API\nConvert Word, Excel, PowerPoint, HTML, PDF and Image formats with our powerful file conversion service.\nWe support more than [200 file types.]( https://www.convertapi.com/doc/file-formats)", "termsOfService": "https://www.convertapi.com/terms", "contact": { "url": "https://www.convertapi.com/support", "email": "support@convertapi.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "v2" }, "servers": [ { "url": "https://v2.convertapi.com" }, { "url": "https://eu-v2.convertapi.com" }, { "url": "https://uk-v2.convertapi.com" }, { "url": "https://us-v2.convertapi.com" }, { "url": "https://ca-v2.convertapi.com" }, { "url": "https://as-v2.convertapi.com" }, { "url": "https://au-v2.convertapi.com" } ], "paths": { "/convert/pdf/to/text-watermark": { "summary": "Text Watermark PDF API", "description": "Apply text watermarks to PDF pages with control of font, size, color, stroke, opacity, rotation, position, links, and page ranges.", "post": { "tags": [ "Conversion" ], "externalDocs": { "description": "Read more about the converter", "url": "https://www.convertapi.com/pdf-to-text-watermark" }, "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "File", "Text" ], "type": "object", "properties": { "Timeout": { "maximum": 1200, "minimum": 10, "type": "integer", "description": "Conversion timeout in seconds.", "default": 900, "x-ca-featured": false, "x-ca-label": "Timeout", "x-ca-group": "Execution", "x-ca-type": "Integer", "x-ca-representation": "Default", "x-ca-range": { "from": "10", "to": "1200" } }, "StoreFile": { "type": "boolean", "description": "When the `StoreFile` parameter is set to `True`, your converted file is written to ConvertAPI’s encrypted, temporary storage and made available via a time-limited secure download URL, valid for up to 3 hours. After this period, the file is permanently deleted.\r\n\r\nWhen `StoreFile` is set to `False`, conversion happens entirely in-memory. The raw file bytes are streamed back in the API response without touching disk or external storage, ensuring maximum security and zero persistence so that only you can access the content.\r\n", "default": false, "x-ca-featured": false, "x-ca-label": "Store file", "x-ca-group": "Output", "x-ca-type": "Bool", "x-ca-representation": "Default" }, "File": { "type": "string", "description": "File to be converted. Value can be URL or file content.", "format": "binary", "x-ca-featured": true, "x-ca-label": "File", "x-ca-group": "Input", "x-ca-type": "File", "x-ca-representation": "Default", "x-ca-allowed-extensions": [ "pdf" ] }, "FileName": { "type": "string", "description": "The `FileName` property defines the name of the output file(s) generated by the file conversion API, ensuring safe and\r\nunique file naming. It sanitizes input filenames to remove potentially harmful characters, automatically appends the\r\ncorrect file extension based on the target format, and includes an indexing feature to distinguish multiple output files\r\nfrom a single input. For example, converting `report.docx` to PDF format might result in `report.pdf` for a single file,\r\nor `report_0.pdf`, `report_1.pdf` for multiple files, ensuring each output file is uniquely identifiable.", "x-ca-featured": false, "x-ca-label": "Output file name", "x-ca-group": "Output", "x-ca-type": "String", "x-ca-representation": "Default", "x-ca-range": { "from": "1", "to": "200" } }, "Password": { "type": "string", "description": "Sets the password to open protected documents.", "x-ca-featured": false, "x-ca-label": "Open Password", "x-ca-group": "Document", "x-ca-type": "String", "x-ca-representation": "Default" }, "Text": { "type": "string", "description": "Specifies the text to use as watermark. The list of supported variables: \r\n\r\n* ```%PAGE%``` - current page number\r\n* ```%PAGES%``` - total number of pages\r\n* ```%FILENAME%``` - name of the file\r\n* ```%WEEKDAY%``` - full weekday name\r\n* ```%WEEKDAY_SHORT%``` - abbreviated weekday name\r\n* ```%MONTH%``` - month number (1-12)\r\n* ```%MONTHNAME%``` - full month name\r\n* ```%MONTHNAME_SHORT%``` - abbreviated month name \r\n* ```%YEAR%``` - year with century (YYYY)\r\n* ```%YEAR_SHORT%``` - year without century (YY)\r\n* ```%DAY%``` - day of month\r\n* ```%DAY_YEAR%``` - day of the year (1 -366)\r\n* ```%HOUR%``` - hour (01- 12)\r\n* ```%HOURS%``` - hour (00-23)\r\n* ```%MINUTES%``` - minutes (00-59)\r\n* ```%SECONDS%``` - seconds (00-59)\r\n* ```%AMPM%``` - AM PM\r\n* ```%DATE%``` - local date representation\r\n* ```%TIME%``` - local time representation\r\n* ```%DATETIME%``` - local date and time \r\n* ```%AUTHOR%``` - document Author\r\n* ```%TITLE%``` - document Title\r\n* ```%SUBJECT%``` - document Subject\r\n* ```%KEYWORDS%``` - document Keywords\r\n* ```%N%``` - new line", "x-ca-featured": true, "x-ca-label": "Watermark text", "x-ca-group": "Watermark", "x-ca-type": "String", "x-ca-representation": "Default" }, "Style": { "enum": [ "stamp", "watermark" ], "type": "string", "description": "Specifies watermark style, stamp or watermark. The stamp is placed over page content and watermark under page content.", "default": "stamp", "x-ca-featured": true, "x-ca-label": "Watermark style", "x-ca-group": "Watermark", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "stamp": "Stamp", "watermark": "Watermark" } }, "FontSize": { "maximum": 200, "minimum": 1, "type": "integer", "description": "Specifies the watermark font size.", "default": 40, "x-ca-featured": false, "x-ca-label": "Watermark font size", "x-ca-group": "Watermark", "x-ca-type": "Integer", "x-ca-representation": "Default", "x-ca-range": { "from": "1", "to": "200" } }, "TextRenderingMode": { "enum": [ "filltext", "stroketext", "fillstroke", "invisible" ], "type": "string", "description": "Specifies the text rendering mode.", "default": "fillstroke", "x-ca-featured": false, "x-ca-label": "Text rendering mode", "x-ca-group": "Watermark", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "filltext": "Fill text without stroke", "stroketext": "Stroke text without fill", "fillstroke": "Fill and stroke", "invisible": "Invisible" } }, "FontColor": { "type": "string", "description": "Specifies the watermark font color.", "x-ca-featured": false, "x-ca-label": "Watermark font color", "x-ca-group": "Watermark", "x-ca-type": "Color", "x-ca-representation": "Default" }, "StrokeColor": { "type": "string", "description": "Specifies font stroke color.", "x-ca-featured": false, "x-ca-label": "Stroke color", "x-ca-group": "Watermark", "x-ca-type": "Color", "x-ca-representation": "Default" }, "StrokeWidth": { "maximum": 200, "minimum": 0, "type": "integer", "description": "Specifies the stroke width.", "default": 1, "x-ca-featured": false, "x-ca-label": "Stroke width", "x-ca-group": "Watermark", "x-ca-type": "Integer", "x-ca-representation": "Default", "x-ca-range": { "from": "0", "to": "200" } }, "FontName": { "enum": [ "arial", "bahnschrift", "calibri", "cambria", "consolas", "constantia", "courierNew", "georgia", "tahoma", "timesNewRoman", "verdana" ], "type": "string", "description": "Specifies the watermark font name. Contact us if you are looking for a specific font for a watermark that is missing from the list.", "default": "arial", "x-ca-featured": false, "x-ca-label": "Watermark font name", "x-ca-group": "Watermark", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "arial": "Arial", "bahnschrift": "Bahnschrift", "calibri": "Calibri", "cambria": "Cambria", "consolas": "Consolas", "constantia": "Constantia", "courierNew": "Courier New", "georgia": "Georgia", "tahoma": "Tahoma", "timesNewRoman": "Times New Roman", "verdana": "Verdana" } }, "Rotate": { "maximum": 360, "minimum": 0, "type": "integer", "description": "Specifies the watermark rotation angle in degrees.", "default": 0, "x-ca-featured": false, "x-ca-label": "Rotate watermark", "x-ca-group": "Watermark", "x-ca-type": "Integer", "x-ca-representation": "Default", "x-ca-range": { "from": "0", "to": "360" } }, "Opacity": { "maximum": 100, "minimum": 0, "type": "integer", "description": "Specifies watermark opacity level.", "default": 100, "x-ca-featured": false, "x-ca-label": "Opacity level", "x-ca-group": "Watermark", "x-ca-type": "Integer", "x-ca-representation": "Default", "x-ca-range": { "from": "0", "to": "100" } }, "GoToLink": { "type": "string", "description": "Specifies the web address to go when the watermark is clicked.", "x-ca-featured": false, "x-ca-label": "Go to web link", "x-ca-group": "Watermark", "x-ca-type": "String", "x-ca-representation": "Default" }, "GoToPage": { "type": "string", "description": "Specifies the page number to go when the watermark is clicked.", "x-ca-featured": false, "x-ca-label": "Go to page", "x-ca-group": "Watermark", "x-ca-type": "String", "x-ca-representation": "Default" }, "PageBox": { "enum": [ "mediabox", "trimbox", "bleedbox", "cropbox" ], "type": "string", "description": "Specifies the PDF page box used as the reference area for applying the watermark.", "default": "mediabox", "x-ca-featured": false, "x-ca-label": "PageBox", "x-ca-group": "Size & Position", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "mediabox": "MediaBox", "trimbox": "TrimBox", "bleedbox": "BleedBox", "cropbox": "CropBox" } }, "HorizontalAlignment": { "enum": [ "left", "center", "right" ], "type": "string", "description": "Specifies the horizontal watermark alignment.", "default": "center", "x-ca-featured": false, "x-ca-label": "Horizontal watermark alignment", "x-ca-group": "Size & Position", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "left": "Left", "center": "Center", "right": "Right" } }, "VerticalAlignment": { "enum": [ "top", "center", "bottom" ], "type": "string", "description": "Specifies the vertical watermark alignment.", "default": "center", "x-ca-featured": false, "x-ca-label": "Vertical watermark alignment", "x-ca-group": "Size & Position", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "top": "Top", "center": "Center", "bottom": "Bottom" } }, "MeasurementUnit": { "enum": [ "pt", "in", "mm", "cm" ], "type": "string", "description": "Measurement unit for position and size parameters.", "default": "pt", "x-ca-featured": false, "x-ca-label": "Measurement unit", "x-ca-group": "Size & Position", "x-ca-type": "Collection", "x-ca-representation": "Dropdown", "x-ca-values": { "pt": "Points", "in": "Inches", "mm": "Millimeters", "cm": "Centimeters" } }, "OffsetX": { "maximum": 10000, "minimum": -10000, "type": "number", "description": "Specifies the watermark offset along the X-axis. Positive values move the watermark to the right, while negative values move it to the left, using the selected `MeasurementUnit`.", "x-ca-featured": false, "x-ca-label": "Watermark offset in X axis", "x-ca-group": "Size & Position", "x-ca-type": "Double", "x-ca-representation": "Default", "x-ca-range": { "from": "-10000", "to": "10000" } }, "OffsetY": { "maximum": 10000, "minimum": -10000, "type": "number", "description": "Specifies the watermark offset along the Y-axis. Positive values move the watermark downward, while negative values move it upward, using the selected `MeasurementUnit`.", "x-ca-featured": false, "x-ca-label": "Watermark offset in Y axis", "x-ca-group": "Size & Position", "x-ca-type": "Double", "x-ca-representation": "Default", "x-ca-range": { "from": "-10000", "to": "10000" } }, "Width": { "maximum": 10000, "minimum": 0, "type": "number", "description": "Specifies the width of the watermark text box in the selected `MeasurementUnit`. A value of `0` means the width is unspecified.", "default": 0, "x-ca-featured": false, "x-ca-label": "Watermark text box width", "x-ca-group": "Size & Position", "x-ca-type": "Double", "x-ca-representation": "Default", "x-ca-range": { "from": "0", "to": "10000" } }, "Height": { "maximum": 10000, "minimum": 0, "type": "number", "description": "Specifies the height of the watermark text box in the selected `MeasurementUnit`. A value of `0` means the height is unspecified.", "default": 0, "x-ca-featured": false, "x-ca-label": "Watermark text box height", "x-ca-group": "Size & Position", "x-ca-type": "Double", "x-ca-representation": "Default", "x-ca-range": { "from": "0", "to": "10000" } }, "LineSpacing": { "maximum": 30, "minimum": -30, "type": "integer", "description": "Specifies the watermark text line spacing.", "default": 0, "x-ca-featured": false, "x-ca-label": "Watermark text line spacing", "x-ca-group": "Watermark", "x-ca-type": "Integer", "x-ca-representation": "Default", "x-ca-range": { "from": "-30", "to": "30" } }, "PageRange": { "type": "string", "description": "Set page range. Example 1-10 or 1,2,5.", "default": "1-2000", "x-ca-featured": false, "x-ca-label": "Page Range", "x-ca-group": "Document", "x-ca-type": "String", "x-ca-representation": "Default", "x-ca-range": { "from": "1", "to": "2000" } }, "FontEmbed": { "type": "boolean", "description": "Specifies whether fonts should be embedded.", "default": true, "x-ca-featured": false, "x-ca-label": "Embed watermark font", "x-ca-group": "PDF Output", "x-ca-type": "Bool", "x-ca-representation": "Default" }, "FontSubset": { "type": "boolean", "description": "Specifies whether fonts should be subset.", "default": true, "x-ca-featured": false, "x-ca-label": "Font subset", "x-ca-group": "PDF Output", "x-ca-type": "Bool", "x-ca-representation": "Default" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ConversionCost": { "type": "integer", "description": "This amount will be deducted from your balance after the conversion.", "format": "int32", "example": 1 }, "Files": { "type": "array", "items": { "type": "object", "properties": { "FileName": { "type": "string", "description": "Name of the converted file.", "example": "myfile.pdf" }, "FileExt": { "type": "string", "description": "File type (file name extension)", "example": "pdf" }, "FileSize": { "type": "integer", "description": "File size", "format": "int32", "example": 111955 }, "FileId": { "type": "string", "description": "File ID", "example": "25811safe8e61dd3f51ef00ee5f58b92" }, "Url": { "type": "string", "description": "File URL", "example": "https://v2.convertapi.com/d/v01plsb72o0cmdooq90w4d1lnqsf6oy4/myfile.pdf" }, "FileData": { "type": "string", "description": "Base64 encoded file data", "format": "base64", "example": "JVBERi0xLjcKJb662+4KMSAwIG9iago8PC9UeXBlIC9DYXRhbG9n..." } } } } }, "externalDocs": { "url": "https://www.convertapi.com/doc/content-types#applicationjson-1" } } }, "multipart/mixed": { "schema": { "type": "string", "format": "binary", "externalDocs": { "url": "https://www.convertapi.com/doc/content-types#multipartmixed" } }, "example": "--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f\nConversionCost: 1\nContent-Type: application/octet-stream\nContent-Disposition: attachment; filename=\"my_file.pdf\"; size=8475\n\n--FILE CONTENT--\n--43cf1475-ab15-4c6b-b5ee-e2cbcedfe92f--\n" }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "externalDocs": { "url": "https://www.convertapi.com/doc/content-types#applicationoctet-stream-1" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "415": { "$ref": "#/components/responses/415" }, "500": { "$ref": "#/components/responses/500" }, "503": { "$ref": "#/components/responses/503" } }, "security": [ { "secret": [ ] }, { "token": [ ] }, { "jwt": [ ] } ] }, "x-ca-overview": "Add professional text watermarks to PDF pages with granular styling and placement controls. Choose the text and font family, embed or subset fonts, set size, fill and stroke colors with stroke width, and pick the rendering mode. Adjust opacity and rotation, position the watermark within page or crop box, and target specific pages or ranges. Optionally attach a link or a go‑to page action and preserve or update PDF metadata as needed. Designed for automation, the API produces consistent, branded results across batches without manual editing.", "x-ca-overview-markdown": "", "x-ca-meta-title": "Watermark PDF API - Stamp PDF Pages with Text Watermark", "x-ca-meta-description": "Add text watermarks to PDFs via API. Control font, size, color, stroke, opacity, rotation, position, page ranges, and links.", "x-ca-keywords": "", "x-ca-source-formats": "pdf", "x-ca-destination-formats": "pdf", "x-ca-tags": [ "watermark", "pdf", "featured" ] } }, "components": { "schemas": { "fileId": { "maxLength": 32, "minLength": 32, "type": "string", "description": "Uploaded File ID", "example": "25811safe8e61dd3f51ef00ee5f58b92" }, "error": { "type": "object", "properties": { "Code": { "type": "integer", "description": "Error message code", "format": "int32", "example": 4000 }, "Message": { "type": "string", "description": "Error message text", "example": "Parameter validation error." } }, "externalDocs": { "url": "https://www.convertapi.com/doc/response-codes" } } }, "responses": { "400": { "description": "Malformed request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "415": { "description": "File type error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "500": { "description": "Conversion failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "503": { "description": "Conversion rate limit error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "parameters": { "fileId": { "name": "fileId", "in": "path", "description": "File ID", "required": true, "schema": { "$ref": "#/components/schemas/fileId" } }, "src": { "name": "src", "in": "path", "description": "Source file format (docx, pdf, jpg etc.)", "required": true, "schema": { "type": "string" } }, "dst": { "name": "dst", "in": "path", "description": "Destination file format (docx, pdf, jpg etc.)", "required": true, "schema": { "type": "string" } } }, "headers": { "content-disposition": { "description": "File information ([docummentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition))", "schema": { "type": "string" } }, "file-name": { "description": "File name", "schema": { "type": "string" } }, "file-ext": { "description": "File name extension", "schema": { "type": "string" } }, "file-size": { "description": "File size", "schema": { "type": "integer" } } }, "securitySchemes": { "secret": { "type": "http", "description": "[Get `Secret`](https://www.convertapi.com/a/secret)", "scheme": "bearer" }, "token": { "type": "http", "description": "[Get `Token`](https://www.convertapi.com/a/api-tokens)", "scheme": "bearer" }, "jwt": { "type": "http", "description": "[Get `JWT`](https://www.convertapi.com/a/jwt-tokens)", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "Conversion", "description": "File Conversion API call", "externalDocs": { "description": "File Conversion related operations", "url": "https://www.convertapi.com/doc/content-types" } }, { "name": "File Server", "description": "ConvertAPI temporary file storage", "externalDocs": { "description": "File Server related operations", "url": "https://www.convertapi.com/doc/upload" } }, { "name": "User", "description": "API User", "externalDocs": { "description": "API User related operations", "url": "https://www.convertapi.com/doc/user" } } ], "externalDocs": { "description": "Find out more about ConvertAPI", "url": "https://www.convertapi.com/doc" } }