Track Writers & Contributors (API)

When you create a track through the LabelGrid public API, you describe the people behind it with two separate arrays: one for song credits (who did what) and one for publishing splits (who owns the composition and their percentage). This guide explains what each array expects and the rules that run when you create a track.

Two arrays per track

Each track carries two independent arrays:

• contributors[] — song credits: who did what on the track.
• writers[] — publishing splits: who owns the composition and their percentage.

Both arrays reference a writer profile by writerId (camelCase) or writer_id (snake_case). Send exactly one of the two — sending both is rejected. The ID must match a writer you own.

Both arrays point at the same writer registry — the writers you create through the Writers endpoint. So a contributor and a publishing-split writer reference the same underlying writer record.

contributors[] — required at create

contributors[] is required on create, with at least one entry. Each entry has:

• writerId / writer_id
• roles[] — 1 to 3 roles, drawn from the Contributor Roles reference list
• ai_contribution — none, partly, or all

Rules that fire when you POST a track:

• Cover all three role categories — across your contributors, there must be at least one Performer, one Composition & Lyrics, and one Production & Engineering role.
• At least one human — ai_contribution can’t be all for every contributor.
• No duplicate writer IDs across the contributors array.

writers[] — publishing splits (optional, but must total 100% if present)

writers[] is optional at create. If you include it, each entry has:

• writerId / writer_id
• roles[] — at least one role; the only allowed values are Composer and Lyricist
• percentage_share — a number from 0 to 100

Rules:

• Splits must total 100% — the percentage_share values across all writers must sum to 100.
• No duplicate writer IDs.
• No duplicate roles for a single writer.

A minimal example

{
  "title": "Track One",
  "contributors": [
    {
      "writerId": "wr_123",
      "roles": ["Vocals", "Composer", "Producer"],
      "ai_contribution": "none"
    }
  ],
  "writers": [
    {
      "writerId": "wr_123",
      "roles": ["Composer", "Lyricist"],
      "percentage_share": 100
    }
  ]
}

Common errors

• Use the plural roles, not role.
• Use percentage_share, not share.
• Don’t send both writerId and writer_id on the same entry.
• For publishing-split writers, only Composer and Lyricist are accepted as roles.
• If you include writers[], the splits must add up to exactly 100%.

Related

• API Overview — endpoints, authentication, and the full reference (including the Contributor Roles reference data)
• Writers & Contributors — how writer profiles work in your catalog