Every change to the Songbrain API, newest first. Changes inside /v1 are always backwards compatible; see the versioning policy below.
scores.virality.score is now calibrated so typical songs land around 75 and genuinely catchy songs can reach 90 (capped at 98). Before, scores topped out around 89, so 90 was out of reach. The median is about the same, the spread is wider.scores.quality.score and scores.lyrics.score are not calibrated yet and can come out a few points lower than before. Their order between songs is unchanged.mode on POST /v1/songs: "full" (default, 25 credits ≈ $0.50) returns everything as before; "dna" (10 credits ≈ $0.20) returns song_dna, timeline, best_moments, lyrics and scores, without story and shot_plan. The 5 free songs a month cover either mode. DocsPOST /v1/songs/{id}/direction: adds the story and the beat-synced shot plan to a finished dna song from the existing analysis, no new upload. 15 credits, refunded if it fails. A second song.done webhook arrives with its own id and data.direction_added: true.mode. A dna document has a direction object (what the upgrade adds, its price). GET /v1/songs/{id}/shot-plan on a dna song answers 409 no_direction.GET /v1/pricing has modes and add_direction; GET /v1/account has prices. price_per_song_* keep meaning the full price. GET /v1/examples/{id}?mode=dna shows the Song DNA view without a key.analyze_song takes mode; new tool add_video_direction. SDKs 0.4.0: mode= on analyze and add_direction().mode nothing changes for existing integrations.provenance on every song document: which fields are measured, transcribed, model_estimate or generated, plus the list of confidence_fields. Docsscores.*.basis: "model_estimate" and a one-sentence scores.basis_note. An AI model's listening judgement, good for comparing songs, not a measurement or a view forecast.lyrics (plain text, up to 20,000 characters) on POST /v1/songs and the MCP tool analyze_song. Your exact words are placed on the transcription's timing; words the singer can't be heard on are left out, never guessed. New lyrics.source (transcribed · provided_lyrics · suno_lyrics), lyrics.note, lyrics.alignment and lyrics.lines[].confidence (0–1, null when not transcribed). Docstagline and sounds_like are now written from the final song_dna.genre, so they no longer contradict it.Songbrain-Request-Id, and every error body includes request_id. Docsinvalid_request with an errors[] list of { field, message }. Unknown routes return not_found.X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.Idempotency-Key on POST /v1/songs: a retry with the same key within 24 h returns the original song and is not charged again. Docs"test": true returns a finished example analysis for free, including the song.done webhook. Docsid for de-duplication, Songbrain-Event-Id and Songbrain-Event-Type headers, up to 10 attempts over about 3 days, POST /v1/webhooks/test and GET /v1/webhooks/deliveries. DocsGET /v1/songs (starting_after, has_more, next_cursor).livemode on songs, list items and webhook events.GET /v1/status and the status page with 90-day uptime history. New security page with the sub-processor list, and a self-serve DPA.best_moments[].reason (one sentence) and signals[] (the measured audio signals) replace why, explanation and judge_note.platform_fit, caption_ideas and hashtags were removed. This cleanup happened before the first customer integration, so no live integration was affected.POST /v1/songs, GET, DELETE), keyless examples, the beat-synced shot plan, signed webhooks, the MCP server and the Python and TypeScript SDKs./v1 is stable. We only add: fields, endpoints, headers, webhook events and enum values. Your client must ignore fields it doesn't know./v2), with at least 6 months in which both versions run, and an email to every key owner.Songbrain-Deprecation response header on the affected calls.songbrain.song/1 changes only with a major version.Watching for changes? This page is the source of truth; the SDK release notes on GitHub follow it.