> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreep.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert Document

> Upload a document and convert it to another format - Word to PDF, PDF to Word, a spreadsheet to CSV, a PDF page to an image. The result is saved to your Dreep storage as a new asset, in the folder you name or the project's default folder.

The request waits for the conversion, up to two minutes. Most documents take a second or two and return `201` with the ready asset. A very long one returns `202`: the asset is created and its `url` answers `202` until the conversion finishes.

Each conversion counts toward your plan's monthly document conversions. If the same document was already converted the same way through its fetch URL, that result is reused for free.


Upload a document and get it back in another format, saved as a new asset.
Use it when the file isn't in Dreep yet, or when you want the converted file
stored on its own. For documents you've already uploaded, you can also
[convert them by URL](https://docs.dreep.cloud/transformations/documents.md).

## Word to PDF

```bash theme={null}
curl -X POST "https://api.dreep.cloud/api/v1/convert" \
  -H "Authorization: Bearer drp_live_xxxxx" \
  -F "file=@contract.docx" \
  -F "format=pdf"
```

```json theme={null}
{
  "asset": {
    "id": "5c1d8a72-3f0e-4b8d-9a61-2e7b4c9d0f13",
    "folderId": "a41f0c2e-6b7d-4e8a-9f3c-1d2e5b6a7c8d",
    "filename": "contract.pdf",
    "format": "pdf",
    "mimetype": "application/pdf",
    "sizeBytes": 104719,
    "status": "ready",
    "url": "https://api.dreep.cloud/api/v1/fetch/5c1d8a72-3f0e-4b8d-9a61-2e7b4c9d0f13.pdf"
  }
}
```

## Saving to a folder

With no folder given, the result is saved to the project's default folder.
Name one with `folder` (a path, created on demand), `folderId` (a UUID) or
`key` (a full path that also names the file):

```bash theme={null}
curl -X POST "https://api.dreep.cloud/api/v1/convert" \
  -H "Authorization: Bearer drp_live_xxxxx" \
  -F "file=@report.xlsx" \
  -F "format=pdf" \
  -F "folder=reports/2026"
```

See [Folders & Paths](https://docs.dreep.cloud/guides/folders-and-paths.md).

## What converts to what

| Upload | `format` |
| :- | :- |
| Word: `doc`, `docx`, `odt`, `rtf` | `pdf`, `docx`, `odt`, `rtf` |
| Excel: `xls`, `xlsx`, `ods`, `csv` | `pdf`, `xlsx`, `ods`, `csv` |
| PowerPoint: `ppt`, `pptx`, `odp` | `pdf`, `pptx`, `odp` |
| PDF | `docx`, `png`, `jpeg` |

Anything else returns `400` with the formats that file can convert to.
Converting a spreadsheet to `csv` exports its first sheet.

To render one page of a PDF as an image, pass `page`:

```bash theme={null}
curl -X POST "https://api.dreep.cloud/api/v1/convert" \
  -H "Authorization: Bearer drp_live_xxxxx" \
  -F "file=@brochure.pdf" \
  -F "format=png" \
  -F "page=2"
```

## Long conversions

The request waits for the result, up to two minutes. Most documents take a
second or two and return `201`.

A very long document returns `202` with `status: "processing"`. The asset
already exists, and its `url` answers `202` until the conversion finishes,
then serves the file. Poll the URL, as with
[video transformations](https://docs.dreep.cloud/transformations/videos.md).

## Billing and limits

Each conversion counts toward your plan's monthly document conversions:
**Free** 100, **Starter** 2,000, **Pro** 10,000. Once those are used,
conversions come from a +1,000 add-on pack (\$4.99). If the same document was
already converted the same way through its fetch URL, that result is reused
for free.

| | Free | Starter and Pro |
| :- | :- | :- |
| Largest document | 10 MB | 100 MB |
| PDF output | First 5 pages | All pages |
| PDF to Word | Not included | Included |
| PDF page images | Pages 1 to 5 | Any page |

Going over a limit returns `402` with `code: "LIMIT_EXCEEDED"` and
`featureKey: "document_conversions_monthly"`. The saved result also counts
toward your storage, so a full storage quota returns `402` too. A conversion
only counts once the result is stored, so a failed request costs nothing.


## OpenAPI

````yaml POST /api/v1/convert
openapi: 3.0.0
info:
  title: Dreep API
  description: The universal media processing and storage API.
  version: 1.0.0
servers:
  - url: https://api.dreep.cloud
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/convert:
    post:
      tags:
        - Media
      summary: Convert Document
      description: >
        Upload a document and convert it to another format - Word to PDF, PDF to
        Word, a spreadsheet to CSV, a PDF page to an image. The result is saved
        to your Dreep storage as a new asset, in the folder you name or the
        project's default folder.


        The request waits for the conversion, up to two minutes. Most documents
        take a second or two and return `201` with the ready asset. A very long
        one returns `202`: the asset is created and its `url` answers `202`
        until the conversion finishes.


        Each conversion counts toward your plan's monthly document conversions.
        If the same document was already converted the same way through its
        fetch URL, that result is reused for free.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - format
              properties:
                file:
                  type: string
                  format: binary
                  description: >
                    The document to convert. Word (doc, docx, odt, rtf), Excel
                    (xls, xlsx, ods, csv), PowerPoint (ppt, pptx, odp) or PDF.
                format:
                  type: string
                  enum:
                    - pdf
                    - docx
                    - odt
                    - rtf
                    - xlsx
                    - ods
                    - csv
                    - pptx
                    - odp
                    - png
                    - jpeg
                  description: >
                    The format to convert to. Documents convert within their own
                    family (a spreadsheet can't become a Word document); PDFs
                    convert to docx, png or jpeg.
                page:
                  type: integer
                  minimum: 1
                  description: >
                    Only when converting a PDF to `png` or `jpeg`: which page to
                    render as the image (page 1 if omitted). Leave it out for
                    every other format - those always include all pages.
                folder:
                  type: string
                  description: >
                    Slug path of the folder to save the result into, relative to
                    the project root. Missing folders are created.
                  example: contracts/pdf
                folderId:
                  type: string
                  format: uuid
                  description: >
                    UUID of an existing folder to save the result into. Mutually
                    exclusive with `folder`.
                key:
                  type: string
                  description: >
                    Full storage path for the result, e.g. `contracts/pdf/acme`.
                    The folder part is created like `folder`; the last segment
                    names the file.
                autoCreateFolders:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                  default: 'true'
                  description: Set to `false` to require that `folder` already exists.
      responses:
        '201':
          description: Document converted and saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertedDocument'
        '202':
          description: >
            Still converting after two minutes. The asset exists with `status:
            "processing"`; its `url` answers `202` until it's ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConvertedDocument'
        '400':
          description: >
            Unsupported file type or format pair, `page` on a non-image format,
            a bad folder, or a document that can't be converted (corrupt or
            password-protected, or a page it doesn't have).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: >
            Monthly document conversions or storage used up, or a paid-only
            conversion on the Free plan (PDF to Word, page images past page 5).
            The body carries `code: "LIMIT_EXCEEDED"` and the `featureKey`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: >-
            The document is over your plan's size limit (10 MB on Free, 100 MB
            on paid plans).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: >-
            The conversion failed for a reason other than the document. Safe to
            retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ConvertedDocument:
      type: object
      properties:
        asset:
          type: object
          description: The saved result.
          properties:
            id:
              type: string
              format: uuid
            folderId:
              type: string
              format: uuid
            filename:
              type: string
              example: contract.pdf
            format:
              type: string
              example: pdf
            mimetype:
              type: string
              example: application/pdf
            sizeBytes:
              type: integer
              description: 0 while still processing.
            status:
              type: string
              enum:
                - ready
                - processing
            url:
              type: string
              description: Fetch URL for the result.
    Error:
      type: object
      properties:
        error:
          type: boolean
          example: true
        message:
          type: string
          example: Invalid request parameters
        code:
          type: string
          example: invalid_request
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.