---
title: "Upload a file from a URL"
method: POST
path: "/v1/aion/upload-url"
---

# Upload a file from a URL

`POST /v1/aion/upload-url`

## Request

- Base URL: `https://api.payaion.com`
- URL: `https://api.payaion.com/v1/aion/upload-url`
- Auth: one of:
  - none
  - API key in header `X-Aion-Key`

Provide an HTTPS URL and the server fetches + stores the file.
Ideal for bots that receive temporary file URLs (Discord, Slack, webhooks).
Private IPs and internal hostnames are blocked (SSRF protection).
Takes the same optional headers as `/v1/aion/upload`: `Idempotency-Key`,
`X-Price-Per-Download`, `X-Payout-Address`, `X-Listing-Intent` and
`X-Wait-For-Ready`. The API key is optional; a keyless caller uploads as a
guest.

## Headers

- `Idempotency-Key` string
- `X-Price-Per-Download` number
- `X-Payout-Address` string
- `X-Listing-Intent` string
- `X-Wait-For-Ready` 'true'

## Request body

- object
  - `url` string, uri, required: HTTPS URL of the file to fetch (Basic 500 MB / Pro 1 GB)
  - `fileName` string: Optional filename override (derived from URL if omitted)

## Response `200`

Returned when `X-Wait-For-Ready` held the request until the upload finished or the wait ran out

- UploadReadyResult
  - `uploadId` string, required
  - `status` string, required: READY on success, otherwise the last status seen (for example FAILED or TIMEOUT)
  - `ready` boolean, required
  - `statusUrl` string, required
  - `downloadUrl` string, uri, required
  - `expiresAt` string, date-time, required
  - `pricePerDownload` string, nullable: Price per download in USD (present only when set)
  - `url` string, uri: Market page (/m/{hash}), present when the listing was created
  - `listingSkipped` ListingSkipped: The daily listing limit was reached. The file was uploaded but not listed.
    - `code` 'listing_limit_reached', required
    - `message` string, required
    - `retryAfterSec` integer, required

## Other responses

- `201`: Idempotent replay of an earlier request with the same `Idempotency-Key`
- `202`: Upload accepted for processing
- `400`: Bad request
- `401`: Invalid or missing credentials
- `403`: Scope denied or access forbidden
- `408`: Timed out fetching the remote URL
- `409`: Idempotency key already in progress
- `413`: File exceeds size limit
- `415`: File type not allowed
- `429`: Rate limit exceeded
- `502`: Upstream failure (storage or fetch)
- `503`: Concurrency limit reached

---

[API](https://skmtc.dev/payaion/apis/payaion-api.md) · [All operations](https://skmtc.dev/payaion/apis/payaion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/payaion/apis/payaion-api/revisions/29927240cfc2?raw)