canonical: https://jentic.com/apis/conversiontools.io/conversiontools

# Conversion Tools API

Jentic publishes the only available OpenAPI specification for Conversion Tools API, keeping it validated and agent-ready. The Conversion Tools API converts between 100+ file formats including XML, JSON, Excel, PDF, and CSV using a three-step flow: upload a file, create a conversion task, then download the result. It supports streaming uploads up to 100GB, sandbox mode for free testing, and webhook callbacks for asynchronous workflows. Authentication is a Bearer API token obtained from the user's Conversion Tools profile.

## For AI agents

Convert files between 100+ formats (PDF, Excel, JSON, XML, CSV) by uploading, creating a task, and downloading the result. Agents authenticate with a Bearer API token.

## Scope

Does not perform OCR, image editing, or content extraction beyond format conversion - use for file format conversion across the 100+ supported types only.

## Capabilities

- Upload source files up to 100GB via POST /files for later conversion
- Create a conversion task between supported formats via POST /tasks
- Poll task status with GET `/tasks/{task_id}` until conversion completes
- Download converted output via GET `/files/{file_id}`
- Test integrations free of charge by passing sandbox: true on POST /tasks
- Update file retention mode with PATCH `/tasks/{task_id}/retention`
- Delete task files immediately with POST `/tasks/{task_id}/delete`

## Use cases

### Bulk Document Conversion Pipeline

Convert large batches of documents between formats - for example, archived Excel files to PDF/A or vendor XML feeds to JSON for downstream ETL. The upload-then-task pattern handles streaming files up to 100GB, and the task list endpoint lets operators monitor a queue of conversions. Suited to data engineering teams converting tens of thousands of files per run with deterministic output formats.

Example prompt: Upload sales-2025.xlsx via POST /files, create a task to convert it to PDF, poll until status is 'completed', and download the result

### User-Driven In-App Conversions

Wire Conversion Tools behind an in-app 'export as' feature so end users convert documents on demand without server-side conversion infrastructure. The bearer token sits server-side, and webhook callbacks notify the application when each task finishes. Useful for SaaS products that need to offer broad export options without building 100 format converters in-house.

Example prompt: When a user clicks 'Export as PDF', upload their JSON document, create a JSON-to-PDF task, and email the download link when ready

### CI Sandbox Testing for Conversion Integrations

Develop and CI-test conversion workflows without consuming paid quota by passing sandbox: true on every POST /tasks request. The sandbox returns realistic responses so flows can be validated before production rollout. Useful for engineering teams iterating on conversion logic or onboarding new file formats.

Example prompt: Run a sandbox conversion task that converts a sample CSV to JSON via POST /tasks with sandbox: true and assert the response shape

### Agent-Driven Format Conversion via Jentic

An AI agent converts user-supplied files through Jentic without holding the bearer token. The agent searches for 'convert a file', loads the multi-step Conversion Tools schema, and orchestrates the upload-task-download flow. Through Jentic the API token is injected from the vault so the agent can run conversion loops safely.

Example prompt: Search Jentic for 'convert a PDF to Excel', load the Conversion Tools operations, upload the user's PDF, create the task, and return the Excel download URL

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/files` | Upload a source file |
| GET | `/files/{file_id}` | Download a file |
| POST | `/tasks` | Create a conversion task |
| GET | `/tasks/{task_id}` | Get task status |
| GET | `/tasks` | List all tasks |
| GET | `/config` | Get supported formats and account config |

## Key resources

- **Files** — Upload, download, and inspect files used as conversion input or output
- **Tasks** — Create, list, monitor, and delete conversion tasks across 100+ formats
- **Config** — Retrieve supported formats and account configuration
- **Auth** — Inspect the authenticated user behind the bearer token

## Why Jentic

- **Setup:** Wiring Conversion Tools by hand means holding its bearer token, then coding the upload-then-poll flow yourself: POST a file, create a task, and keep polling GET `/tasks/{task_id}` until the conversion finishes. Through Jentic you install once, import the Conversion Tools API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The conversion targets here are files and tasks your agent creates on the fly rather than fixed resources, so scope it by operations: allow the agent the calls it needs, such as uploading a file and creating and checking a conversion task, and leave out anything you do not want it running. Every operation you credit the agent with stays inside that allowed set.
- **Credential handling:** Your Conversion Tools token is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert a PDF to Excel' or 'check a conversion task status', and Jentic returns the matching Conversion Tools operation with its input schema so the agent runs the upload-and-task flow without browsing the reference docs.

## Related APIs

- **CloudConvert API** — File conversion service across 200+ formats with similar upload-task-download flow.
- **ConvertAPI** — REST API for converting between document, image, and spreadsheet formats.
- **Filestack API** — File ingestion, transformation, and CDN delivery that pairs with conversion services.

## FAQ

### Why is there no official OpenAPI spec for Conversion Tools API?

Conversion Tools does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Conversion Tools API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Conversion Tools API use?

The API uses HTTP bearer authentication. Send your API token (from https://conversiontools.io/profile) in the Authorization: Bearer header on every call. Through Jentic the token sits in the vault and is injected at execution time so it never enters the agent's context.

### How big a file can the Conversion Tools API handle?

The API supports streaming uploads up to 100GB via POST /files, after which a task is created with POST /tasks referencing the uploaded file_id. For very large files, prefer streaming uploads and webhook callbacks rather than synchronous polling.

### Can I test conversions without using my paid quota?

Yes. Pass sandbox: true on the POST /tasks body and the conversion runs in sandbox mode without counting against your quota. This makes CI tests and integration validation free.

### How do I run a file conversion through Jentic?

Run jentic search for 'convert a file', load the upload-and-task operations, then execute POST /files followed by POST /tasks with the source and target formats. Poll GET `/tasks/{task_id}` for status and GET `/files/{file_id}` to download the result.

### What are the rate limits for the Conversion Tools API?

Rate limits are not declared in the OpenAPI spec. Conversion Tools applies plan-based quotas - see https://conversiontools.io for current tiers. Treat the upload and task endpoints as rate-limited per token and back off on HTTP 429 responses.

### How do I delete files after a conversion is done?

Call POST `/tasks/{task_id}/delete` to remove the task's input and output files immediately, or use PATCH `/tasks/{task_id}/retention` to switch the task to a shorter retention mode. This is useful for sensitive documents that should not linger on the service.

### Can I limit what my agent is allowed to do with the Conversion Tools API?

Yes. Because Jentic One is self-hosted, you set the rules for which Conversion Tools operations and credentials your agent may use. Since the targets are files and tasks the agent creates on the fly rather than fixed resources, you scope by operation: grant only the calls it needs, such as uploading a file with POST /files, creating a task with POST /tasks, and checking status with GET `/tasks/{task_id}`, while withholding calls like POST `/tasks/{task_id}/delete.` Every operation you credit the agent with stays inside that allowed set, so it cannot invoke anything you left out.