API Documentation

Health check endpoint. Returns the application status and version.

Parameters

None

Response

{
  "status": "ok",
  "version": "1.0"
}

Returns all 16 arrangement styles with their names, descriptions, and available sub-variants.

Parameters

None

Response

{
  "hymn-block": {
    "name": "Hymn Block",
    "description": "Classic four-part hymn texture...",
    "variants": {
      "modern": {
        "name": "Modern",
        "description": "Contemporary voicings..."
      }
    }
  },
  "gospel": { ... },
  "bach-chorale": { ... }
}

Returns all available ensemble types for orchestration, with names, instrument parts, and descriptions.

Parameters

None

Response

{
  "quartet": {
    "name": "String Quartet",
    "parts": "Violin I, Violin II, Viola, Cello",
    "description": "The classic chamber ensemble..."
  },
  "trio": { ... },
  "piano-trio": { ... },
  "wind-quintet": { ... },
  "brass-quintet": { ... },
  "custom": { ... }
}

Returns orchestration style details including name, description, features list, and suggested tempo.

Parameters

None

Response

{
  "baroque": {
    "name": "Baroque",
    "description": "Contrapuntal lines, terraced dynamics...",
    "features": ["Detache articulation", "Trills & mordents", ...],
    "tempo": "Andante"
  },
  "classical": { ... },
  "romantic": { ... },
  "impressionist": { ... }
}

Returns the library of built-in sample scores. These are public domain melodies you can use for testing without uploading your own files.

Query Parameters

Example

GET /api/samples?category=choral

Response

[
  {
    "id": "amazing-grace",
    "title": "Amazing Grace",
    "composer": "Traditional",
    "category": "choral",
    "suggested_style": "hymn-block"
  },
  ...
]

Download a sample score as a MusicXML file. The id comes from the /api/samples listing.

URL Parameters

Response

Binary MusicXML file download (.mxl). On error, returns JSON with an "error" field.

Example

GET /api/samples/amazing-grace/file

Generates and returns a demo MIDI file (base64-encoded) for a given arrangement style. Used by the Styles page for audio previews. Results are cached on the server.

URL Parameters

Query Parameters

Response

{
  "midi_b64": "TVRoZAAAAAYAAQAC..."
}

Generate a piano accompaniment from an uploaded melody. Returns download URLs for the arranged score and MIDI.

Content Type

multipart/form-data

Form Parameters

Example (curl)

curl -X POST https://clarascore.app/api/arrange \
  -F "file=@melody.mxl" \
  -F "style=gospel" \
  -F "intro=on" \
  -F "target_key=G"

Response

{
  "job_id": "a1b2c3d4",
  "style": "gospel",
  "original_name": "melody.mxl",
  "download_url": "/download/a1b2c3d4/melody_gospel_arranged.mxl",
  "midi_url": "/midi/a1b2c3d4/melody_gospel_arranged.mxl"
}

Orchestrate a piano score for a chamber ensemble. Returns download URLs for the ensemble score and MIDI.

Content Type

multipart/form-data

Form Parameters

Example (curl)

curl -X POST https://clarascore.app/api/orchestrate \
  -F "file=@piano-score.mxl" \
  -F "style=romantic" \
  -F "ensemble=wind-quintet"

Response

{
  "job_id": "e5f6g7h8",
  "style": "romantic",
  "ensemble": "wind-quintet",
  "ensemble_name": "Wind Quintet",
  "original_name": "piano-score.mxl",
  "download_url": "/download/e5f6g7h8/piano-score_romantic_wind5.mxl",
  "midi_url": "/midi/e5f6g7h8/piano-score_romantic_wind5.mxl"
}

Generate SATB or SAB vocal harmonization from a single melody line. Returns download URLs for the harmonized score and MIDI.

Content Type

multipart/form-data

Form Parameters

Example (curl)

curl -X POST https://clarascore.app/api/harmonize \
  -F "file=@melody.mxl" \
  -F "voices=satb" \
  -F "target_key=Eb"

Response

{
  "job_id": "i9j0k1l2",
  "voices": "satb",
  "target_key": "Eb",
  "original_name": "melody.mxl",
  "download_url": "/download/i9j0k1l2/melody_satb_harmonized.mxl",
  "midi_url": "/midi/i9j0k1l2/melody_satb_harmonized.mxl"
}

Upload a score and get style recommendations based on its key, tempo, meter, and note density. Returns up to 5 suggestions ranked by fit score.

Content Type

multipart/form-data

Form Parameters

Example (curl)

curl -X POST https://clarascore.app/api/recommend-styles \
  -F "file=@melody.mxl"

Response

{
  "key": "G major",
  "mode": "major",
  "time_signature": "4/4",
  "tempo_bpm": 100,
  "measures": 16,
  "density": 4.5,
  "recommendations": [
    {
      "style": "hymn-block",
      "reason": "Simple meter, short form — classic hymn texture",
      "score": 90
    },
    {
      "style": "gospel",
      "reason": "Major key, 4/4 time — natural gospel feel",
      "score": 85
    }
  ]
}

Analyze lyrics to detect their poetic meter and return matching hymn tunes from a library of 74 public domain melodies.

Content Type

application/json

JSON Body

Example (curl)

curl -X POST https://clarascore.app/api/hymn-setting/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "Amazing grace how sweet the sound\nThat saved a wretch like me"}'

Response

Returns detected meter, syllable counts, and an array of matching tunes with their names, meters, and keys.