API changelog

Every change to the Songbrain API, newest first. Changes inside /v1 are always backwards compatible; see the versioning policy below.

1. 2026-10-07v1.2Added

   Trust: know what is measured, send your own lyrics

   • Top-level provenance on every song document: which fields are measured, transcribed, model_estimate or generated, plus the list of confidence_fields. Docs
   • Scores are labelled as what they are: scores.*.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: optional 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). Docs
   • Genre consistency: tagline and sounds_like are now written from the final song_dna.genre, so they no longer contradict it.
   • All changes are additive. Existing fields keep their meaning.
2. 2026-10-07v1.1Added

   Production readiness

   • Request IDs: every response carries Songbrain-Request-Id, and every error body includes request_id. Docs
   • Validation errors use the standard error envelope: code invalid_request with an errors[] list of { field, message }. Unknown routes return not_found.
   • Rate-limit headers on every keyed request: 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 mode: "test": true returns a finished example analysis for free, including the song.done webhook. Docs
   • Webhooks: stable event id 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. Docs
   • Cursor pagination on GET /v1/songs (starting_after, has_more, next_cursor).
   • livemode on songs, list items and webhook events.
   • OpenAPI: security schemes, documented error responses and code samples for curl, Python and JavaScript.
   • Public 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.
3. 2026-10-06Changed

   best_moments: one clear reason

   • 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.
4. 2026-10-06v1.0Launch

   Public launch

   • Songs (POST /v1/songs, GET, DELETE), keyless examples, the beat-synced shot plan, signed webhooks, the MCP server and the Python and TypeScript SDKs.

Versioning policy

• /v1 is stable. We only add: fields, endpoints, headers, webhook events and enum values. Your client must ignore fields it doesn't know.
• Breaking changes only come in a new major path (/v2), with at least 6 months in which both versions run, and an email to every key owner.
• Deprecations are announced here and in a Songbrain-Deprecation response header on the affected calls.
• The response schema id 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.