Comments

Post a comment or reply

Requires the Comments: Create permission (on by default for admins and members). The media must belong to your company and be one you can open. Owners and members with the folder Access all permission can open any file; everyone else can open files in folders assigned to them or their groups, and files they own. Any other media returns 404, the same as a media id that does not exist.

Three kinds of comment

  • On a passage: send range and expectedTranscriptRevision together. expectedTranscriptRevision is the transcriptRevision you read the transcript at, from GET /media/transcript/{mediaId}, GET /media/insight/{mediaId}, or the list endpoints on this page. The server builds the anchor from its own copy of the transcript. If the transcript has been saved since, the request returns 409 "This transcript changed since you opened it. Reload to keep editing." and nothing is written: read the transcript again and recompute the word range.
  • On the whole file: leave out both range and expectedTranscriptRevision.
  • A reply: send parentId, the commentId of a thread's first comment. A reply cannot carry range or mediaLabelId; it belongs to its thread. Replies go one level deep, so replying to a reply returns 400.

Add mediaLabelId to link a new thread to a labelled passage on the same media.

A reply sends an in-app notification to the person who started the thread, unless they wrote the reply. A transcript holds at most 5,000 comments on passages; whole-file comments and replies are not counted.

Errors

  • 400 when a field fails validation, the rules above are broken, the range runs past the transcript, or the limit is reached.
  • 403 without the permission.
  • 404 when the media, the parent comment or the labelled passage does not exist.
  • 409 when expectedTranscriptRevision is stale.
post/media/{mediaId}/comments

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/media/{mediaId}/comments
  • Auth: API key in header x-speakai-key and API key in header x-access-token

Path parameters

mediaIdstring required

Id of the media file. 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.

Request body

bodystring required

Comment text. Trimmed, then 1 to 5,000 characters.

expectedTranscriptRevisioninteger

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.

parentIdstring

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.

mediaLabelIdstring

A labelled passage on this media to link the thread to. Not allowed on 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

Success

status'success'

success on every 2xx response.

Changes

No recorded changes to this operation across all 2 revisions of this API.