Developer docs

Correct a song’s brief

MCP tool
edit_song_brief
CLI
kinetune songs edit-brief
PATCH/api/v1/songs/{song_id}/brief

Not sent from the docs: it changes your workspace. Run it with curl, the CLI or its MCP tool.

Rewrite what the song is about, in the user’s words

The brief (get_song: brief) is what every director reads before making anything for the song: its theme, the story under it, how the feeling moves through its sections (mood_arc), the setting it evokes and its tone. When it reads the song wrong ("it’s about my father, not a breakup"), send the fields to change; the others stay. mood_arc replaces the whole list (a section with an empty feeling is dropped); null or "" clears tone, story or setting; theme can’t be emptied. Plain text, on one line each. The correction is the user’s: brief.edited is true, every video, Canvas and cover made from then on reads it, and nothing replaces it (new lyrics or a new analysis keep it) until rewrite_song_brief. 409 while a song without a brief yet is sent no theme.

headerAuthorizationBearer <token>

An organization API key (kt_live_…) or an OAuth access token

song_id*string

The song id

Length1 <= length <= 120
application/json
  1. body
theme?string

What the song is about, in a sentence

Lengthlength <= 400
tone?|

Its register, in a few words (tender, comic parody, defiant…)

story?|

The story or situation under the words: who it is about, what happens

setting?|

An era, a place or a scene it evokes

mood_arc?array<>

How the feeling moves through the song, section by section: replaces the whole list

Itemsitems <= 40

Response Body

OK

application/json
  1. response
status*string

writing: being written (the fields are null until ready)

Value in"writing""ready"
theme*|

What the song is about, in a sentence

tone*|

Its register, in a few words

story*|

The story or situation under the words (null for a mood piece)

mood_arc*array<>

How the feeling moves through it, section by section

setting*|

An era, a place or a scene it evokes (null when none)

edited*boolean

The user corrected it: directors read their version, and nothing replaces it until rewrite_song_brief

updated_at*string|null
[key: string]?unknown
Example Request
curl -X PATCH 'https://kinetune.com/api/v1/songs/string/brief' \
  -H 'Content-Type: application/json' \
  -d '{}'
Example Response
{
  "status": "writing",
  "theme": "string",
  "tone": "string",
  "story": "string",
  "mood_arc": [
    {
      "section": "string",
      "feeling": "string"
    }
  ],
  "setting": "string",
  "edited": true,
  "updated_at": "string",
  "property1": null,
  "property2": null
}