POST /jobs/[id]/approve

Endpoint

POST https://lyrcs.ai/api/v1/jobs/{job_id}/approve

Approves a job held at a review gate, authenticated with your API key. No review link, no browser, no visit to lyrcs.ai — for when the artist reviews the lyrics inside your own product. This is one of two doors into the same held job. The other is our review page, reached through review_url. Both converge on the same approval and the same outputs. See Running Review In Your Own Product.

Request

Both fields are optional. Omit them to approve the lyrics unchanged.

curl -X POST https://lyrcs.ai/api/v1/jobs/{job_id}/approve \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lines": ["first line", "second line corrected", "third line"],
    "transliterated_lines": ["…", "…", "…"]
  }'

Field	Type	Notes
`lines`	`string[]`	Edited lines of the original script. Cannot be an empty array — omit it instead.
`transliterated_lines`	`string[]`	Edited transliteration. Position-parallel to `lines`.

The two scripts move together

Index 3 of transliterated_lines is the romanisation of index 3 of lines, and alignment inherits each transliteration’s timing from its original by index. When you add or remove a line, send both arrays — sending one alone with a different length is refused with 409 APR_005. The refusal exists because the alternative is silent: an uneven pair does not fail alignment, it produces a blank transliterated line, and a deletion shifts every remaining pair onto the wrong original for the rest of the song.

Text only, no timestamps

Timings are taken from the job, not from you. You have not run the aligner, so you have no measured timings to send, and anything an edit invalidates is re-derived from the audio on approval. Read the current lyrics from the review block on GET /jobs/{id} while the job is held.

Responses

Approved at the transcript gate — 200. The job is not finished; alignment now runs on the text you approved.

{
  "job_id": "a1b2c3d4-…",
  "status": "approved",
  "stage": "transcript",
  "lines_edited": 1,
  "transliteration_lines_edited": 1,
  "aligning": true,
  "message": "Approved. Alignment is running; poll GET /v1/jobs/{id} or wait for the job.complete webhook."
}

Approved at the aligned gate — 200. The job is finished.

{
  "job_id": "a1b2c3d4-…",
  "status": "approved",
  "stage": "aligned",
  "lines_edited": 1,
  "transliteration_lines_edited": 0,
  "alignment": "realigned"
}

alignment reports what happened to the timings, and is absent when no edit landed:

Value	Meaning
`realigned`	The edit was re-timed against the audio.
`word_timings_dropped`	Re-alignment was unavailable, so the now-incorrect word-level track was removed rather than returned stale. Line timings are unchanged.
`line_timings_unchanged`	The job had no word-level track to drop; line timings are unchanged.

Already approved — 200. Not an error.

{ "job_id": "a1b2c3d4-…", "status": "approved", "already_approved": true, "stage": "transcript" }

The first approval wins, whichever door it came through. Retrying after a timeout is safe: nothing is applied twice, nothing is re-aligned, nothing is charged.

Errors

Status	Code	Meaning
400	`APR_002`	`lines` or `transliterated_lines` was not an array of strings, or was empty
404	`NOT_001`	No such job, or it belongs to another organisation
409	`APR_001`	The job is not waiting for review
409	`APR_003`	The job was submitted with `review_delivery: "link"`, so it can only be approved from the review page
409	`APR_005`	`lines` and `transliterated_lines` would have different lengths
409	`REV_001`	Line count changed at the aligned gate and the timings cannot be re-derived
502	`APR_004`	The edits were saved but the job could not be released. Retry — the approval was rolled back

Rate limiting

Counted against your read limit, not your submission limit. A reviewed job draws one submission when you create it, and approving it is the second half of that same submission rather than a new one.

​Endpoint

​Request

​The two scripts move together

​Text only, no timestamps

​Responses

​Errors

​Rate limiting