---
title: "Create transcript highlight"
method: POST
path: "/v1/highlights"
tags: ["Highlights"]
---

# Create transcript highlight

`POST /v1/highlights`

Create a highlight on a transcript by specifying start and end timestamps in seconds.

The data entry (referenced by `note_id`) must contain an audio or video transcript for the highlight to be created.
If the entry contains multiple audio/video elements, the first transcript is used.

**Tip:** to get word-level timestamps for picking `start_time` and `end_time`, pair this endpoint with **Export data** (`GET /v1/data/:data_id/export/html`). The HTML export wraps each transcript word in a `<span>` carrying `data-monologue-start-time` and `data-monologue-end-time` attributes; the markdown export only includes paragraph-level timestamps. Bounds are snapped to the nearest word, so `start_time` / `end_time` returned by **Get highlight** / **List highlights** can be sent back here unchanged.

Returns the created highlight.

> 🚧 Permissions
>
> Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

## Request body

- object
  - `note_id` string, required — Unique identifier of the data entry (note) containing the transcript.
  - `start_time` number, required — Start time in seconds within the transcript to begin the highlight.
  - `end_time` number, required — End time in seconds within the transcript to end the highlight.
  - `tag_ids` string[] — Optional list of tag IDs to associate with the highlight.

## Response `201`

201

- object
  - `data` object, required
    - `id` string, required
    - `url` string, nullable — The URL of the parent note containing this highlight in the Dovetail web app. This field is experimental and may change without notice.
    - `note_id` string, nullable, required
    - `tags` object[], required
      - `id` string, required
      - `title` string, required
    - `text` string, nullable, required
    - `type` 'highlight', required
    - `start_time` number, nullable, required
    - `end_time` number, nullable, required
    - `created_at` string, required
    - `updated_at` string, required

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/versions/4107f5fdf8b2/schema)