Lyric Scoring API Reference

Score lyrics synchronously

Submit lyrics and wait for the full 12-metric result (30-60s typical). For batch workloads prefer /score/async. Build 1964: optional `mode` query parameter — `mode=lite` skips triangulation + stranger test + webhook dispatch for high-throughput callers; `mode=full` (default) keeps the full pipeline.

Enqueue a scoring job

Returns 202 with a job id. Poll /score/jobs/{id} OR supply a webhookUrl and receive a POST when the job completes.

Fetch async job status + result

On first GET of a queued job by the owning key, runs the eval inline and returns the terminal result. Subsequent GETs return the cached row.

Score a single metric

Score lyrics on ONE of the 12 metrics in isolation (`specificity`, `emotional-truth`, `craft`, `prosody`, `imagery`, `narrative-arc`, `originality`, `voice`, `vulnerability`, `impact`, `transcendence`, `commerciality`). Same per-call cost as the full /score endpoint (no engine shortcut yet) but a tighter response when the caller only needs one axis.

8-voice adversarial critique (authenticated)

Submit lyrics to the 8-voice Crucible panel (Pat, Andrea, Chuck, Tobi, Tasha, Russell, Bex, J. Patrick). Returns the per-voice verdict + a verdict banner. Synchronous JSON variant of the SSE-streaming /api/crucible. Bearer-key auth + 60 req/hour rate-limit. For lower-friction integrations (Substack widgets, blog embeds), use /crucible/public.

8-voice critique (no auth, IP rate-limited)

NO-AUTH sibling of /crucible for the long tail of third-party tools (Substack widgets, AI music wrappers, blog embeds). Same Crucible panel + same reproducibility seal — only the throughput differs. **10 req / hour / IP** (vs 60 / hour / key on the authenticated tier). Lyrics cap **2500 chars** (vs 5000). CORS allows all origins. The 11th request hits 429 with a `retryAfter` field + a docs link to the authenticated tier.

CORS preflight

Compute voice-consistency fingerprint

Pure-statistics endpoint. Caller supplies per-song Voice (M8) scores (already produced via /score or /metric/voice); this endpoint computes mean / median / stddev / consistency band. No model in the loop — deterministic, free to call within the same 60/hr key budget. The math is general enough to publish so third-party tooling can answer "what does my fingerprint look like over 50 songs" without re-implementing it.

Full curated artist library

Returns the full curated artist library — every hand-authored brief the forge uses for artist-inspired mode. **No auth**. CDN-cacheable (s-maxage 24h + 1h SWR). 399+ entries as of this build. Single-entry mode: pass `?slug=ac-dc` to fetch one entry. The single-entry response has shape `ArtistLibrarySingleResponse` (returns 404 with `artist_not_in_library` for unknown slugs).

Random artist pick

Returns a fresh random entry from the curated artist library. `Cache-Control: no-store` so every call rolls anew. Surface use: discovery widgets, "surprise me" buttons, batch-mode random-artist seeds. **No auth**.

Audit a forge output against a brief

Score how faithfully a song output matches a structured brief. Components: premise alignment (Haiku-judged), anchor coverage, structure conformance, style constraints, forbidden-language compliance, chorus evolution, transcendence. Use when scoring a generated lyric against the prompt that produced it — answers "did the model do what the user actually asked for?" Cost: ~$0.0005 per call with default settings (one Haiku premise call + sync audits). Set `skipPremiseAudit: true` for pure-sync mode (<50ms, premise component returns null).

Search the Transcendent Line Library

Search across the 9,531-line audited corpus. Four modes — keyword (GIN tsvector), filter (structured facets only), semantic (kNN over text-embedding-3-large vectors), and hybrid (keyword + semantic via Reciprocal Rank Fusion, Cormack/Clarke/Buettcher 2009). All facets are URL query params; values are CSVs. Bad facet values are silently dropped (not 400'd) so a stale URL gracefully falls back to a broader search. Public read-only — no authentication.

Issue a signed badge URL

Returns an absolute /api/v1/badge URL with the HMAC signature query parameter already appended. Drop the `url` field directly into an `<img src="...">` tag — the badge SVG renders the score + verifies the signature server-side on each request. Use this when third parties want to display their SongForgeAI score on their own surface without exposing the signing secret.