API Documentation

File Converters

File converters accept an uploaded file via multipart/form-data and return the converted output. This page covers data format converters and lightweight document-to-PDF converters (HTML and Markdown). For office document converters (Word, Excel, PowerPoint, LibreOffice, Apple iWork, and ePub), see Document Converters.

Available Endpoints

Data Format Converters:

  • POST /v1/convert/json-to-xml
  • POST /v1/convert/xml-to-json
  • POST /v1/convert/json-to-yaml
  • POST /v1/convert/yaml-to-json
  • POST /v1/convert/csv-to-json
  • POST /v1/convert/json-to-csv
  • POST /v1/convert/markdown-to-html

Lightweight Document to PDF Converters:

  • POST /v1/convert/html-to-pdf
  • POST /v1/convert/markdown-to-pdf

Office & Document Converters — See Document Converters for the full list of 11 endpoints covering Microsoft Office, LibreOffice, Apple iWork, and ePub formats.

Request Format

All file converter endpoints use multipart/form-data for the request body.

Parameters

Parameter Type Required Description
file file Yes The file to convert. Must match the expected input format for the endpoint.
output_filename string No Custom filename for the converted output. If omitted, the API generates a filename based on the input file.
pdf_options string (JSON) No PDF output configuration as a JSON string. Controls page size, orientation, margins, and grayscale. See PDF Options. Only applies to PDF output endpoints (html-to-pdf, markdown-to-pdf).

Example Request

The following example converts a CSV file to JSON:

curl -X POST https://api.enconvert.com/v1/convert/csv-to-json \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@data.csv" \
  -F "output_filename=data.json"

PDF Options

PDF endpoints only: The pdf_options parameter applies to all endpoints that produce PDF output (html-to-pdf, markdown-to-pdf, and all document converters). It is ignored by data format converters.

Since file converters use multipart/form-data, the pdf_options parameter is sent as a JSON string in a form field.

Parameters

Field Type Default Description
page_size string "A4" Paper size: A0–A6, B0–B5, Letter, Legal, Tabloid, Ledger.
page_width float null Custom page width in mm. Overrides page_size (requires page_height).
page_height float null Custom page height in mm. Overrides page_size (requires page_width).
orientation string "portrait" "portrait" or "landscape".
margins object {"top": 10, "bottom": 10, "left": 10, "right": 10} Page margins in mm.
scale float 1.0 Scale of content rendering (0.1–2.0).
grayscale boolean false Convert output to grayscale.
header object null Header on each page.
header.content string "" Text content with template variables: {{page}}, {{total_pages}}, {{date}}.
header.height float 15 Header area height in mm.
footer object null Footer on each page.
footer.content string "" Text content with template variables.
footer.height float 15 Footer area height in mm.

Template Variables

Variable Description
{{page}} Current page number
{{total_pages}} Total number of pages
{{date}} Formatted current date

Example: HTML to PDF with Options

curl -X POST https://api.enconvert.com/v1/convert/html-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.html" \
  -F 'pdf_options={"page_size": "Letter", "orientation": "landscape", "margins": {"top": 25, "bottom": 25, "left": 20, "right": 20}, "grayscale": true}'

Example: Markdown to PDF with Page Numbers

curl -X POST https://api.enconvert.com/v1/convert/markdown-to-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@notes.md" \
  -F 'pdf_options={"page_size": "A4", "footer": {"content": "Page {{page}} of {{total_pages}}", "height": 12}}'

Response Formats

The response format depends on the type of API key used to authenticate the request.

Response with Private API Key

When authenticated with a private API key, the API returns a JSON response containing a presigned URL for downloading the converted file and the storage object key.

HTTP 200 OK

{
  "success": true,
  "message": "Conversion successful",
  "presigned_url": "https://storage.enconvert.com/live/files/abc123/csv-to-json/data.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
  "object_key": "live/files/abc123/csv-to-json/data.json",
  "filename": "data.json",
  "file_size": 2048,
  "conversion_time": 0.342
}
Field Type Description
success boolean Whether the conversion succeeded.
message string Human-readable status message.
presigned_url string A temporary, downloadable URL for the converted file.
object_key string The storage path of the converted file (e.g., live/files/{key_id}/{conversion_type}/...).
filename string The name of the converted file.
file_size integer Size of the converted file in bytes.
conversion_time float Time taken for the conversion in seconds.

Response with Public API Key or JWT

When authenticated with a public API key or a JWT token, the API returns the converted file directly as a binary download.

HTTP 200 OK

The response body contains the raw file content with the appropriate Content-Type header.

Response Headers

Header Description Example
Content-Disposition Indicates the filename for the downloaded file. attachment; filename="data.json"
Content-Type MIME type of the converted file. application/json
X-Object-Key The storage path of the converted file. live/files/abc123/csv-to-json/data.json
X-File-Size Size of the converted file in bytes. 2048
X-Conversion-Time Time taken for the conversion in seconds. 0.342
X-Filename The name of the converted file. data.json

Error Responses

Validation Error (400)

Returned when the uploaded file is missing or invalid.

{
  "success": false,
  "error": "No file provided",
  "code": "MISSING_FILE"
}

Unsupported Format (400)

Returned when the file type does not match the expected input format.

{
  "success": false,
  "error": "Invalid file format. Expected CSV file.",
  "code": "INVALID_FORMAT"
}

Conversion Failure (500)

Returned when the conversion engine fails to process the file.

{
  "success": false,
  "error": "Conversion failed: unable to process the file",
  "code": "CONVERSION_ERROR"
}
← Endpoints Overview URL Converters →