{
  "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/watermark-overlay": {
      "summary": "Overlay Watermark PDF API",
      "description": "Overlay PDFs with another PDF page as a watermark. Choose source page, scale, opacity, position, page ranges, links, and style.",
      "post": {
        "tags": [
          "Conversion"
        ],
        "externalDocs": {
          "description": "Read more about the converter",
          "url": "https://www.convertapi.com/pdf-to-watermark-overlay"
        },
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "required": [
                  "File",
                  "OverlayFile"
                ],
                "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"
                  },
                  "OverlayFile": {
                    "type": "string",
                    "description": "Specifies the PDF file to use as overlay. Value can be URL or file content.",
                    "format": "binary",
                    "x-ca-featured": true,
                    "x-ca-label": "Overlay PDF file",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "File",
                    "x-ca-representation": "Default",
                    "x-ca-allowed-extensions": [
                      "pdf"
                    ]
                  },
                  "OverlayPage": {
                    "maximum": 2000,
                    "minimum": 1,
                    "type": "integer",
                    "description": "Specifies the page to use as overlay from the OverlayFile file.",
                    "default": 1,
                    "x-ca-featured": false,
                    "x-ca-label": "Overlay PDF page",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Integer",
                    "x-ca-representation": "Default",
                    "x-ca-range": {
                      "from": "1",
                      "to": "2000"
                    }
                  },
                  "Scale": {
                    "maximum": 2000,
                    "minimum": 0,
                    "type": "integer",
                    "description": "Specifies the watermark scale in percent.",
                    "default": 100,
                    "x-ca-featured": false,
                    "x-ca-label": "Scale watermark",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Integer",
                    "x-ca-representation": "Default",
                    "x-ca-range": {
                      "from": "0",
                      "to": "2000"
                    }
                  },
                  "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"
                    }
                  },
                  "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"
                    }
                  },
                  "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": "watermark",
                    "x-ca-featured": false,
                    "x-ca-label": "Watermark style",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Collection",
                    "x-ca-representation": "Dropdown",
                    "x-ca-values": {
                      "stamp": "Stamp",
                      "watermark": "Watermark"
                    }
                  },
                  "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"
                  },
                  "PageRotation": {
                    "type": "boolean",
                    "description": "Specifies whether to use the page rotation parameter when placing watermark.",
                    "default": false,
                    "x-ca-featured": false,
                    "x-ca-label": "Use page rotation",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Bool",
                    "x-ca-representation": "Default"
                  },
                  "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": "Watermark",
                    "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": "Watermark",
                    "x-ca-type": "Collection",
                    "x-ca-representation": "Dropdown",
                    "x-ca-values": {
                      "top": "top",
                      "center": "center",
                      "bottom": "bottom"
                    }
                  },
                  "PositionX": {
                    "maximum": 10000,
                    "minimum": 1,
                    "type": "integer",
                    "description": "Specifies the watermark X coordinate. If set overrides property HorizontalAlignment.",
                    "x-ca-featured": false,
                    "x-ca-label": "Watermark X coordinate",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Integer",
                    "x-ca-representation": "Default",
                    "x-ca-range": {
                      "from": "1",
                      "to": "10000"
                    }
                  },
                  "PositionY": {
                    "maximum": 10000,
                    "minimum": 1,
                    "type": "integer",
                    "description": "Specifies the watermark Y coordinate. If set overrides property VerticalAlignment.",
                    "x-ca-featured": false,
                    "x-ca-label": "Watermark Y coordinate",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Integer",
                    "x-ca-representation": "Default",
                    "x-ca-range": {
                      "from": "1",
                      "to": "10000"
                    }
                  },
                  "PositionUnit": {
                    "enum": [
                      "pt",
                      "in",
                      "mm",
                      "cm"
                    ],
                    "type": "string",
                    "description": "Specifies measurement unit to use for the PositionX and PositionY properties.",
                    "default": "pt",
                    "x-ca-featured": false,
                    "x-ca-label": "Watermark position unit",
                    "x-ca-group": "Watermark",
                    "x-ca-type": "Collection",
                    "x-ca-representation": "Dropdown",
                    "x-ca-values": {
                      "pt": "Points",
                      "in": "Inches",
                      "mm": "Millimeters",
                      "cm": "Centimeters"
                    }
                  }
                }
              }
            }
          }
        },
        "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": "Use a PDF page as an overlay watermark across target PDFs for branding and background graphics. Select the source overlay file and page, control scale and opacity, and position the overlay on each page. Apply to specific pages or ranges, set a watermark style, and add interactive actions such as external links or go‑to page navigation. Respect page rotation and place the overlay precisely for consistent, professional results across batches and automated workflows.",
      "x-ca-meta-title": "Overlay Watermark PDF API – Use PDF page as watermark",
      "x-ca-meta-description": "Overlay PDFs via API using a PDF page as a watermark. Set source page, scale, opacity, position, page ranges, links, and style.",
      "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"
  }
}