# Reorder a collection

Reorder the tracks in a collection owned by the caller. Each track's new position is its index in the `ordered_track_ids` array (zero-based). Ids that are not in the collection are ignored.

Returns `404` if the collection is not owned by the caller.

## Path parameters

**`organization_id`** string required

The organization that owns the collection.

**`collection_id`** string required

The collection id (`mcoll_`).

## Request Body

**`ordered_track_ids`** array required

An array of track ids (`mtrack_`) in the desired order. Each track is moved to the position matching its index in the array (zero-based). Ids not currently in the collection are ignored.

## Returns

A mutation acknowledgement with `success`, `id` (the collection id), and `detail`.

Example

```bash cURL
curl -X PATCH "https://api.aitronos.com/v1/music/org_abc123/collections/mcoll_4a1f9c7e2b8d/order" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ordered_track_ids": ["mtrack_1b9c4e7f2a6d", "mtrack_8d2e1f6a3c9b"] }'
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

ack = client.patch(
    "/v1/music/org_abc123/collections/mcoll_4a1f9c7e2b8d/order",
    json={"ordered_track_ids": ["mtrack_1b9c4e7f2a6d", "mtrack_8d2e1f6a3c9b"]},
)
print(ack["detail"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.patch(
    "https://api.aitronos.com/v1/music/org_abc123/collections/mcoll_4a1f9c7e2b8d/order",
    headers={"X-API-Key": api_key},
    json={"ordered_track_ids": ["mtrack_1b9c4e7f2a6d", "mtrack_8d2e1f6a3c9b"]},
)

print(response.json()["detail"])
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/music/org_abc123/collections/mcoll_4a1f9c7e2b8d/order', {
  method: 'PATCH',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ordered_track_ids: ['mtrack_1b9c4e7f2a6d', 'mtrack_8d2e1f6a3c9b'] }),
});

const ack = await response.json();
console.log(ack.detail);
```

**Response:**


```json 200 OK
{
  "success": true,
  "id": "mcoll_4a1f9c7e2b8d",
  "detail": "Collection reordered."
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "system_message": "Music collection not found or not owned by caller",
    "type": "client_error",
    "status": 404,
    "details": { "collection_id": "mcoll_4a1f9c7e2b8d" },
    "trace_id": "req_jkl012abc",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload is invalid.",
    "system_message": "ordered_track_ids must be an array of track ids",
    "type": "validation_error",
    "status": 422,
    "details": { "field": "ordered_track_ids" },
    "trace_id": "req_ghi789xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [List a collection's tracks](/docs/api-reference/music/list-collection-tracks)
- [Add a track to a collection](/docs/api-reference/music/add-collection-track)
- [Get a collection](/docs/api-reference/music/get-collection)