---
title: "Label a passage through a share link"
method: POST
path: "/embed/media/{mediaId}/labels"
tags: ["Shared Links"]
---

# Label a passage through a share link

`POST /embed/media/{mediaId}/labels`

## Request

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

Label a passage through a dashboard share link. Allowed while labels are on with `labels.mode` set to `apply`. Word positions and `expectedTranscriptRevision` work as on `POST /media/{mediaId}/labels`, and a stale revision returns 409. Every label must be one the dashboard offers, or the request returns 400 "Choose labels this dashboard offers." Adding labels to the same words merges only into your own passage from this dashboard. 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

## 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.
  - `range` object, required: Inclusive range of word positions. Word positions count every word of the transcript in order, starting at 0. Within each sentence, words come from `entities` in order (an entity that holds several words, such as "New York", counts as several), or from the sentence `text` split on whitespace when the sentence has no entities. A token that is only punctuation is not counted.
    - `start` integer, required: Position of the first word. Integer, 0 or more.
    - `end` integer, required: Position of the last word, inclusive. Integer, at least `start`. A range that runs past the last word returns 400 "The selected words are outside this transcript."
  - `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)."
  - `expectedTranscriptRevision` integer, required: The `transcriptRevision` you read the transcript at. Integer, 0 or more. A stale value returns 409.

## 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`: Validation, range, label or limit problem
- `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)