---
title: "Change a passage's labels through a share link"
method: PATCH
path: "/embed/media/{mediaId}/labels/{mediaLabelId}"
tags: ["Shared Links"]
---

# Change a passage's labels through a share link

`PATCH /embed/media/{mediaId}/labels/{mediaLabelId}`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/embed/media/{mediaId}/labels/{mediaLabelId}`
- Auth: none required

Replace the labels on your own passage through a dashboard share link. Allowed while labels are on with `labels.mode` set to `apply`. Every label must be one the dashboard offers, or the request returns 400 "Choose labels this dashboard offers." Moving a passage and reviewing re-anchored passages stay in the app. No API key or access token: the share link `token` is the only credential. The media must be in one of the dashboard's folders. Every refusal returns the same `404 {"message": "Not found."}`, so a link holder cannot tell which check failed. The entry is recorded under `reviewerName` via this dashboard. The name is chosen by the link holder and not authenticated, the same as feedback; only a name the dashboard allows is accepted. A name can change or delete only the entries written under it from the same dashboard. Writes are limited to 30 requests a minute per IP address.

## Path parameters

- `mediaId` string, required
- `mediaLabelId` string, required

## Query parameters

- `token` string, required

## Request body

- object
  - `reviewerName` string, required: The name you write as: one of `annotationSettings.reviewers`, or any name when `allowOtherReviewer` is true. Chosen by the link holder and not authenticated. Trimmed; a listed name in another case is stored with the listed spelling. Required.
  - `labelIds` string[], required: Labels to put on the passage. 1 to 20 ids, no repeats. Each must be an active label (not a group) in your company, or the request returns 400 "Choose active labels from this workspace (groups cannot be applied)."

## Response `200`

Success

- object
  - `status` 'success': `success` on every 2xx response.
  - `data` object: Labels on one passage of a transcript.
    - `mediaLabelId` string: Id of the labelled passage.
    - `mediaId` string: Id of the media.
    - `labelIds` string[]: Labels on the passage.
    - `anchor` object: Where the passage sits in the transcript. Built by the server from the word range you send.
      - `startWord` integer: Position of the first word.
      - `endWord` integer: Position of the last word, inclusive.
      - `exact` string: The quoted words, joined by single spaces.
      - `prefix` string: Up to 32 characters of transcript text before the quote.
      - `suffix` string: Up to 32 characters of transcript text after the quote.
      - `startInSec` number: Start time of the first word, in seconds.
      - `endInSec` number: End time of the last word, in seconds.
      - `speakerIds` string[]: Speakers of the quoted words.
      - `transcriptRevision` integer: The transcript revision these positions refer to.
    - `status` 'active' | 'shifted' | 'needs_review': `active`: the same words, possibly at new positions after an edit. `shifted`: most of the words survived an edit near the same time, but the text changed. `needs_review`: the words changed too much to follow; `anchor` then holds a suggested passage on the new transcript and `lastResolved` the last position a person confirmed.
    - `lastResolved` object: Present only while `status` is `needs_review`: the last position a person confirmed.
      - `startWord` integer: Position of the first word.
      - `endWord` integer: Position of the last word, inclusive.
      - `exact` string: The quoted words, joined by single spaces.
      - `prefix` string: Up to 32 characters of transcript text before the quote.
      - `suffix` string: Up to 32 characters of transcript text after the quote.
      - `startInSec` number: Start time of the first word, in seconds.
      - `endInSec` number: End time of the last word, in seconds.
      - `speakerIds` string[]: Speakers of the quoted words.
      - `transcriptRevision` integer: The transcript revision these positions refer to.
    - `createdAt` string, date-time: When it was created.
    - `updatedAt` string, date-time: When it last changed.
    - `authorName` string: The author's display name: the name a share-link viewer wrote as, or the team member's name, or "Team member" when a member has none or has left the company.

## Other responses

- `400`: The body broke a rule or failed validation
- `404`: Any refusal: unknown or revoked token, expired subscription, the setting is off, view mode on a write, media outside the link, a name that is not allowed, or someone else's entry
- `409`: The transcript changed since you read it
- `429`: Rate limit reached

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)