Jam Jam

Returns, in one call, what the calling Jam Jam identity is allowed to do and how much of each allowance is left. THREE INDEPENDENT COUNTERS, they never borrow from one another: `conversion` (10 per week on a free account, 500 per calendar month on Premium, 3 per 24h anonymous), `read` (2000 per UTC day free, 20000 Premium, spent by the notebook and social listing tools) and `write` (200 per UTC day free, 5000 Premium, spent by the notebook writing tools). `scopes` lists the permissions of the API key in use. Call this before a batch, and after a quota error to learn when it resets. Costs nothing itself.

Uploads a local file (path, or base64 content) to the Jam Jam API, waits for the conversion to finish, and returns the result: embedded text for small text formats (ChordPro, .lrc, .lab...), or a local file path for binary formats (PDF, MIDI, MP4...). Call jj_list_formats first to find valid "output" ids for your input. Consumes one unit of the conversion quota (10/week free, 500/month Premium, see jj_check_usage), which is a different counter from notebook reads and writes.

Sends plain text or ChordPro (pasted lyrics and chords, no file) to the Jam Jam API, waits for the conversion to finish, and returns the result: embedded text for small text formats, or a local file path for binary formats (PDF, MIDI...). Call jj_list_formats first to find valid "output" ids. Consumes one unit of the conversion quota.

Creates a playlist in the calling account's notebook. Playlists are flat and allow multi-membership: a song can be in several of them. `songIds` is the ordered content and every id must be a live song of this account. Consumes one unit of the daily write quota.

Adds a song to the calling account's PRIVATE notebook. `song` is the canonical pivot payload: exactly the object returned by jj_get_song (`song`) or by a conversion whose output is "songbook", so converting then filing is a copy with no transformation. The id is DERIVED, never random: `song.id` if given, otherwise an "artist-title" slug. That means posting the same song twice REPLACES it instead of creating a duplicate, and it is also how you rewrite a song wholesale (read it with jj_get_song, edit the payload, post it back with its id). Adding NEVER publishes anything on the public profile. Consumes one unit of the daily WRITE quota (200/day free, 5000 Premium).

Deletes a playlist, and ONLY the playlist: its songs stay in the notebook and in their other playlists. Idempotent, and an unknown id succeeds too. If the playlist was published on the profile, that published copy disappears.

Deletes a song from the calling account's notebook. Idempotent: deleting twice succeeds twice, and an unknown id succeeds too (saying "no such song" would leak whether it exists in someone else's notebook). Side effects are the same as deleting in the app: the song leaves all its playlists, its published copy disappears from the profile, and accounts that had imported it are notified. This cannot be undone from the API: confirm with the person before calling it.

Fetches the current state of a conversion job by id: phase (queued/running/done/failed/cancelled), per-step progress, and the list of artifacts once done. Use this to check on a job after jj_convert_file or jj_convert_text stopped waiting for it.

Returns one playlist of the calling account's notebook with its songs in summary form, in playlist order, paginated by the same opaque cursor. A song the playlist still references but that has since been deleted from the notebook is simply skipped.

Returns the profile card of a Jam Jam account designated by its public @handle, seen from the calling account: display name, bio, avatar, visibility (public/private), follower and following counts, and `relation` (none / following / follower / mutual / requested / self). A PRIVATE account the caller does not follow returns a closed card without bio or counts. An unknown handle returns not-found. Jam Jam is a host: this never ranks or recommends anyone, and never exposes somebody else's audience figures.

Returns one song of the calling account's notebook in full: the summary fields AND `song`, the canonical pivot payload (sections, lines, chords with their offsets, lyrics, detectedKey, metadata). That payload is exactly what jj_create_song and jj_update_song accept, so reading then writing back is a copy, not a translation. An unknown id and an id belonging to another account both return the same not-found error.

Lists the calling account's own followers, newest first. status="requested" lists the follow requests it has not accepted yet. Only the caller's own relations are readable; reading somebody else's followers is not offered by this API.

Lists the accounts the calling account follows, newest first. status="requested" lists the requests it has sent to private accounts and that are still pending. Following and un-following are done in the Jam Jam application, never by API.

Lists the input and output formats actually served by the Jam Jam API right now (GET /formats), with their limits (maxBytes, maxPages, maxDurationS) and whether they require an account or Premium. Call this FIRST, before jj_convert_file or jj_convert_text, to know which output ids are valid for a given input. Pass "input" to get the exact list of possible outputs for that one input format. Needs no API key.

Lists the playlists of the calling account's notebook. Playlists are FLAT and allow multi-membership: `songIds` is the ORDERED list of song ids, and one song can appear in several playlists. Same cursor pagination and same updatedSince incremental filter as jj_list_songs. Consumes one unit of the daily read quota.

Lists the playlists an account has published on its profile. Same visibility rules as jj_list_profile_songs. `songCount` already counts only what the caller is allowed to see: a published playlist hides the songs its author did not publish.

Lists the songs an account has chosen to publish on its profile, newest first, with cursor pagination. `hasAudio` and `audioPlayable` are only ever true between accounts that follow each other MUTUALLY: without that link the very existence of a backing track is withheld, and no endpoint serves audio at all. A private account you do not follow refuses the call; an unknown handle returns not-found. Consumes one unit of the daily read quota.

Lists the songs in the calling account's PRIVATE Jam Jam notebook, page by page, oldest update first. fields="summary" (default) gives id, title, artist, key, capo, bpm, playlistIds and updatedAt; fields="full" adds the complete pivot payload (chords, lyrics, sections) and lowers the page cap to 25. Use the returned nextCursor to get the next page, and stop when it is null. Consumes one unit of the daily READ quota (2000/day free, 20000 Premium), never a conversion.

Changes one or more fields of a playlist: `name`, `coverEmoji` (null removes it), and `songIds`, which REPLACES the whole content and its order. Only the fields you pass move. To reorder, read the playlist with jj_get_playlist first and send the full list back in the new order.

Changes some fields of one song of the calling account's notebook. Only the fields you pass move; a field set to null erases its value. `key` is the DISPLAYED key ("G", "Am"). `playlistIds` is the complete target membership, so it is idempotent. `publish: true` puts the song on the account's public profile and requires `publishDeclaration` the first time, plus a public username; `publish: false` removes it and has no conditions. Publishing is a deliberate act by the account holder: never publish unless they asked. To rewrite lyrics, chords or structure, use jj_create_song with the song's id instead.