Tracks

The core unit of work in Aden — versions, covers, collaborators, comments, todos, and release status.

A track is the central object in Aden. Everything else — albums, sessions, chat, calendar, todos — eventually points back at a track. If you're building on top of Aden, you'll spend most of your time here.

What a track represents

A track is one piece of music as it moves through the studio: from first idea, through revisions and feedback, to a released master. It carries every artifact needed to get there — audio versions, artwork, collaborator splits, comments, todos, and metadata.

Tracks belong to a team and can optionally be grouped into an album. A track without an album is a single.

Data model

Field	Type	Notes
`id`	`number`	Stable numeric ID.
`title`	`string`	Display title.
`status`	`TrackStatus`	`idea`, `in_progress`, `mixing`, `mastering`, `ready`, `released`.
`team_id`	`number`	Owning team.
`album_id`	`number \| null`	Album, if grouped.
`position`	`string`	Fractional index for ordering within team or album.
`cover_url`	`string \| null`	Original cover.
`cover_url_medium`	`string \| null`	Resized variant for lists.
`current_version_id`	`number \| null`	The version surfaced as "the track right now."
`created_at`	`string`	ISO 8601.
`updated_at`	`string`	ISO 8601.

A track owns these sub-resources:

Versions — every iteration of the audio. One is marked current.
Covers — every uploaded artwork. One is marked current.
Collaborators — contacts attached to the track with a role and split.
Comments — feedback threads anchored to a version (and optionally a timestamp inside that version).
Todos — actionable items scoped to a version.
Metadata — ISRC, BPM, key, genre, writers, publishers — anything the release pipeline needs.

Lifecycle

Status is the spine of the lifecycle. The product surfaces it as a kanban, the API exposes it as a string:

idea → in_progress → mixing → mastering → ready → released

Status transitions are explicit — call PATCH /tracks/{id}/status. Any transition is allowed (no enforced graph), but the product UI and analytics assume the order above.

A track is released when its status flips to released. That's the moment to fire downstream automations (DSP delivery, social posts, archival).

Versions

Versions are the heart of the track. Each version is a discrete audio file with its own waveform, plays, comments, and todos. Workflows revolve around producing a new version, getting feedback, and promoting one to current.

Key endpoints:

GET /tracks/{id}/versions — list versions.
POST /tracks/{id}/versions — upload a new version.
GET /tracks/{id}/versions/{versionId}/detail — version with comments, todos, and metadata in one round trip.
PATCH /tracks/{id}/versions/{versionId}/final — mark this version as the current one for the track.
POST /tracks/{id}/versions/{versionId}/plays — record a play (used by the player and analytics).
POST /tracks/{id}/versions/reorder — fractional reorder; never rewrites rows in bulk.

Comments

Comments live on a version and may carry a timestamp (in seconds) plus attachments.

GET /tracks/{id}/versions/{versionId}/comments — list.
POST /tracks/{id}/versions/{versionId}/comments — text-only.
POST /tracks/{id}/versions/{versionId}/comments/with-attachments — multi-file upload in a single request.
POST /tracks/{id}/versions/{versionId}/comments/upload — request a signed upload URL when you want to upload directly to storage.
Reactions: POST / DELETE /tracks/{id}/versions/{versionId}/comments/{commentId}/reactions/{emoji}.

Todos

Todos are version-scoped — "fix the kick at 1:24 in v3" rather than a free-floating task. Use GET /tracks/{id}/versions/{versionId}/todos and the matching write endpoints.

Covers

Tracks can hold many covers (drafts, A/B variants); one is current.

POST /tracks/{id}/covers — upload a new cover.
PATCH /tracks/{id}/covers/{coverId}/current — promote.

The promoted cover populates cover_url and cover_url_medium on the track.

Collaborators

Collaborators are contacts attached to a track with a role (producer, writer, mixer…) and an optional split percentage. They drive credits, splits, and access.

GET /tracks/{id}/collaborators
POST /tracks/{id}/collaborators
DELETE /tracks/{id}/collaborators (by contact)

Search

Two read endpoints:

GET /tracks — paginated list, filtered by team, album, status, etc.
GET /tracks/search/deep — searches titles, metadata, and version filenames. Use this when a producer types into the global command bar.

Recipes

List a team's in-progress tracks

const { data } = await aden.api.v1.tracks.get({
    query: { teamId: 123, status: 'in_progress', limit: 50 },
})

Promote a new version to current

await aden.api.v1
    .tracks({ id: trackId })
    .versions({ versionId })
    .final.patch({})

Mark a track released after a CI run

await aden.api.v1.tracks({ id: trackId }).status.patch({ status: 'released' })

Drop a timestamped comment from an external tool

await aden.api.v1
    .tracks({ id: trackId })
    .versions({ versionId })
    .comments.post({
        content: 'Sub bass clipping here',
        timestamp_seconds: 84.3,
    })

Albums — group tracks into a release.
Team — who owns the track and who can edit it.
API reference — full schemas and parameters.

Tracks

On this page