> ## 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.
# Remote URL upload
> Fetch a file from a remote URL and store it in your Autorender workspace.
## Overview
Fetches a file from a public HTTP or HTTPS URL on our servers and stores it in your workspace. Use this when the file already lives on another server and you don't want to download it locally first.
## Required request
### Headers
| Header | Value |
| --------------- | --------------------- |
| `Authorization` | `Bearer YOUR_API_KEY` |
| `Content-Type` | `application/json` |
### Body fields
| Field | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------- |
| `remote_url` | Yes | Public HTTP or HTTPS URL of the file to fetch |
| `folder` | No | Destination path for the file (e.g. `products/shoes`) |
| `tags` | No | Comma-separated labels you can filter by later (e.g. `hero,banner`) |
| `transform` | No | Transformation string applied as the file is stored (e.g. `w_800,h_600,c_crop`) |
| `metadata` | No | JSON string of custom fields (e.g. `{"source":"shopify"}`) |
| `custom_id` | No | Your own reference ID for the file |
| `random_prefix` | No | Set to `"true"` to append a random suffix to the stored name so filenames don't collide |
## Minimal example
```bash theme={null}
curl -X POST \
https://upload.autorender.io/api/v1/uploads/remote \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"remote_url": "https://example.com/product.jpg"}'
```
## Example with options
```bash theme={null}
curl -X POST \
https://upload.autorender.io/api/v1/uploads/remote \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"remote_url": "https://example.com/product.jpg",
"folder": "products/shoes",
"tags": "imported,shopify",
"transform": "w_1200,f_auto,q_auto"
}'
```
## Next steps
Upload a file's bytes directly from your backend.
Page through the files in your workspace.
## OpenAPI
````yaml api-reference/openapi.json POST /api/v1/uploads/remote
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/remote:
post:
tags:
- Uploads
summary: Remote URL upload
description: Download a file from a remote URL and store it in AutoRender.
operationId: uploadRemote
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
remote_url:
type: string
format: uri
description: HTTP/HTTPS URL to fetch
file_name:
description: Override file name
type: string
folder:
description: Destination folder path
type: string
tags:
description: Tags array or comma-separated string
anyOf:
- type: array
items:
type: string
- type: string
random_prefix:
description: true/false to append random suffix
type: string
custom_id:
type: string
metadata:
description: JSON string of metadata object
type: string
webhook_url:
type: string
format: uri
required:
- remote_url
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 or failed download
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 or failed download
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
description: Unauthorized
'413':
description: Remote file exceeds allowed size
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
errorCode:
type: string
message:
type: string
required:
- error
additionalProperties: false
description: Remote file exceeds allowed size
'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
````