API Documentation

Data Format Conversion API#

The Data Formats endpoints convert structured data files between JSON, XML, YAML, CSV, and TOML, plus render Markdown to fully styled HTML. Each conversion is a single POST request with a multipart/form-data file upload: send your file, get the converted result back as raw bytes, or request a presigned download URL instead. All eleven endpoints follow the same request shape, authentication, and error model, so integrating a second format after your first takes minutes.

Supported conversions#

Conversion Endpoint Description
JSON to XML POST /v1/convert/json-to-xml Converts JSON to XML with objects as children of <root>, arrays wrapped in <item> elements, and scalars in <value>.
XML to JSON POST /v1/convert/xml-to-json Converts XML to JSON, mapping attributes to @-prefixed keys, text content to #text, and repeated sibling elements to arrays.
JSON to YAML POST /v1/convert/json-to-yaml Direct mapping to human-readable block-style YAML with key order and unicode preserved.
YAML to JSON POST /v1/convert/yaml-to-json Safely parses .yaml or .yml files (no arbitrary code execution) into pretty-printed 2-space-indented JSON.
JSON to CSV POST /v1/convert/json-to-csv Converts a JSON array of objects to comma-delimited CSV with headers taken from the first object's keys.
CSV to JSON POST /v1/convert/csv-to-json Converts CSV to a JSON array where the header row becomes the keys and every value stays a string (no type inference).
JSON to TOML POST /v1/convert/json-to-toml Converts JSON to TOML, wrapping arrays under an items key and scalars under value; null values are rejected with a 400.
TOML to JSON POST /v1/convert/toml-to-json Converts TOML tables and arrays to pretty-printed JSON, serializing datetime values as ISO-8601 strings.
CSV to XML POST /v1/convert/csv-to-xml Converts CSV to XML with column headers as element tag names and each row as an <item> inside <root>.
XML to CSV POST /v1/convert/xml-to-csv Flattens tabular XML (repeated sibling elements with consistent fields) into comma-delimited CSV rows.
Markdown to HTML POST /v1/convert/markdown-to-html Renders .md or .markdown files into a complete, self-contained HTML page with embedded CSS, tables, code blocks, TOC support, and dark mode.

Shared conventions#

  • Authentication: Every endpoint accepts either a private API key via the X-API-Key header or a JWT Authorization: Bearer token obtained from a public key. See Authentication.
  • Request shape: All conversions are synchronous multipart/form-data POSTs with a required file field plus optional output_filename and direct_download parameters. See Sync and Async Jobs.
  • Responses: By default (direct_download=true) the converted file is returned as raw bytes; with direct_download=false you receive JSON metadata containing a presigned_url, object_key, filename, file_size, and conversion_time_seconds.
  • Input requirements: All inputs must be UTF-8 encoded and match the expected file extension; maximum file size is plan-dependent (Founding plan: 5 MB).
  • Errors: Invalid files or failed conversions return 400, missing or invalid credentials 401, exceeded plan limits 402, and oversized files 413. See Error Codes.

Frequently asked questions#

How do I authenticate requests to the data format conversion endpoints?#

All eleven endpoints accept either a private API key in the X-API-Key header or a JWT Authorization: Bearer token obtained from a public key. The same credentials work across every conversion. See Authentication for details.

Can I get a download URL instead of the converted file bytes?#

Yes. Every endpoint returns the converted file as raw bytes by default; set direct_download=false to receive JSON metadata with a presigned_url, object_key, filename, file_size, and conversion_time_seconds instead.

What file size and input limits apply to data format conversions?#

The maximum file size is plan-dependent (Founding plan: 5 MB), and files exceeding your plan's limit return 413 Payload Too Large. All inputs must be UTF-8 encoded, and each conversion bills one op against your plan's monthly ops allowance, so exhausting it returns 402 Payment Required.

← ots-to-pdf json-to-xml →