> ## 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.

# Upload & Extract Text

> Upload an image or PDF document and instantly extract its text using Optical Character Recognition (OCR). If a destination folder is given (via `folder` or `folderId`), the extracted text is also saved to your Dreep storage as a `.txt` file in that folder. With no folder, the text is returned in the response only.


## Saving the extracted text

Name a destination folder and Dreep also stores the extracted text as a `.txt`
asset in it. Use `folder` (a path, created on demand) or `folderId` (a UUID):

```bash theme={null}
curl -X POST "https://api.dreep.cloud/api/v1/ocr" \
  -H "Authorization: Bearer drp_live_xxxxx" \
  -F "file=@receipt.jpg" \
  -F "folder=receipts/2024"
```

With no folder, the text is returned in the response only and `savedAsset` is
`null`. See [Folders & Paths](/guides/folders-and-paths).

## Response size

By default the response contains the extracted `text` only:

```bash theme={null}
curl -X POST "https://api.dreep.cloud/api/v1/ocr" \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "file=@receipt.jpg"
```

```json theme={null}
{
  "text": "ACME STORE\nTotal  $42.00",
  "savedAsset": null
}
```

Pass `includeBlocks=true` when you need the per-line and per-word geometry — for example to
draw bounding boxes over the source image:

```bash theme={null}
curl -X POST "https://api.dreep.cloud/api/v1/ocr" \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "file=@receipt.jpg" \
  -F "includeBlocks=true"
```

```json theme={null}
{
  "text": "ACME STORE\nTotal  $42.00",
  "blocks": [
    {
      "BlockType": "LINE",
      "Text": "ACME STORE",
      "Geometry": { "BoundingBox": { "Width": 0.31, "Height": 0.04, "Left": 0.12, "Top": 0.08 } }
    }
  ],
  "savedAsset": null
}
```

<Note>
  The OCR engine emits one block per page, line, and word, each with its own geometry, so `blocks` is
  typically far larger than the text itself. Leave it off unless you use the coordinates.
</Note>


## OpenAPI

````yaml POST /api/v1/ocr
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/ocr:
    post:
      tags:
        - Media
      summary: Upload & Extract Text
      description: >
        Upload an image or PDF document and instantly extract its text using
        Optical Character Recognition (OCR). If a destination folder is given
        (via `folder` or `folderId`), the extracted text is also saved to your
        Dreep storage as a `.txt` file in that folder. With no folder, the text
        is returned in the response only.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to extract text from (Image or PDF).
                folder:
                  type: string
                  description: >
                    Slug path of the folder to save the extracted text into,
                    relative to the project root. Missing folders are created.
                  example: receipts/2024
                folderId:
                  type: string
                  format: uuid
                  description: >
                    UUID of an existing folder to save the extracted text into.
                    Mutually exclusive with `folder`.
                autoCreateFolders:
                  type: string
                  enum:
                    - 'true'
                    - 'false'
                  default: 'true'
                  description: Set to `false` to require that `folder` already exists.
      responses:
        '200':
          description: Extraction successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  text:
                    type: string
                    description: The fully concatenated plain text.
                  blocks:
                    type: array
                    description: >-
                      Raw AWS Textract block objects (lines, words) with
                      bounding boxes.
                    items:
                      type: object
                  savedAsset:
                    type: object
                    nullable: true
                    description: >-
                      Details of the saved text file, if `folderId` was
                      provided.
                    properties:
                      id:
                        type: string
                      storageKey:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
components:
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: boolean
          example: true
        message:
          type: string
          example: Invalid request parameters
        code:
          type: string
          example: invalid_request
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer

````