canonical: https://jentic.com/apis/convertapi.com/convertapi

# ConvertAPI

Jentic publishes the only available OpenAPI specification for ConvertAPI, keeping it validated and agent-ready. ConvertAPI converts files between document, image, and web formats through a single POST `/convert/{sourceFormat}/to/{destinationFormat}` endpoint that returns the converted output synchronously. The API also supports uploading files for later conversion, listing available converters, and inspecting account usage. Authentication is either an API secret in the query string or a bearer token in the Authorization header.

## For AI agents

Convert a file from one format to another with a single POST call to ConvertAPI. Agents authenticate with an API secret query parameter or bearer token.

## Scope

Does not perform OCR, content editing, or asynchronous task queuing - use for direct format-to-format file conversion only.

## Capabilities

- Convert a file between any supported source and destination format via POST `/convert/{sourceFormat}/to/{destinationFormat}`
- Upload a file with POST /upload to use as input on subsequent conversions
- Discover supported source and target formats via GET /info
- Inspect account usage and remaining quota via GET /user
- Authenticate either with the Secret query parameter or an Authorization Bearer token

## Use cases

### Synchronous Document-to-PDF Conversion

Convert documents - DOCX, XLSX, HTML, Markdown - to PDF on demand by POSTing the source file to `/convert/{sourceFormat}/to/pdf.` The response carries the converted file directly, so there is no polling step. Suited to applications that need instant export-as-PDF behaviour for user-facing documents.

Example prompt: POST a DOCX file to `/convert/docx/to/pdf` and stream the resulting PDF back to the user

### Format Discovery and Capability Reporting

Build user interfaces that show only the conversions actually supported by ConvertAPI by reading GET /info at startup. The endpoint returns the full source-to-destination matrix, so dropdowns and file pickers stay in sync with the live capability list. Useful for SaaS dashboards exposing conversion options to end users.

Example prompt: Call GET /info and return the full list of formats that can be converted to PDF

### Two-Step Upload-Then-Convert Workflow

Upload a large file once via POST /upload, then run multiple conversions against the same uploaded file by referencing its ID on the convert endpoint. This avoids re-transferring large source files when the same input needs PDF, PNG, and TXT outputs. Useful for archival and indexing pipelines that produce several derivative formats from each source.

Example prompt: Upload report.docx via POST /upload, then trigger conversions to PDF, PNG, and TXT against the returned upload ID

### Agent-Driven File Conversion via Jentic

An AI agent converts user files end-to-end through Jentic without holding the API secret. The agent searches Jentic for 'convert a file', loads the schema, and executes POST `/convert/{sourceFormat}/to/{destinationFormat}` with the desired formats. Through Jentic the secret or bearer token is injected from the vault so authoring loops stay safe.

Example prompt: Search Jentic for 'convert a docx to pdf', load the ConvertAPI schema, then convert the user's uploaded DOCX and return the PDF URL

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/convert/{sourceFormat}/to/{destinationFormat}` | Convert a file between two formats |
| POST | `/upload` | Upload a file to reuse on later conversions |
| GET | `/info` | List all available converters |
| GET | `/user` | Get the authenticated user's account information |

## Key resources

- **Convert** — The primary conversion endpoint, parameterised by source and destination format
- **Upload** — Pre-upload a file to reuse as input on later conversion calls
- **Info** — Discover the full matrix of supported source-to-destination conversions
- **User** — Inspect the authenticated account, quota, and limits

## Why Jentic

- **Setup:** Wiring ConvertAPI by hand means deciding whether to pass the Secret as a query parameter or a bearer token, then handling the format-to-format request and file handoff yourself. Through Jentic you install once, import ConvertAPI from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The source and destination formats travel in the request path as conversion parameters, not as a fixed resource you own, so scope this by operations: allow the agent the calls it needs, such as converting a file and uploading one, and leave read-only lookups like account info in or out as you choose. Each operation you credit the agent with stays inside that allowed set.
- **Credential handling:** Your ConvertAPI secret is stored once, encrypted, by your own Jentic One instance and injected as the Secret query parameter or 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 docx to pdf', and Jentic returns the matching ConvertAPI convert operation with its input schema so the agent builds the request without browsing the reference docs.

## Related APIs

- **CloudConvert API** — File conversion across 200+ formats with an upload-then-task flow.
- **Conversion Tools API** — File conversion with sandbox testing and 100GB streaming uploads.
- **Filestack API** — File ingestion, transformation, and CDN delivery that pairs with conversion services.

## FAQ

### Why is there no official OpenAPI spec for ConvertAPI?

ConvertAPI does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ConvertAPI 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 ConvertAPI use?

Two schemes are supported: the Secret query parameter (apiKey) for the simplest direct use, and HTTP Bearer authentication via the Authorization header. Through Jentic the secret or bearer token is stored in the vault and injected at execution time so it never enters the agent's prompt.

### How do I convert a DOCX file to PDF with ConvertAPI?

POST your DOCX file to `/convert/docx/to/pdf` with multipart form data and the API returns the converted PDF synchronously. There is no separate task or polling step - the response body carries the result.

### Which formats can ConvertAPI convert between?

Call GET /info to retrieve the live list of supported source and destination formats - documents, images, web pages, and more. The endpoint returns the matrix so applications can stay in sync as ConvertAPI adds converters.

### How do I check my ConvertAPI account quota?

Call GET /user with your bearer token or Secret. The response includes account information and the remaining quota for the authenticated user.

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

Run jentic search for 'convert a file', load the POST `/convert/{sourceFormat}/to/{destinationFormat}` operation, then execute it with the source format, destination format, and file. Jentic injects the credential from the vault and returns the converted file as a structured response.

### Can I upload a file once and convert it to multiple formats?

Yes. POST /upload returns an ID for the uploaded file, which can be referenced on subsequent /convert calls to produce different output formats without re-uploading the source. This is efficient for derivative-format pipelines.

### Can I limit what my agent is allowed to do with the ConvertAPI?

Yes. Because you run Jentic One yourself, your own rules decide which ConvertAPI operations and credentials the agent may use. You can allow just the calls it needs, such as converting a file with POST `/convert/{sourceFormat}/to/{destinationFormat}` and uploading a file with POST /upload, while choosing to include or exclude the read-only lookups like GET /info and GET /user. Each operation you credit the agent with stays inside that allowed set, and your stored secret is injected at execution time rather than exposed to the agent.