---
title: "Get a link to upload one audio file"
method: POST
path: "/orders/upload-url"
tags: ["Orders"]
---

# Get a link to upload one audio file

`POST /orders/upload-url`

## Request

- Base URL: `https://barevalue.com/api/v1`
- URL: `https://barevalue.com/api/v1/orders/upload-url`
- Auth: HTTP bearer

For a recording that is a file and has no link, such as a file on the machine an agent runs on. Returns a form to post the file to (`upload_url`, `upload_fields`, the file last in a field named `file`; a ready `curl` command is included) and an `upload_id`. Then place the order with `POST /orders/submit` and that `upload_id` in place of `file_url`. No order exists until then. One audio file, up to 750 MB; the link works for 15 minutes and the upload can be ordered once, within 2 hours. The file is measured by decoding it after upload, the same as a link. Returns 403 `link_orders_only` while uploads are switched off; in that case order with `file_url`.

## Request body

- UploadUrlRequest
  - `filename` string, required: Name of the file, with its extension
  - `size_bytes` integer: Optional size of the file. Storage enforces the 750 MB limit whatever is said here; giving it gets the refusal at once.

## Response `200`

An upload form and the upload_id to order with

- UploadUrlResponse
  - `upload_id` string: Pass this to POST /orders/submit in place of file_url, once the file is uploaded
  - `upload_url` string, uri: Where to POST the form
  - `upload_method` 'POST'
  - `upload_fields` object: Form fields to send exactly as given, before the file
  - `file_field` 'file': Name of the form field that carries the file. It must be the last field.
  - `expires_in_minutes` integer: How long upload_url accepts the file
  - `submit_within_minutes` integer: How long after this call the upload can be ordered
  - `max_bytes` integer
  - `curl` string: A ready command: replace /path/to/your/audio with the file, inside the single quotes it stands in (an apostrophe in the path is written '\''; copy a file with a comma or a semicolon in its path to a plain name first). Prints 204 when the upload worked.
  - `instructions` string

## Other responses

- `401`: Missing or invalid API key
- `403`: link_orders_only: uploads are switched off, order with file_url. Or a refusal the account would also get on submit (email_verification_required, allowance_used).
- `422`: Validation failed
- `429`: too_many_open_uploads: order or let expire the uploads already asked for. upload_limit_reached: the number of upload links per 24 hours is used.

---

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