---
title: "Ask for a finished order to be edited again"
method: POST
path: "/orders/{id}/revision"
tags: ["Orders"]
---

# Ask for a finished order to be edited again

`POST /orders/{id}/revision`

## Request

- Base URL: `https://barevalue.com/api/v1`
- URL: `https://barevalue.com/api/v1/orders/{id}/revision`
- Auth: HTTP bearer

Creates a new order that re-edits the original recording with these instructions and returns its id. It is edited by the AI and uses the original's minutes from the allowance, like any order, unless it ends failed: a revision that is not delivered (for one, because it would have sounded worse than the original edit) uses none. The original order and its files are not changed. A revision cannot itself be revised: send the next change to the original order. It returns the edited audio; show notes, transcript and clips are made again only when the instructions ask for them. Only an order placed through the API can be revised through it.

## Path parameters

- `id` integer, required

## Request body

- RevisionRequest
  - `instructions` string, required: What to change, in plain language. Say everything that should be different in one request

## Response `200`

The same revision as a moment ago (duplicate: true)

- RevisionResponse
  - `order_id` integer: The revision, a new order. Poll its status
  - `original_order_id` integer
  - `status` string
  - `minutes_used` integer: Taken from the allowance: the length of the original recording
  - `message` string
  - `duplicate` boolean: Present and true when the same instructions were sent for this order in the last 10 minutes: this is that revision, nothing new was ordered
  - `allowance` AgentAllowance: Limits on an account whose email is not verified yet. `limited` is false once verified.
    - `limited` boolean, required
    - `reason` string
    - `minutes_remaining` number
    - `orders_remaining` integer
    - `minutes_limit` integer
    - `orders_limit` integer
    - `window_days` integer
    - `how_to_lift` string
    - `rate` object: How fast the allowance may be used. A value is null when that limit is not in force.
      - `orders_in_progress` integer
      - `orders_at_once` integer, nullable
      - `minutes_per_window` integer, nullable
      - `window_hours` integer
      - `window_minutes_remaining` number, nullable

## Other responses

- `201`: Revision ordered
- `401`: Missing or invalid API key
- `403`: allowance_used or email_verification_required: the allowance does not cover it
- `404`: Resource not found
- `409`: order_not_done, cannot_revise_a_revision or revision_not_available
- `422`: validation_error
- `429`: rate_limited, too_many_orders_in_progress or a daily capacity limit
- `503`: agent_plan_paused, or servers_full: our servers are currently full, nothing was created, send the request again after retry_after_seconds (also the Retry-After header)

---

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