---
title: "Store waveform peaks for an audio or video file"
method: PUT
path: "/v1/files/{uuid}/waveform"
tags: ["Files"]
---

# Store waveform peaks for an audio or video file

`PUT /v1/files/{uuid}/waveform`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/files/{uuid}/waveform`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Safe to repeat. A body with more buckets than the stored waveform replaces it; any other
leaves it as it is (`stored: false`). `buckets` is at most 100 per second of the file's
probed duration (at least 256, at most 60000). An all-zero waveform is refused.

## Path parameters

- `uuid` string, uuid, required

## Request body

- object
  - `format` string, required: Must be "i8mm".
  - `version` integer: Optional; 1.
  - `buckets` integer, required: Number of (min, max) pairs.
  - `peaks` string, required: Base64 of 2 x buckets signed bytes, each -127..127.

## Response `200`

The waveform now on file.

- object
  - `success` boolean
  - `data` object
    - `buckets` integer: Resolution of the stored waveform.
    - `stored` boolean: Whether this call wrote it.
  - `timestamp` string, date-time

## Other responses

- `400`: Invalid format, bucket count or peaks.
- `401`: Missing or invalid API key.
- `403`: The token does not hold files:write.
- `404`: Unknown file, not yours, not media, OR readable only by a container scope your token lacks.
- `422`: The file has no sound.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

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