> ## 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.
# Direct upload
> Upload a file with multipart/form-data using an API key.
## Overview
Uploads a file to your workspace as `multipart/form-data`. This is the primary upload endpoint for backend services.
## Required request
### Headers
| Header | Value |
| --------------- | --------------------- |
| `Authorization` | `Bearer YOUR_API_KEY` |
| `Content-Type` | `multipart/form-data` |
### Form fields
| Field | Required | Description |
| ----------- | -------- | --------------------------------------------------- |
| `file` | Yes | The binary file to upload |
| `file_name` | Yes | The name the file is stored under in your workspace |
## Minimal example
```bash theme={null}
curl -X POST \
https://upload.autorender.io/api/v1/uploads \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@./image.jpg" \
-F "file_name=image.jpg"
```
## Common optional fields
| Field | Description |
| --------------- | ------------------------------------------------------------------------- |
| `folder` | Destination path for the file (e.g. `products/shoes`) |
| `tags` | Comma-separated labels you can filter by later (e.g. `hero,banner`) |
| `transform` | Transformation string applied as the file is stored (e.g. `w_800,f_auto`) |
| `metadata` | JSON string of custom fields (e.g. `{"source":"shopify"}`) |
| `custom_id` | Your own reference ID for the file |
| `random_prefix` | Appends a random suffix to the stored name so filenames don't collide |
## Success response shape
```json theme={null}
{
"success": true,
"data": {
"file_no": "1234567890",
"name": "image.jpg",
"url": "https://assets.autorender.io/...",
"path": "products/image.jpg",
"format": "jpg",
"file_size": 102400
}
}
```
## Error pattern
A failed request returns `success: false` with an `error` and a `message`. A missing or invalid key returns:
```json theme={null}
{
"success": false,
"error": "Unauthorized",
"message": "Invalid or missing API key"
}
```
## Next steps
Fetch a file from another server instead of uploading its bytes.
Upload large files in parts with presigned URLs.
## OpenAPI
````yaml api-reference/openapi.json POST /api/v1/uploads
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/uploads:
post:
tags:
- Uploads
summary: Server-side direct upload
description: Upload a file from your backend server using multipart/form-data.
operationId: uploadDirect
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- file_name
properties:
file:
type: string
format: binary
description: File to upload.
file_name:
type: string
description: File name (e.g. product.jpg)
example: product.jpg
folder:
type: string
description: Optional folder path
example: products/sku123
transform:
type: string
description: Transform string (w_300,h_300,c_crop,...)
tags:
type: string
description: Comma-separated tags
example: product,thumbnail
random_prefix:
description: true/false to append random suffix
type: string
custom_id:
type: string
description: Custom identifier
example: sku123
metadata:
type: string
description: JSON string of metadata
example: '{"productId":"123"}'
webhook_url:
type: string
description: URL to notify on success
responses:
'201':
description: Upload created
content:
application/json:
schema:
type: object
properties:
id:
type: string
file_no:
type: string
workspace_id:
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:
type: string
mime_type:
type: string
hash:
type: string
tags:
type: array
items:
type: string
metadata:
nullable: true
type: object
additionalProperties:
x-stainless-any: true
custom_id:
nullable: true
type: string
folder_no:
nullable: true
type: string
is_private:
type: boolean
is_duplicate:
type: boolean
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))$
upload_source:
type: string
thumbnail:
type: string
extension:
type: string
required:
- id
- file_no
- workspace_id
- name
- path
- url
- width
- height
- size
- mime_type
- tags
- metadata
- custom_id
- folder_no
- is_duplicate
- created_at
- upload_source
- thumbnail
- extension
additionalProperties: false
description: Upload created
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
errorCode:
type: string
message:
type: string
required:
- error
additionalProperties: false
description: Invalid request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
description: Unauthorized
'402':
description: Storage limit exceeded
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
errorCode:
type: string
message:
type: string
required:
- error
additionalProperties: false
description: Storage limit exceeded
'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
'500':
description: Server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
errorCode:
type: string
message:
type: string
required:
- error
additionalProperties: false
description: Server error
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
````