> ## Documentation Index
> Fetch the complete documentation index at: https://autorender.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List files
> Paginated files with sort, folder filter, and meta pagination.
```bash cURL theme={null}
curl --request GET \
--url 'https://upload.autorender.io/api/v1/files?page=1&limit=20&sort_field=file_size&sort_order=desc&folder_no=BGbQHg5UtW' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
```json 200 theme={null}
{
"files": [
{
"file_no": "2353377462",
"name": "ar-juice.jpg",
"thumbanil": "https://assets.autorender.io/FWA7PWC7LZ/h_320,w_320,c_center/ar-juice.jpg",
"url": "https://assets.autorender.io/FWA7PWC7LZ/ar-juice.jpg",
"file_size": 1278975,
"format": "jpg",
"width": 3788,
"height": 5869,
"created_at": "2026-03-27T14:58:53.795Z",
"workspace_no": "FWA7PWC7LZ",
"path": "ar-juice.jpg",
"extension": "image"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 2,
"hasNext": false,
"hasPrev": false
}
}
```
```json 401 theme={null}
{
"success": false,
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
```
## Overview
Returns **`files`** (lightweight rows for listing) alongside **`meta`** pagination (`page`, `limit`, `total`, `hasNext`, `hasPrev`). Order the results with **`sort_field`** and **`sort_order`**, and scope them to one folder with **`folder_no`**.
The API returns each file's thumbnail URL under the key **`thumbanil`** — a known misspelling. Read it exactly as shown.
## Query parameters
| Parameter | Type | Description |
| ------------ | ------- | ------------------------------------------------------- |
| `page` | integer | Page number (default `1`) |
| `limit` | integer | Page size (e.g. `20`) |
| `sort_field` | string | One of: `file_size`, `name`, `created_at`, `updated_at` |
| `sort_order` | string | `asc` or `desc` |
| `folder_no` | string | Only files in this folder |
| `name` | string | Filename filter (partial), if supported |
| `path` | string | Path filter, if supported |
| `tags` | string | Comma-separated tags, if supported |
## Response fields
**`files[]`:** `file_no`, `name`, `thumbanil`, `url`, `file_size`, `format`, `width`, `height`, `created_at`, `workspace_no`, `path`, `extension`
**`meta`:** `page`, `limit`, `total`, `hasNext`, `hasPrev`
## Next steps
Fetch the full metadata for one file by its file number.
Browse the folders in your workspace.
## OpenAPI
````yaml api-reference/openapi.json GET /api/v1/files
openapi: 3.0.0
info:
title: AutoRender Public API
description: >-
REST API for uploading, managing, and serving media assets. All endpoints
require an API key via the x-api-key header or Authorization: Bearer .
version: 1.0.0
contact:
name: AutoRender Support
email: support@autorender.io
servers:
- url: https://app-api.autorender.io
description: Production server
security:
- apiKey: []
tags:
- name: Uploads
description: Upload endpoints (API key required)
- name: Files
description: File management endpoints (API key required)
- name: Folders
description: Folder management endpoints (API key required)
paths:
/api/v1/files:
get:
tags:
- Files
summary: List files
description: List/search files with pagination, filtering, and sorting.
operationId: listFiles
parameters:
- schema:
type: string
in: query
name: folder_no
required: false
description: Filter by folder number
- schema:
type: string
in: query
name: search
required: false
description: Partial name match (case-insensitive)
- schema:
default: 1
type: integer
minimum: 1
maximum: 9007199254740991
in: query
name: page
required: false
- schema:
default: 20
type: integer
minimum: 1
maximum: 100
in: query
name: limit
required: false
- schema:
default: created_at_desc
type: string
enum:
- name_asc
- name_desc
- size_asc
- size_desc
- created_at_asc
- created_at_desc
in: query
name: sort
required: false
responses:
'200':
description: Files list
content:
application/json:
schema:
type: object
properties:
files:
type: array
items:
type: object
properties:
id:
type: string
file_no:
type: string
name:
type: string
path:
type: string
url:
type: string
width:
nullable: true
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
height:
nullable: true
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
size:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
format:
nullable: true
type: string
mime_type:
type: string
tags:
type: array
items:
type: string
metadata:
nullable: true
type: object
additionalProperties:
x-stainless-any: true
folder_no:
nullable: true
type: string
folder_name:
nullable: true
type: string
source:
type: string
created_at:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updated_at:
nullable: true
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- id
- file_no
- name
- path
- url
- width
- height
- size
- format
- mime_type
- tags
- metadata
- folder_no
- folder_name
- source
- created_at
- updated_at
additionalProperties: false
meta:
type: object
properties:
page:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
limit:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
total:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
hasNext:
type: boolean
hasPrev:
type: boolean
required:
- page
- limit
- total
- hasNext
- hasPrev
additionalProperties: false
required:
- files
- meta
additionalProperties: false
description: Files list
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
additionalProperties: false
description: Unauthorized
'429':
description: Rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
retryAfterSeconds:
type: number
required:
- error
- message
additionalProperties: false
description: Rate limit exceeded
'503':
description: Limit service unavailable
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
additionalProperties: false
description: Limit service unavailable
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
name: x-api-key
in: header
description: >-
API key for public endpoints. Can also be provided via Authorization:
Bearer
````