Labels

Change, confirm or move a labelled passage

Requires the Labels: Assign permission. Send exactly one of labelIds or action; both or neither returns 400.

  • labelIds replaces the passage's labels, with the same rules as when you label a passage.
  • action: "keep" confirms the passage where it is now: status becomes active and lastResolved is cleared. Use it on a shifted passage, or to accept the suggestion on a needs_review one. It returns 409 if the passage is still on an older revision, which happens for a moment after a save.
  • action: "replace" moves the passage to new words. It needs range and expectedTranscriptRevision, which are not allowed with any other choice. 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.

Errors

  • 400 when the body breaks the rules above, the range runs past the transcript, or a label cannot be applied.
  • 403 without the permission.
  • 404 when the media or the labelled passage does not exist.
  • 409 when the revision is stale.
patch/media/{mediaId}/labels/{mediaLabelId}

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/media/{mediaId}/labels/{mediaLabelId}
  • 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.

mediaLabelIdstring required

Id of the labelled passage, from mediaLabelId. 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

labelIdsstring[]

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)."

action'keep' | 'replace'

keep to confirm the current position, replace to move the passage.

expectedTranscriptRevisioninteger

Required with action: "replace", not allowed otherwise. The transcriptRevision you read the transcript at. Integer, 0 or more. A stale value returns 409.

Response

Success

status'success'

success on every 2xx response.

Changes

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