--- title: "Comment through a share link" method: POST path: "/embed/media/{mediaId}/comments" tags: ["Shared Links"] --- # Comment through a share link `POST /embed/media/{mediaId}/comments` ## Request - Base URL: `https://api.speakai.co/v1` - URL: `https://api.speakai.co/v1/embed/media/{mediaId}/comments` - Auth: none required Start a thread or reply through a dashboard share link. Allowed while comments are on with `comments.mode` set to `reply`. Send `range` with `expectedTranscriptRevision` to comment on a passage, `parentId` to reply, or neither to comment on the whole file. `mediaLabelId` is not accepted here. 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. - `body` string, required: Comment text. Trimmed, then 1 to 5,000 characters. - `range` object: The passage to comment on. Send it with `expectedTranscriptRevision`; leave both out for a whole-file comment. Not allowed on a reply. 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." - `expectedTranscriptRevision` integer: Required when you send `range`, not allowed without it. The `transcriptRevision` you read the transcript at. Integer, 0 or more. A stale value returns 409. - `parentId` string: `commentId` of the thread's first comment, to post a reply. Trimmed, then 1 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-` (pattern `^[A-Za-z0-9_-]{1,64}$`). Anything else returns 400. ## Response `200` Success - object - `status` 'success': `success` on every 2xx response. - `data` object: A comment. - `commentId` string: Id of the comment. - `mediaId` string: Id of the media. - `anchor` object, nullable: The passage the comment is on, or `null` for a comment on the whole file. Replies carry `null`. - `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. - `parentId` string, nullable: `commentId` of the thread's first comment for a reply, `null` for the first comment. - `body` string: Comment text. Empty on a deleted first comment that still has replies. - `status` 'active' | 'shifted' | 'needs_review': Present only on comments with an anchor. `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. - `isResolved` boolean: `true` once the thread is resolved. Only set on the first comment of a thread. - `isDeleted` boolean: `true` on a deleted first comment kept because it has replies. - `createdAt` string, date-time: When it was posted. - `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, reply depth, range 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)