Composers

A composer (also called a shareholder in the app) is a person or entity that holds a share of a track: writer, producer, publisher. Records carry the identifiers a PRO or distributor needs.

List composers

GET /api/v1/composers?cursor=…

Scope read:composers. Returns up to 100 per page, newest first, each with its linked tracks. Pass the last item's id as cursor for the next page.

[
  {
    "id": "cm3a…",
    "userId": "…",
    "fullName": "Jane Doe",
    "artistName": "Janie",
    "email": "jane@example.com",
    "publisher": "Doe Music Publishing",
    "pro": "ASCAP",
    "ipi": "00012345678",
    "createdAt": "…",
    "tracks": [
      { "share": 50, "role": "writer", "track": { "id": "cm1x…", "name": "Night Drive", "createdAt": "…" } }
    ]
  }
]

Count composers

GET /api/v1/composers/count

Scope read:composers. Returns { "count": 42 }.

Get a composer

GET /api/v1/composers/single?id={composerId}

Scope read:composer (singular). Returns { "composer": { … }, "id", "userId" }. composer is null if not found.

Create a composer

POST /api/v1/composers

Scope create:composer.

{
  "fullName": "Jane Doe",
  "email": "jane@example.com",
  "artistName": "Janie",
  "publisher": "Doe Music Publishing",
  "pro": "ASCAP",
  "ipi": "00012345678"
}

fullName and email are required. Email is unique per account; a duplicate returns 400.

Update a composer

PATCH /api/v1/composers

Scope update:composer. Body is { "id": "…" } plus any fields to change. Returns { "success": true, "composer": { …fields you sent } }.

Delete a composer

DELETE /api/v1/composers?id={composerId}

Scope delete:composer. Permanent. Returns { "success": true }.

Webhooks

Composer changes emit composer.created and composer.updated; linking to tracks emits the shareholder.* and publisher.* events. See Webhooks.