---
title: "Remplacer une chanson de mon carnet"
method: PUT
path: "/me/songs/{songId}"
tags: ["carnet"]
---

# Remplacer une chanson de mon carnet

`PUT /me/songs/{songId}`

## Request

- Base URL: `https://jam-jam.org/api/v1`
- URL: `https://jam-jam.org/api/v1/me/songs/{songId}`
- Auth: one of:
  - HTTP bearer
  - none

DECLARATIF : la chanson DEVIENT exactement le corps envoye. Ce qui
n'y figure pas disparait (une branche `detectedKey` absente efface la
tonalite). C'est ce qui rend ce verbe idempotent par nature : rejouer
le meme corps rend le meme etat.

L'identifiant de l'URL fait foi, meme si `song.id` en porte un autre :
le payload stocke est reecrit pour concorder avec sa cle. Si
l'identifiant n'existe pas, il est CREE (`201`), comme tout PUT.

CONCURRENCE : poser `If-Match` avec l'`updatedAt` lu transforme
l'ecriture en « remplace seulement si personne ne m'a devance ». Sans
`If-Match`, le dernier ecrivain gagne.

## Path parameters

- `songId` string, required

## Headers

- `If-Match` string

## Request body

- SongUpsert: Corps de `POST /me/songs` et de `PUT /me/songs/{songId}`. Un champ INCONNU est REFUSE (`400`), jamais retire en silence : un client qui se trompe de nom doit l'apprendre, pas croire qu'il a ete pris en compte.
  - `song` object, required: Payload pivot canonique. La meme forme que `songs[0]` de `GET /jobs/{id}/result/songbook` et que `song` de `GET /me/songs/{songId}` : `title` (obligatoire, non vide), `artist`, `sections[].lines[].lyrics` et `.chords[] = { offset, chord }`, `detectedKey { tonic, scale }`, `metadata { capo, bpm, ... }`. Validee par la MEME porte que l'import d'un fichier `.jamsong` dans l'application ; une forme invalide rend `422 unprocessable-entity` avec le motif en clair. Plafond DUR de 512 Ko (JSON serialise), sinon `413 payload-too-large`.
  - `playlistIds` string[]: Etat CIBLE COMPLET des appartenances. La chanson est ajoutee aux playlists citees et RETIREE de toutes les autres. Omis = les appartenances ne bougent pas.
  - `publish` boolean: Reserve : une CREATION ne publie jamais par defaut. Publier passe par `PATCH`, avec `publishDeclaration`.
  - `publishDeclaration` 'created' | 'imported_no_known_restriction' | 'arrangement'

## Response `200`

Chanson remplacee

- WriteAck: Accuse d'ecriture, identique sur les six routes qui en rendent un. Volontairement MINIMAL : l'identifiant pour adresser l'objet, et l'horodatage a renvoyer en `If-Match` a la prochaine ecriture. Relire l'objet complet se fait par `GET /me/songs/{songId}`, qui consomme du quota de LECTURE : ne pas l'imposer a chaque ecriture est delibere.
  - `id` string, required: Identifiant stable de l'objet ecrit.
  - `updatedAt` string, date-time, required: Horodatage serveur apres l'ecriture, en ISO 8601 UTC au millieme. C'est EXACTEMENT la valeur a renvoyer dans `If-Match`.
  - `published` boolean: Present UNIQUEMENT quand la requete portait `publish` : etat REEL de la publication apres l'ecriture. Un refus de publication n'est jamais un `published: false` silencieux, c'est un `409`.

## Other responses

- `201`: Chanson creee sous cet identifiant
- `400`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `401`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `403`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `404`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `409`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `413`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `415`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `422`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `429`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).

---

[API](https://skmtc.dev/jam-jam/apis/jam-jam-convert-api.md) · [All operations](https://skmtc.dev/jam-jam/apis/jam-jam-convert-api/llms.txt) · [OpenAPI document](https://skmtc.dev/jam-jam/apis/jam-jam-convert-api/revisions/64cd41a46e4e?raw)