> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musixmatch.com/llms.txt
> Use this file to discover all available pages before exploring further.
# work.post
> Submit a musical work's details.
export const PlanIndicator = ({children, plan = []}) => {
const plans = {
basic: {
label: 'Basic',
url: 'https://www.musixmatch.com/pro/api/pricing?utm_source=docs&utm_medium=web&utm_content=basic_button'
},
scale: {
label: 'Grow',
url: 'https://www.musixmatch.com/pro/api/pricing?utm_source=docs&utm_medium=web&utm_content=grow_button'
},
scaleNew: {
label: 'Scale',
url: 'https://www.musixmatch.com/pro/api/pricing?utm_source=docs&utm_medium=web&utm_content=scale_button'
},
enterprise: {
label: 'Enterprise',
url: 'https://www.musixmatch.com/pro/api/pricing?utm_source=docs&utm_medium=web&utm_content=enterprise_button'
}
};
const icon = ;
const selectedPlans = Array.isArray(plan) ? plan : [plan];
if (selectedPlans.length === 1 && selectedPlans[0] === 'basic') return null;
const href = selectedPlans.length === 1 ? plans[selectedPlans[0]]?.url : 'https://www.musixmatch.com/pro/api/pricing';
return <>
{icon}
{selectedPlans.map((planKey, index) =>
{plans[planKey]?.label}
{index < selectedPlans.length - 1 && ', '}
)}
{children} plan
;
};
Use this API to submit new or updated publishing data.
This API is designed for publishers to post copyright information associated to a musical work (intellectual property).
The API supports the transmission of detailed information, including their **ownership shares** along with **collection shares** on a per-territory basis, and other essential metadata such as **ISRC codes**, **performer names**, and **alternate titles**, which are crucial for accurate work matching across various sources that partecipate in the royalties collection and our music catalog.
If you are a **label** and you'd like to send us **lyrics in bulk**, please refer to our commercial department.
Please note that you are responsible for transmitting only trustworthy and verified data.
## OpenAPI
````yaml post /ws/1.1/work.post
openapi: 3.0.3
info:
title: Lyrics API
description: >-
These endpoints return metadata about songs and lyrics.
For full details, see the [API
reference](https://docs.musixmatch.com/lyrics-api/introduction) for these
endpoints.
To authenticate your API requests and use the endpoints, you need to include
your API key as a **query parameter** (`apikey`) in every call, like this:
`GET /ws/1.1/track.get?apikey=YOUR_API_KEY`.
In Postman, enter your API Key in the **Auth** tab, where it will be
automatically appended to the request. **Best Practice:** Use **Postman
Vault** to securely store your key; see the official [Postman
documentation](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/)
for details.
Always keep your API key secure and never share it publicly. If you believe
your API key has been compromised, contact us immediately at
`sales@musixmatch.com`.
version: 1.0.0
contact: {}
servers:
- url: https://api.musixmatch.com
security:
- apiKey: []
tags:
- name: Matcher
description: >-
Match an external piece of information (like a title and artist) to a
track in the Musixmatch catalog to retrieve its track ID, lyrics, or
syncs.
- name: Track
description: >-
Search for specific songs, and retrieve detailed information about a
single track, including its lyrics, snippets, translations, and rich sync
data.
- name: Artist
description: >-
Search for artists, and retrieve detailed information about a specific
artist, including their discography (albums).
- name: Album
description: >-
Retrieve detailed information about a specific music album, including the
list of tracks it contains.
- name: Charts
description: >-
Retrieve top-ranking tracks and artists, typically based on country, as
well as lists of available music genres.
- name: Enterprise
description: >-
**For more details on the Enterprise integration refer to the** [official
documentation.](https://docs.musixmatch.com/enterprise-integration/introduction)
paths:
/ws/1.1/work.post:
post:
tags:
- Enterprise
summary: work.post
description: Submit a musical work's details.
operationId: workPost
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: object
required:
- identifier
- title
properties:
identifier:
type: string
minLength: 1
maxLength: 40
description: >-
Your Musical Work’s unique identifier. Submitting
updated data with the same 'identifier' creates a new
version of the same Work.
title:
type: string
minLength: 1
description: The Work's title.
alternate_titles:
type: array
items:
type: string
description: A list of known alternate titles
iswc:
type: string
nullable: true
description: >-
The ISWC of the Work being submitted (example:
T3452468001 or T-123456789-1).
isrc:
type: array
items:
type: string
description: >-
A list of ISRCs that are known to be linked to the Work
(example: AA6Q72000047 or AA-6Q7-20-00047).
performers:
type: array
items:
type: object
required:
- name
properties:
name:
type: string
description: The name of a performer.
identifier:
type: string
nullable: true
description: The performers's unique identifier on your side.
additionalProperties: false
description: A list of known Performers.
owners:
type: object
additionalProperties: false
required:
- publisher
- writer
properties:
publisher:
type: array
description: The publisher schema
items:
type: object
required:
- name
- controlled
additionalProperties: false
properties:
identifier:
type: string
nullable: true
description: The Publisher's unique identifier on your side
name:
type: string
minLength: 1
description: The Publisher's name.
ipi:
type: string
nullable: true
description: >-
The Publisher's IPI. IPI consists of max 11
digits.
role:
type: string
nullable: true
description: >-
The Publisher's role (either "E", "SE" or "AM"
for Original Publisher, Sub-Publisher or
Administrator, respectively).
enum:
- AQ
- AM
- PA
- E
- ES
- SE
- aq
- am
- pa
- e
- es
- se
- null
controlled:
type: string
description: >-
The Publisher's controlled status, either 'Y'
or 'N'
enum:
- 'Y'
- 'N'
- 'y'
- 'n'
mech_ownership_share:
type: integer
nullable: true
minimum: 0
maximum: 10006
description: >-
The share of Mechanical rights owned by this
Publisher. Shares are defined as 5 digits
(i.e. 00000 no share, 10000 full share, 05000
half share).
perf_ownership_share:
type: integer
nullable: true
minimum: 0
maximum: 10006
description: >-
The share of Performing rights owned by this
Publisher. Shares are defined as 5 digits
(i.e. 00000 no share, 10000 full share, 05000
half share).
sync_ownership_share:
type: integer
nullable: true
minimum: 0
maximum: 10006
description: >-
The share of Synchronization rights owned by
this Publisher. Shares are defined as 5 digits
(i.e. 00000 no share, 10000 full share, 05000
half share).
writer:
type: array
description: The writer schema
items:
type: object
required:
- name
- controlled
additionalProperties: false
properties:
identifier:
type: string
nullable: true
description: The Writer's unique identifier on your side.
name:
type: string
minLength: 1
description: The Writer's name.
ipi:
type: string
nullable: true
description: >-
The Writer's IPI. IPI consists of max 11
digits.
role:
type: string
nullable: true
description: >-
The Writer's role (e.g. 'CA' for
Composer-Author, 'C' for Composer, 'A' for
Author, etc.)
enum:
- AD
- AR
- A
- C
- CA
- SR
- SA
- TR
- PA
- EL
- ad
- ar
- a
- c
- ca
- sr
- sa
- tr
- pa
- el
- null
controlled:
type: string
description: >-
The Writer's controlled status, either 'Y' or
'N'
enum:
- 'Y'
- 'N'
- 'y'
- 'n'
mech_ownership_share:
type: integer
nullable: true
minimum: 0
maximum: 10006
description: >-
The share of Mechanical rights owned by this
Writer. Shares are defined as 5 digits (i.e.
00000 no share, 10000 full share, 05000 half
share).
perf_ownership_share:
type: integer
nullable: true
minimum: 0
maximum: 10006
description: >-
The share of Performing rights owned by this
Writer. Shares are defined as 5 digits (i.e.
00000 no share, 10000 full share, 05000 half
share).
sync_ownership_share:
type: integer
nullable: true
minimum: 0
maximum: 10006
description: >-
The share of Synchronization rights owned by
this Writer. Shares are defined as 5 digits
(i.e. 00000 no share, 10000 full share, 05000
half share).
description: >-
The right holders, split into Songwriters and
Publishers.
collection:
type: object
additionalProperties: false
required:
- territories
description: Details on collected royalties, on a per-territory basis
properties:
validity_begin:
type: string
nullable: true
description: >-
Beginning of deal, in the YYYY-MM-DD format. If
omitted, the date of submission will be used
instead.
validity_end:
type: string
nullable: true
description: End of deal, in the YYYY-MM-DD format.
territories:
type: array
description: A list of territories where royalties are collected.
items:
type: object
required:
- code
anyOf:
- required:
- mech_share
- required:
- perf_share
- required:
- sync_share
additionalProperties: true
properties:
code:
type: string
description: >-
One of the territory codes where you collect.
For Worldwide use "XW", otherwise use 2-digit
ISO 3166-1 alpha-2 codes
(https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2),
a two-letter country codes standard published
by the International Organization for
Standardization (ISO).
mech_share:
type: integer
minimum: 0
maximum: 10006
description: >-
The share of Mechanical royalties collected in
this territory. For example, 100% becomes
10000, 50% becomes 5000, 12.50% becomes 1250,
33.3333% becomes 3333 and so on. At least one
of the shares properties (sync_share or
perf_share or mech_share) is required.
perf_share:
type: integer
minimum: 0
maximum: 10006
description: >-
The share of Performing royalties collected in
this territory. For example, 100% becomes
10000, 50% becomes 5000, 12.50% becomes 1250,
33.3333% becomes 3333 and so on.
sync_share:
type: integer
minimum: 0
maximum: 10006
description: >-
The share of Synchronization royalties
collected in this territory. For example, 100%
becomes 10000, 50% becomes 5000, 12.50%
becomes 1250, 33.3333% becomes 3333 and so on.
lyrics:
type: object
description: >-
[Optional] Provide the lyrics for this Work along with
its ownership details.
additionalProperties: false
required:
- lyrics
properties:
duration:
type: integer
description: The duration in seconds of the original recording.
lyrics:
type: string
minLength: 1
description: >-
The lyrics for this Work, verses separated by line
feed. Remember to encode strings properly as the
JSON format is used.
lrc:
type: string
description: >-
Lyrics in LRC format
(https://en.wikipedia.org/wiki/LRC_(file_format)).
Make sure the last row has the time indication and
an empty lyrics line. This time will correspond to
the timing of the end of the last lyrics line,
example: '[04:10.010] \n'
description: The data schema for submitting data of a musical work.
examples:
work.post:
value:
data:
collection:
territories:
- code: IT
mech_share: 10000
sync_share: 10000
validity_begin: '2023-07-17'
identifier: '00001100196005'
owners:
publisher:
- controlled: 'Y'
name: Sony/Atv Tunes Llc
writer:
- controlled: 'Y'
mech_ownership_share: 5000
name: John Lennon
role: CA
sync_ownership_share: 5000
- controlled: 'Y'
mech_ownership_share: 5000
name: Paul McCartney
role: CA
sync_ownership_share: 5000
title: Yellow Submarine
responses:
'200':
description: 200 OK / 400 Bad Request / 401 Unauthorized
headers:
Connection:
schema:
type: string
example: keep-alive
Content-Encoding:
schema:
type: string
example: gzip
Content-Length:
schema:
type: string
example: '99'
Date:
schema:
type: string
example: Fri, 14 Feb 2025 08:03:01 GMT
Vary:
schema:
type: string
example: Accept-Encoding
x-mxm-cache:
schema:
type: string
example: no-cache
x-mxm-header-execute-time:
schema:
type: string
example: '0.15362906455994'
x-mxm-header-status:
schema:
type: string
example: '401'
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
body:
anyOf:
- type: object
properties:
alternate_titles:
type: array
items:
type: object
properties:
title:
type: string
example: Yellow Submarine
example:
- title: Yellow Submarine
collections:
type: object
properties:
'2023-07-17':
type: object
properties:
territories:
type: array
items:
type: object
properties:
code:
type: string
example: IT
countries:
type: array
items:
type: string
example: IT
example:
- IT
mech_share:
type: number
example: 10000
perf_share:
type: number
example: 0
publisher:
nullable: true
example: null
sync_share:
type: number
example: 10000
example:
- code: IT
countries:
- IT
mech_share: 10000
perf_share: 0
publisher: null
sync_share: 10000
validity_begin:
type: string
example: '2023-07-17'
validity_end:
nullable: true
example: null
identifier:
type: string
example: '00001100196005'
is_disabled:
type: number
example: 0
isrc:
type: array
items: {}
example: []
iswc:
type: string
example: ''
last_trasmission:
type: string
example: '2023-07-17'
owners:
type: object
properties:
publisher:
type: array
items:
type: object
properties:
controlled:
type: string
example: 'Y'
id:
type: number
example: 211
identifier:
type: string
example: ''
ipi:
type: string
example: '00000000000'
mech_ownership_share:
type: number
example: 0
mech_society:
nullable: true
example: null
name:
type: string
example: Sony/Atv Tunes Llc
perf_ownership_share:
type: number
example: 0
perf_society:
nullable: true
example: null
role:
nullable: true
example: null
sync_ownership_share:
type: number
example: 0
sync_society:
nullable: true
example: null
type:
type: string
example: publisher
validity_begin:
type: string
example: '2023-07-17'
example:
- controlled: 'Y'
id: 211
identifier: ''
ipi: '00000000000'
mech_ownership_share: 0
mech_society: null
name: Sony/Atv Tunes Llc
perf_ownership_share: 0
perf_society: null
role: null
sync_ownership_share: 0
sync_society: null
type: publisher
validity_begin: '2023-07-17'
writer:
type: array
items:
type: object
properties:
controlled:
type: string
example: 'Y'
id:
type: number
example: 11353
identifier:
type: string
example: ''
ipi:
type: string
example: '00000000000'
mech_ownership_share:
type: number
example: 5000
mech_society:
nullable: true
example: null
name:
type: string
example: John Lennon
perf_ownership_share:
type: number
example: 0
perf_society:
nullable: true
example: null
role:
type: string
example: CA
sync_ownership_share:
type: number
example: 5000
sync_society:
nullable: true
example: null
type:
type: string
example: writer
validity_begin:
nullable: true
example: null
example:
- controlled: 'Y'
id: 11353
identifier: ''
ipi: '00000000000'
mech_ownership_share: 5000
mech_society: null
name: John Lennon
perf_ownership_share: 0
perf_society: null
role: CA
sync_ownership_share: 5000
sync_society: null
type: writer
validity_begin: null
- controlled: 'Y'
id: 11354
identifier: ''
ipi: '00000000000'
mech_ownership_share: 5000
mech_society: null
name: Paul McCartney
perf_ownership_share: 0
perf_society: null
role: CA
sync_ownership_share: 5000
sync_society: null
type: writer
validity_begin: null
ownership:
type: array
items: {}
example: []
performers:
type: array
items: {}
example: []
publisher_short_name:
type: string
example: Sony
source:
type: object
properties:
affiliation:
nullable: true
example: null
control:
type: boolean
example: false
created:
type: string
example: '2011-12-09'
credits_priority:
type: string
example: '15'
description:
type: string
example: SonyATV / EMI
id:
type: number
example: 1
last_updated:
type: string
example: '2024-10-22 16:47:38'
report:
type: string
example: create
sender_id:
type: string
example: '00269021863'
sender_name:
type: string
example: SONY/ATV MUSIC PUBLISHING LLC
short_name:
type: string
example: Sony
type_of_right:
type: string
example: SYN
validity_begin:
type: string
example: '2010-11-04'
validity_end:
nullable: true
example: null
submissions:
type: array
items:
type: object
properties:
creation_date:
type: string
example: '2023-07-17'
disabled:
type: string
example: 'N'
filename:
type: string
example: api-works-2023-07-17.json
id:
type: number
example: 3401968
source:
type: number
example: 1
transmission_date:
type: string
example: '2023-07-17'
example:
- creation_date: '2023-07-17'
disabled: 'N'
filename: api-works-2023-07-17.json
id: 3401968
source: 1
transmission_date: '2023-07-17'
tablespace:
type: string
example: works
title:
type: string
example: Yellow Submarine
type_of_right:
type: string
example: SYN
validity_begin:
nullable: true
example: null
validity_end:
type: string
example: '2024-10-20'
wgid:
type: string
example: works:191813604
work_id:
type: number
example: 191813604
- type: array
items: {}
example: []
- type: array
items: {}
example: []
header:
type: object
properties:
execute_time:
type: number
example: 0.63219499588013
hint:
type: string
example: >-
JSON in input doesn't respect the API JSON schema
- errorType: required - errorDetails:
{"missing":"title"} - errorPath: ["data"]
status_code:
type: number
example: 200
examples:
200 OK:
value:
message:
body:
alternate_titles:
- title: Yellow Submarine
collections:
'2023-07-17':
territories:
- code: IT
countries:
- IT
mech_share: 10000
perf_share: 0
publisher: null
sync_share: 10000
validity_begin: '2023-07-17'
validity_end: null
identifier: '00001100196005'
is_disabled: 0
isrc: []
iswc: ''
last_trasmission: '2023-07-17'
owners:
publisher:
- controlled: 'Y'
id: 211
identifier: ''
ipi: '00000000000'
mech_ownership_share: 0
mech_society: null
name: Sony/Atv Tunes Llc
perf_ownership_share: 0
perf_society: null
role: null
sync_ownership_share: 0
sync_society: null
type: publisher
validity_begin: '2023-07-17'
writer:
- controlled: 'Y'
id: 11353
identifier: ''
ipi: '00000000000'
mech_ownership_share: 5000
mech_society: null
name: John Lennon
perf_ownership_share: 0
perf_society: null
role: CA
sync_ownership_share: 5000
sync_society: null
type: writer
validity_begin: null
- controlled: 'Y'
id: 11354
identifier: ''
ipi: '00000000000'
mech_ownership_share: 5000
mech_society: null
name: Paul McCartney
perf_ownership_share: 0
perf_society: null
role: CA
sync_ownership_share: 5000
sync_society: null
type: writer
validity_begin: null
ownership: []
performers: []
publisher_short_name: Sony
source:
affiliation: null
control: false
created: '2011-12-09'
credits_priority: '15'
description: SonyATV / EMI
id: 1
last_updated: '2024-10-22 16:47:38'
report: create
sender_id: '00269021863'
sender_name: SONY/ATV MUSIC PUBLISHING LLC
short_name: Sony
type_of_right: SYN
validity_begin: '2010-11-04'
validity_end: null
submissions:
- creation_date: '2023-07-17'
disabled: 'N'
filename: api-works-2023-07-17.json
id: 3401968
source: 1
transmission_date: '2023-07-17'
tablespace: works
title: Yellow Submarine
type_of_right: SYN
validity_begin: null
validity_end: '2024-10-20'
wgid: works:191813604
work_id: 191813604
header:
execute_time: 0.63219499588013
status_code: 200
400 Bad Request:
value:
message:
body: []
header:
execute_time: 0.19051003456116
hint: >-
JSON in input doesn't respect the API JSON schema -
errorType: required - errorDetails:
{"missing":"title"} - errorPath: ["data"]
status_code: 400
401 Unauthorized:
value:
message:
body: []
header:
execute_time: 0.15362906455994
status_code: 401
components:
securitySchemes:
apiKey:
type: apiKey
name: apikey
in: query
````