# Albums
Source: https://docs.aden.space/docs/developers/concepts/albums

Group tracks into a release, EPs, albums, mixtapes, with shared artwork, collaborators, and ordering.
An **album** is an ordered collection of [tracks](/docs/developers/concepts/tracks) that
ship together. Aden uses the same resource for EPs, albums, mixtapes, and
singles-with-extras: anything where the unit of release is bigger than one
song.

## What an album represents [#what-an-album-represents]

Albums sit between a [team](/docs/developers/concepts/team) and its tracks. Adding a
track to an album doesn't move it, tracks always belong to a team, but it
does opt that track into the album's ordering, collaborator roster, and
release status.

Albums carry the things a release needs as a whole: artwork, a release date,
a tracklist order, and a shared set of collaborators.

## Data model [#data-model]

| Field              | Type             | Notes                                        |
| ------------------ | ---------------- | -------------------------------------------- |
| `id`               | `number`         | Stable numeric ID.                           |
| `title`            | `string`         | Album title.                                 |
| `status`           | `AlbumStatus`    | Mirrors track status: `idea` → `released`.   |
| `team_id`          | `number`         | Owning team.                                 |
| `position`         | `string`         | Fractional index for the team's album shelf. |
| `cover_url`        | `string \| null` | Album artwork.                               |
| `cover_url_medium` | `string \| null` | Resized variant.                             |
| `release_date`     | `string \| null` | ISO date. Drives the calendar release event. |
| `created_at`       | `string`         | ISO 8601.                                    |
| `updated_at`       | `string`         | ISO 8601.                                    |

Album sub-resources:

* **Tracks**: the tracklist, ordered by fractional position.
* **Collaborators**: contacts credited on the album as a whole.
* **Links**: DSP / streaming / store links surfaced on the public release page.

## Lifecycle [#lifecycle]

Albums share the [track status enum](/docs/developers/concepts/tracks#lifecycle), but at
the release level. A common pattern:

1. Create the album, attach tracks (status: `idea`).
2. Move the album to `in_progress` while tracks are being written.
3. Move to `mixing` / `mastering` as masters land.
4. Set `release_date` and flip to `ready` when everything's locked.
5. Flip to `released` on release day. This also fires the
   [calendar](/docs/developers/api) release event.

Album status is independent from track status; the product surfaces both so
you can see, at a glance, "the album is mastering but track 4 is still in
progress."

## Tracklist ordering [#tracklist-ordering]

Track order inside an album is stored as a **fractional index** on each
track's album-scoped position. To reorder, you send the new position for the
moved track only, never N positions at once.

Endpoints:

* `GET /albums/{id}/tracks`: ordered tracklist.
* `POST /albums/{id}/tracks`: attach an existing track.
* `DELETE /albums/{id}/tracks/{trackId}`: detach (the track stays in the team).
* `POST /albums/{id}/tracks/reorder`: move a single track.

## Collaborators [#collaborators]

Album-level collaborators are credited on the release as a whole. Common for
A\&Rs, executive producers, art directors, or anyone whose contribution spans
the whole record.

* `GET /albums/{id}/collaborators`
* `POST /albums/{id}/collaborators`
* `DELETE /albums/{id}/collaborators`

Track-level collaborators stay on the track. Both are displayed on the
release page.

## Status [#status]

Status is its own endpoint so transitions can be audited:

```
PATCH /albums/{id}/status   { "status": "released" }
```

## Links [#links]

DSP and store links live on the album:

* `GET /albums/links`: list links across the team.
* `POST /albums/links`, `PATCH /albums/links`, `DELETE /albums/links`.

## Recipes [#recipes]

### Ship an album end-to-end [#ship-an-album-end-to-end]

```ts
const { data: album } = await aden.api.v1.albums.post({
    teamId: 123,
    title: 'Late Bloomer',
    release_date: '2026-06-12',
})

for (const trackId of trackIds) {
    await aden.api.v1.albums({ id: album.id }).tracks.post({ trackId })
}

await aden.api.v1.albums({ id: album.id }).status.patch({ status: 'ready' })
```

### Reorder track 4 to the top of the album [#reorder-track-4-to-the-top-of-the-album]

```ts
await aden.api.v1.albums({ id: albumId }).tracks.reorder.post({
    trackId,
    beforeTrackId: firstTrackId,
})
```

### Pull a release page payload [#pull-a-release-page-payload]

```ts
const [{ data: album }, { data: tracks }] = await Promise.all([
    aden.api.v1.albums({ id: albumId }).get(),
    aden.api.v1.albums({ id: albumId }).tracks.get(),
])
```

## Related [#related]

* [Tracks](/docs/developers/concepts/tracks): the units inside an album.
* [Team](/docs/developers/concepts/team): who owns the release.
* [API reference](/docs/developers/api): full schemas and parameters.