---
title: "Upload a file and get a download URL"
method: POST
path: "/v1/aion/upload"
---

# Upload a file and get a download URL

`POST /v1/aion/upload`

## Request

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

One-shot file upload for bots and automation.
Send a `multipart/form-data` request with a single `file` field.

The API key is optional: a keyless caller uploads as a guest (100 MB per
file, 24-hour link, or 14 days when priced). Include an `Idempotency-Key`
header to make retries safe (API keys only). Optionally set a price with
`X-Price-Per-Download`, list the file with `X-Listing-Intent`, and send
`X-Wait-For-Ready: true` to get the final result in one response.

## Headers

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

## 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
- `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)