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

# List Files

> Retrieve paginated list of uploaded files with filtering support

## List Files

**GET** `/files`

Retrieve a paginated list of uploaded files with support for filtering by type and status. Deleted files are excluded by default.

### Features

* Paginated results with configurable page sizes
* Filter by document type and status
* Exclude deleted files by default
* Efficient querying with proper indexing

### Parameters

| Parameter   | Type    | Default | Description                                                        |
| ----------- | ------- | ------- | ------------------------------------------------------------------ |
| `page`      | integer | 1       | Page number                                                        |
| `page_size` | integer | 20      | Items per page (max: 100)                                          |
| `type`      | string  | -       | Filter by document type (invoice, bank\_statement, etc.)           |
| `status`    | string  | -       | Filter by status (pending, processing, completed, failed, deleted) |

### Request

```bash theme={null}
curl "https://api.invaro.ai/api/v1/files?page=1&page_size=10&type=invoice" \
  -H "Authorization: Bearer your_api_key"
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "files": [
      {
        "id": "72f574a0-b3d2-4a0f-8527-f542e6ea7500",
        "filename": "invoice.pdf",
        "file_id": "1234567890_invoice.pdf",
        "type": "invoice",
        "status": "pending",
        "size": 84898,
        "created_at": "2024-01-07T10:00:00Z",
        "completed_at": null
      }
    ],
    "page": 1,
    "page_size": 10,
    "total": 25
  }
}
```

### Response Fields

| Field          | Type    | Description                      |
| -------------- | ------- | -------------------------------- |
| `id`           | string  | Unique file identifier           |
| `filename`     | string  | Original filename                |
| `file_id`      | string  | Internal file storage identifier |
| `type`         | string  | Document type                    |
| `status`       | string  | Processing status                |
| `size`         | integer | File size in bytes               |
| `created_at`   | string  | Upload timestamp (ISO 8601)      |
| `completed_at` | string  | Processing completion timestamp  |
| `page`         | integer | Current page number              |
| `page_size`    | integer | Items per page                   |
| `total`        | integer | Total number of files            |

## Try It Out

Use the interactive playground above to test the list files endpoint. You can:

1. **Add your API key** in the Authorization header
2. **Configure pagination** with page and page\_size parameters
3. **Apply filters** by type (invoice, bank\_statement) or status
4. **Execute the request** to see paginated results

The playground allows you to experiment with different filter combinations.


## OpenAPI

````yaml GET /files
openapi: 3.0.0
info:
  title: Invaro Document Processing API
  description: API for processing bank statements and invoices using OCR and AI
  version: 1.0.0
  contact:
    name: Invaro Support
    email: support@invaro.ai
    url: https://docs.invaro.ai
servers:
  - url: https://api.invaro.ai/api/v1
    description: Production API
security:
  - bearerAuth: []
paths:
  /files:
    get:
      tags:
        - Files API
      summary: List Files
      description: Retrieve paginated list of uploaded files with filtering support
      operationId: listFiles
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Page number
          example: 1
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Items per page
          example: 10
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Filter by document type (invoice, bank_statement, etc.)
          example: invoice
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - processing
              - completed
              - failed
              - deleted
          description: Filter by status
          example: completed
      responses:
        '200':
          description: Files retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      files:
                        type: array
                        items:
                          $ref: '#/components/schemas/FileMetadata'
                      page:
                        type: integer
                        example: 1
                      page_size:
                        type: integer
                        example: 10
                      total:
                        type: integer
                        example: 25
components:
  schemas:
    FileMetadata:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 72f574a0-b3d2-4a0f-8527-f542e6ea7500
        filename:
          type: string
          example: invoice.pdf
        file_id:
          type: string
          example: 1234567890_invoice.pdf
        type:
          type: string
          example: invoice
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - deleted
          example: pending
        size:
          type: integer
          example: 84898
        created_at:
          type: string
          format: date-time
          example: '2024-01-07T10:00:00Z'
        completed_at:
          type: string
          format: date-time
          example: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````