> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyrcs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Review Flow

> End-to-end guide to the artist approval workflow

The review flow adds an artist approval gate between transcription and delivery. Results are held until an artist or rights holder confirms the lyrics are correct.

## End-to-end flow

<Steps>
  <Step title="Distributor submits job with review=true">
    ```json theme={null}
    POST /api/v1/transcribe
    {
      "audio_url": "https://cdn.example.com/song.mp3",
      "language": "Punjabi",
      "review": true,
      "webhook_url": "https://api.example.com/webhooks/lyrcs"
    }
    ```

    Returns `202 { "job_id": "...", "status": "queued", "review_required": true }`.
  </Step>

  <Step title="Transcription and alignment run (~90 seconds)">
    lyrcs.ai transcribes the audio, generates transliteration and translation, then time-aligns the lyrics. No action needed from the distributor during this phase.
  </Step>

  <Step title="job.awaiting_review webhook fires">
    ```json theme={null}
    {
      "event": "job.awaiting_review",
      "job_id": "a1b2c3d4-...",
      "language": "Punjabi",
      "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=abc123",
      "expires_at": "2024-01-02T00:00:00.000Z",
      "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-..."
    }
    ```

    The distributor receives this at their `webhook_url`.
  </Step>

  <Step title="Distributor routes review_url to artist">
    Extract `review_url` and forward it to the artist — by email, SMS, or your own platform's notification system. The artist does not need a lyrcs.ai account.
  </Step>

  <Step title="Artist reviews and approves">
    The artist visits the `review_url` and sees the full transcript, transliteration, and translation in the lyrcs.ai Studio. They can read through the lyrics and, if satisfied, click **Approve**.
  </Step>

  <Step title="job.complete fires with full results">
    ```json theme={null}
    {
      "event": "job.complete",
      "job_id": "a1b2c3d4-...",
      "language": "Punjabi",
      "results": {
        "transcript": "...",
        "transliteration": "...",
        "translation": "...",
        "cultural_notes": null,
        "downloads": {
          "lrc_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original",
          "lrc_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/transliterated",
          "srt_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/original",
          "srt_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/transliterated"
        }
      }
    }
    ```

    The distributor can now download and deliver the lyric files.
  </Step>
</Steps>

## Polling for review status

If you're polling rather than using webhooks, the `GET /api/v1/jobs/{id}` response includes review fields:

```json theme={null}
{
  "job_id": "a1b2c3d4-...",
  "status": "complete",
  "review_required": true,
  "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=abc123",
  "review_expires_at": "2024-01-02T00:00:00.000Z",
  "review_approved_at": "2024-01-01T14:22:00.000Z"
}
```

`review_approved_at` is `null` until approval. Once set, the job is approved and results are available.

## Known limitations

**review\_url is null until alignment completes**

The review URL and token are only generated after alignment finishes (\~90s). If you poll `GET /jobs/{id}` immediately after submission, `review_url` will be `null`. Wait for the `job.awaiting_review` webhook or poll until `review_url` is non-null.

**Single-attempt webhook delivery after approval**

The `job.complete` webhook fired after artist approval does not retry on failure — unlike the standard pipeline which retries at +1 min, +5 min, +30 min. Ensure your webhook endpoint is reliable. If you miss this delivery, poll `GET /jobs/{id}` — the `review_approved_at` field will be set and results will be available.

**Token expiry**

Review tokens expire. If the artist doesn't approve before `expires_at`, contact [support@lyrcs.ai](mailto:support@lyrcs.ai) to issue a new token.

## Review in batch jobs

Batch jobs support `review=true` per job:

```json theme={null}
{
  "webhook_url": "https://api.example.com/webhooks/lyrcs",
  "jobs": [
    { "audio_url": "https://cdn.example.com/song.mp3", "language": "Punjabi", "review": true }
  ]
}
```

Each job's `review_url` appears in `GET /api/v1/batch/{id}` responses once alignment completes. The `batch.complete` webhook fires when all jobs are done — note that `review=true` batch jobs are considered complete (for batch-counting purposes) as soon as alignment finishes, not after artist approval. This means `batch.complete` may fire before all artists have approved; individual `job.complete` webhooks fire per approval.