---
title: "Submit an order"
method: POST
path: "/orders/submit"
tags: ["Orders"]
---

# Submit an order

`POST /orders/submit`

## Request

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

Submit an AI audio editing order for one audio file: `file_url`, a direct public link, or `upload_id` from `POST /orders/upload-url` for a file that has no link. Give one of the two. The file must hold exactly one audio track; one with several is refused once it has been fetched (the order fails with the reason). A fetch that has to be tried again leaves the order in `new` for some minutes: keep polling. Free inside the account's allowance (600 AI minutes per 30 days; 30 until the account email is confirmed). Requires an idempotency key. `order_id` (the upload path before October 2026) is no longer accepted: 410 `upload_id_required`, or 403 `link_orders_only` while uploads are switched off. Human-edited orders through the API were retired in October 2026: `editing_mode=human` or `order_type=video` returns 410.

## Request body

- SubmitOrderRequest
  - `file_url` string, uri: Direct public link to the audio file. Give this or upload_id.
  - `upload_id` string: The upload_id from POST /orders/upload-url, once the file has been uploaded. Give this or file_url.
  - `podcast_name` string, required
  - `episode_name` string, required
  - `episode_number` string, nullable: Digits only. A value that is not a whole number is ignored; the order is still accepted.
  - `special_instructions` string, nullable: Editing instructions (e.g., 'Remove ums and ahs', 'Keep the intro music')
  - `host_names` string, nullable: Comma-separated host names for speaker identification
  - `guest_names` string, nullable: Comma-separated guest names for speaker identification
  - `idempotency_key` string, uuid, nullable, required: Required. A UUID. Resend the same value when retrying so the order is not created twice.
  - `duration_minutes` number: Optional. Audio length in minutes for a file_url order, if known. The real length is measured after download and billed.

## Response `201`

Order submitted successfully

- SubmitOrderResponse
  - `order_id` integer
  - `status` 'pending' | 'processing'
  - `estimated_completion` string, date-time, nullable: Estimated completion time

## Other responses

- `400`: Bad request
- `401`: Missing or invalid API key
- `404`: upload_not_found: no upload with this upload_id is waiting on this account (wrong account, already ordered, or older than 2 hours).
- `422`: Validation failed
- `429`: Rate limit exceeded
- `503`: servers_full: our servers are currently full. Nothing was created and nothing counts against the allowance. Send the same request again after retry_after_seconds (also the Retry-After header). Or agent_plan_paused.

---

[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)