# Create a music collection

Create a new, empty collection of music tracks owned by the caller. Tracks are added afterwards.

Creates an empty collection. Use [Add a track to a collection](/docs/api-reference/music/add-collection-track) to populate it.

## Path parameters

**`organization_id`** string required

The organization that owns the collection.

## Request Body

**`name`** string required

Human-readable collection name. Must be 1–512 characters.

**`description`** string optional

Free-text description of the collection.

**`cover_track_id`** string optional

A track id (`mtrack_`) whose artwork is used as the collection cover.

**`cover_image_url`** string optional

A direct image URL for the collection cover. Maximum 1024 characters.

## Returns

The created collection object.

**`id`** string

Collection id, prefixed `mcoll_`.

**`name`** string

The collection name.

**`description`** string | null

The collection description, if any.

**`cover_track_id`** string | null

The cover track id, if set.

**`cover_image_url`** string | null

The cover image URL, if set.

**`track_count`** integer

Number of tracks in the collection. `0` for a newly created collection.

**`created_at`** string

ISO 8601 creation timestamp.

**`updated_at`** string

ISO 8601 last-update timestamp.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/music/org_abc123/collections" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Focus Sessions",
    "description": "Instrumental tracks for deep work"
  }'
```


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

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

collection = client.post(
    "/v1/music/org_abc123/collections",
    json={
        "name": "Focus Sessions",
        "description": "Instrumental tracks for deep work",
    },
)
print(collection["id"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/music/org_abc123/collections",
    headers={"X-API-Key": api_key},
    json={
        "name": "Focus Sessions",
        "description": "Instrumental tracks for deep work",
    },
)

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


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

const response = await fetch('https://api.aitronos.com/v1/music/org_abc123/collections', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Focus Sessions',
    description: 'Instrumental tracks for deep work',
  }),
});

const collection = await response.json();
console.log(collection.id);
```

**Response:**


```json 201 Created
{
  "id": "mcoll_4a1f9c7e2b8d",
  "name": "Focus Sessions",
  "description": "Instrumental tracks for deep work",
  "cover_track_id": null,
  "cover_image_url": null,
  "track_count": 0,
  "created_at": "2026-06-28T10:30:00Z",
  "updated_at": "2026-06-28T10:30:00Z"
}
```

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 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "system_message": "Missing USE_MUSIC_GENERATION capability",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_def456uvw",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload is invalid.",
    "system_message": "name must be between 1 and 512 characters",
    "type": "validation_error",
    "status": 422,
    "details": { "field": "name" },
    "trace_id": "req_ghi789xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [List music collections](/docs/api-reference/music/list-collections)
- [Add a track to a collection](/docs/api-reference/music/add-collection-track)
- [Music Studio overview](/docs/api-reference/music/introduction)