carnet

Remplacer une chanson de mon carnet

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.

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

Path parameters

songIdstring required

Identifiant stable de la chanson au carnet (slug artiste-titre).

Headers

If-Matchstring

updatedAt ISO 8601 lu sur l'objet, avec ou sans guillemets ("2026-09-21T12:00:00.000Z" ou la forme nue). Si la valeur en base differe, l'ecriture est refusee par 409 conflict, dont le corps porte l'updatedAt serveur courant. Absent = dernier ecrivain gagne. If-Match: * n'est pas pris en charge (400).

Request body

songobject 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.

playlistIdsstring[]

Etat CIBLE COMPLET des appartenances. La chanson est ajoutee aux playlists citees et RETIREE de toutes les autres. Omis = les appartenances ne bougent pas.

publishboolean

Reserve : une CREATION ne publie jamais par defaut. Publier passe par PATCH, avec publishDeclaration.

publishDeclaration'created' | 'imported_no_known_restriction' | 'arrangement'

Response

Chanson remplacee

idstring required

Identifiant stable de l'objet ecrit.

updatedAtstring date-time required

Horodatage serveur apres l'ecriture, en ISO 8601 UTC au millieme. C'est EXACTEMENT la valeur a renvoyer dans If-Match.

publishedboolean

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.

Changes

No recorded changes to this operation across all 1 revision of this API.