> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/voice-notes/openapi.json](/docs/api/voice-notes/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Voice notes

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

Voice notes are the audio messages Kenso records for a contact: the LinkedIn notes a voice note step records, and the iMessage notes Ken writes and speaks for a person who replied on iMessage (`POST /v1/voice-notes`, while the workspace's `imessage` feature is on). Touches show each note as a `voiceNote` object with its status, and with an `audioUrl` while its audio is stored, and LinkedIn thread messages and the LinkedIn messages in account activity show their notes the same way. An iMessage thread message names its note in `imessage.voiceNoteId` instead, and `GET /v1/voice-notes/{voiceNoteId}/imessage-audio` plays it, whether a member or a workflow sent it. `GET /v1/voice-notes/{voiceNoteId}` reads only a note made with `POST /v1/voice-notes` (its status and the touch or thread it was made for): any other note is `404`. Play the audio with this section's calls.

Copy and personalization. 4 endpoints under `https://api.ken.so`. Every request sends `Authorization: Bearer <your API key>` and `Ken-Version: 2026-11-02`: see [Authentication](/docs/authentication.md), [Workspaces](/docs/workspaces.md) and [Errors](/docs/errors.md). OpenAPI for this resource only: [/docs/api/voice-notes/openapi.json](/docs/api/voice-notes/openapi.json).

- `POST /v1/voice-notes` - Make an iMessage voice note for a person (`voice-notes.create`): [/docs/api/voice-notes/create.md](/docs/api/voice-notes/create.md)
- `GET /v1/voice-notes/{voiceNoteId}` - Get an iMessage voice note (`voice-notes.get`): [/docs/api/voice-notes/get.md](/docs/api/voice-notes/get.md)
- `GET /v1/voice-notes/{voiceNoteId}/imessage-audio` - Open the audio of a voice note on an iMessage text (`voice-notes.imessage-audio`): [/docs/api/voice-notes/imessage-audio.md](/docs/api/voice-notes/imessage-audio.md)
- `GET /v1/voice-notes/{voiceNoteId}/audio` - Get a voice note's audio (`voice-notes.audio`): [/docs/api/voice-notes/audio.md](/docs/api/voice-notes/audio.md)

## Make an iMessage voice note for a person

`POST /v1/voice-notes` - operationId `voice-notes.create`

| Permission | Rate limit |
| --- | --- |
| Inbox edit | 240 requests a minute per API key |

Ken writes a voice note for the person and Kenso speaks it in `voice` right away. Nothing is sent. A member
sends the note as the `voiceNoteId` of a reply on the person's iMessage thread
(`POST /v1/threads/{threadId}/messages`). An agent or an API key sends it on one of the person's iMessage
touches instead (make it with `touchId`, or set the touch's `voiceNoteId`), which a member approves: a
reply that carries a `voiceNoteId` from an agent or an API key is refused with `403 forbidden`
(`imessage_agent_voice_note`). Only a person who replied in an iMessage thread can get one, and an SMS thread
carries text only. The note costs credits (`imessage_voice_note`), which count toward your monthly credit limit
in the workspace.

Pass `touchId` to make the note for one of the person's iMessage touches. The note is then judged on the
thread that touch goes on (a reply's own thread, else its thread on the line the touch sends from; a warm path hop's,
on its approver's line), and Ken writes it on that thread's messages. The note names only its touch, not that
thread. The touch shows it in `imessage.voiceNoteInProgress` while it is being made, and a call for a touch
whose note is still being made returns that note (status `generating`) without making or charging another.
When the note is ready it goes on the touch as its `voiceNoteId`, as your own edit of the touch, if the touch
is still open (planned, drafted, awaiting approval or failed), carries no images and has no voice note, and nobody
changed it while the note was made, even when you stopped waiting for this call. Otherwise the note is kept, and
charged, for you to put on a touch yourself, unless the touch was sent, skipped or deleted meanwhile: then the note
fails with `touch_ended` and is not charged.

Pass `threadId` (a `thr_` id) to make the note for one of the person's iMessage threads, such as the one
a member has open in the inbox to reply with it. The note is then judged on that thread instead of the person's latest iMessage thread, the thread
shows it in `imessage.voiceNoteInProgress` while it is being made, and a call for a thread whose note is still
being made returns that note (status `generating`) without making or charging another. Send `touchId` or
`threadId`, not both. With neither, the note is made for the latest thread on the person's mobile number: it is
judged on that thread, its `threadId` is that thread, and a call while that thread's note is still being made
returns that note.

The note is made for iMessage: it goes only on an iMessage text, never on a LinkedIn, Facebook or WhatsApp message.

Returns `201` with the voice note: status `ready` with its `audioUrl`, or `failed` with its
`failureReason` when the note could not be finished (or `generating` for a note already being made). The
call waits while the note is made. The note names the `touchId` or the `threadId` it was made for (with
neither sent, the person's latest thread), the member who asked for it (`createdByMemberId`), and
`createdAt` and `readyAt`, as `GET /v1/voice-notes/{voiceNoteId}` returns them. When the call timed
out on your side, the thread's `imessage.voiceNoteInProgress` or `imessage.voiceNoteReady` names the note.

Errors:

- `400 validation_failed`: `personId` or `voice` is missing or invalid, the voice is not available
in this workspace, or the person has not replied in an iMessage thread (detail `recipient_must_reply`) or
texts on SMS (detail `sms_thread`). With a `touchId`, those two details are on `touchId`, and a
touch on another channel is `not_allowed`, one already sent or skipped `touch_ended` and one for another
person `wrong_person` (nothing is written, spoken or charged). When the touch is sent, skipped or deleted
while its note is made, the call returns `201` with the note `failed` (`failureReason`
`touch_ended`), nothing is charged and the note can't be sent. With a
`threadId`, they are on `threadId`: a value that is not a thread id is `invalid`, a thread on another
channel or a `threadId` sent with a `touchId` `not_allowed`, and a thread with another person
`wrong_person`.
- `402 member_credit_limit_reached`: you reached your monthly credit limit in this workspace. The refusal is
in `error.refusal` and in the top-level `refusal`. Nothing is written, spoken or charged.
- `403 permission_denied`: you do not have Inbox edit, or you are a member with the Client role.
- `404 not_found`: no person has this id in the workspace, no touch you can see has the `touchId`, or no
iMessage thread in the workspace has the `threadId`.
- `409 invalid_state` with detail `phone_opt_out`: the number the note would go to texted STOP, or the
person opted out of texts. With detail `do_not_call`: a provider the
workspace's own key asked flagged the person do not call. With detail `suppressed:<reason>` (such as `suppressed:blocklisted`): the
person is on the blocklist, on do-not-contact or unsubscribed, or (with a `touchId`) a domain of the touch's
account is on the blocklist, as the text's send reads it. The detail is on the field that named the thread
(`threadId`, `touchId`, else `personId`), and a reply to that number is refused the same way,
except that a member may still reply for `do_not_call` alone in a thread where the person has written. This
comes before every other refusal below, except `503 voice_notes_unavailable` while voice notes are off on
Kenso's side, for every caller and every `wordsMode`: Kenso does not text this person. Nothing is written,
spoken or charged.
- `409 imessage_line_owner_left`: the owner of the line the note would go out on (the thread's line, or the
line the touch sends from) can't send from it anymore, as a reply or a touch's approval on that line is refused.
An admin can give the line a new owner in Delivery. Nothing is written, spoken or charged.
- `409 imessage_line_gone`: that line can no longer send (it was released, failed or never activated), as a
reply on that thread is refused: nothing goes on the thread again. Nothing is written, spoken or charged.
- `409 person_refused` on `personId`: the person said no and nothing since takes it back (a classed reply
that is no refusal, an accepted connection or a booked meeting), and an agent or an API key asked for the note
(any `wordsMode`) or Ken would write its words (`wordsMode` `ken_writes`, for anyone). A member can
still make one with their own `script`. Nothing is written, spoken or charged.
- `503 service_unavailable` with detail `imessage_reply_unclassified` on `personId`: in the same
cases, the person wrote after their no and that message has no class yet. Retry in a few minutes. Nothing is
written, spoken or charged.
- `503 voice_notes_unavailable`: voice notes are not available right now. Try again later.

Requires Inbox edit, and a member with the Client role cannot call it.

Needs the `imessage` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/voice-notes/POST/v1/voice-notes)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request body

`application/json`, optional.

The person the note is for and the voice that says it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `personId` | integer (int64) | no | The person the note is for: the `imessage.personId` of their iMessage thread. They must have replied in it. |
| `voice` | LinkedInVoiceNoteSettings | no | The voice and the words, as a voice note step takes them: `provider` (`deepgram` or `elevenlabs`), `voiceId`, `speed` (null or 0.5 to 1.5), `wordsMode` (`ken_writes` with `instructions`, or `script` with `script`), `model` (`haiku` or `sonnet`) and `matchLeadLanguage`. |
| `touchId` | integer (int64) | no | Optional: the person's iMessage touch the note is for. The note is then judged on the thread that touch goes on (a reply's own thread), the touch shows it in `imessage.voiceNoteInProgress` while it is being made, and a second call for the touch while it is being made returns that note instead of making and charging another. When it is ready it goes on the touch as its `voiceNoteId` if the touch is still open, carries no images and has no voice note, and nobody changed it meanwhile; if the touch is still open but one of those does not hold, the note is kept, and charged, for you to put on a touch. A touch already sent or skipped is 400 with `touch_ended` on `touchId` (any other channel's touch: `not_allowed`); one sent, skipped or deleted while the note is made fails the note with `failureReason` `touch_ended`, uncharged. |
| `threadId` | string | no | Optional: the person's iMessage thread the note is for, as its `thr_` id, such as the thread a member has open in the inbox to reply with it (an agent or an API key sends a note on a touch, never as a reply). The note is then judged on that thread, so a person who replied there can get one even when their latest thread is on another number. The thread shows it in `imessage.voiceNoteInProgress` while it is being made, and a second call for the thread while it is being made returns that note instead of making and charging another. Send `touchId` or `threadId`, not both. |

### Response 201

`data` is a `ImessageVoiceNote`.

| Field | Type | Description |
| --- | --- | --- |
| `voiceNoteId` | integer (int64) | The voice note's id. |
| `status` | string | `generating` while Kenso makes it, `ready` once its audio can be sent, `sent` once a text carried it, `failed` when it could not be made (see `failureReason`), or `expired`. Stop polling at any value but `generating`. One still generating about 85 seconds after `createdAt` reads `failed` with `generation_unavailable`: make a new note. |
| `touchId` | integer (int64) | The iMessage touch it was made for (`touchId` at create). Omitted when none. |
| `threadId` | string | The iMessage thread it was made for, as its `thr_` id (`threadId` at create, or the person's latest thread when the create sent neither `touchId` nor `threadId`). Omitted when none: a note made for a `touchId` names only its touch. |
| `failureReason` | string | Why the note failed. Omitted unless status is `failed`. |
| `createdAt` | string (date-time) | When the note was asked for. |
| `createdByMemberId` | integer (int64) | The member who asked for the note, as their member id (the id the workspace's member list gives). Omitted for a note an API key with no member made. |
| `readyAt` | string (date-time) | When its audio was ready. Omitted until then, and for a note that failed. |
| `durationMs` | integer (int32) | The audio's length in milliseconds. Omitted until known. |
| `language` | string | The language of the script. Omitted when unknown. |
| `provider` | string | The voice service that made the audio. Omitted when unknown. |
| `voiceId` | string | The voice used for the audio. Omitted when unknown. |
| `scriptText` | string | The words spoken. Omitted until generated. |
| `audioAvailable` | boolean | True while Kenso keeps the audio. |
| `audioUrl` | string | The API route that plays the audio (`GET /v1/voice-notes/{voiceNoteId}/imessage-audio`). Omitted when there is no audio. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/voice-notes" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "personId": 77310,
  "voice": {
    "provider": "elevenlabs",
    "voiceId": "vc_7Qm2xB4kLpR9",
    "wordsMode": "ken_writes",
    "instructions": "Thank her for the reply and confirm Thursday at 2pm Central. Under 20 seconds.",
    "model": "haiku",
    "matchLeadLanguage": false
  },
  "threadId": "thr_aW1lc3NhZ2U6NTUxMjA0"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "voiceNoteId": 4410,
    "status": "ready",
    "touchId": 51842,
    "threadId": "thr_aW1lc3NhZ2U6NTUxMjA0",
    "createdAt": "2026-10-24T10:02:17Z",
    "createdByMemberId": 1093,
    "readyAt": "2026-10-24T10:02:31Z",
    "durationMs": 14200,
    "language": "en",
    "provider": "elevenlabs",
    "voiceId": "vc_7Qm2xB4kLpR9",
    "scriptText": "Hi Amanda, it's Alex. Thanks for getting back to me. Thursday at 2pm Central works, I'll send the invite now. Talk soon.",
    "audioAvailable": true,
    "audioUrl": "/v1/voice-notes/4410/imessage-audio"
  }
}
```

## Get an iMessage voice note

`GET /v1/voice-notes/{voiceNoteId}` - operationId `voice-notes.get`

| Permission | Rate limit |
| --- | --- |
| Inbox edit | 12,000 requests a minute per API key |

Returns a voice note made with `POST /v1/voice-notes`: its `status`, the `touchId` or
`threadId` it was made for, the member who asked for it (`createdByMemberId`), its `failureReason`,
and when it was made and ready. Poll it while the status is
`generating` (a touch's or thread's `imessage.voiceNoteInProgress` names the note being made), and stop at
any other status: `ready` (play it with `audioUrl`), `sent`, `failed` or `expired`.

A note is made in about half a minute. One still generating about 85 seconds after `createdAt` was stopped part
way and will not finish: it is returned as `failed` with `failureReason` `generation_unavailable`.
Make a new note with `POST /v1/voice-notes`. Nothing was charged for the one that failed. A note whose touch
was sent, skipped or deleted while it was made is `failed` with `failureReason` `touch_ended`, and
nothing was charged for it either.

Errors:

- `403 permission_denied`: you do not have Inbox edit, or you are a member with the Client role.
- `404 not_found`: no note made with `POST /v1/voice-notes` in the workspace has this id (a note a workflow
made is not read here: play it with `GET /v1/voice-notes/{voiceNoteId}/imessage-audio`), or it is for a person
you cannot see.

Requires Inbox edit, and a member with the Client role cannot call it.

Needs the `imessage` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/voice-notes/GET/v1/voice-notes/%7BvoiceNoteId%7D)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `voiceNoteId` | path | integer (int64) | yes | The voice note's id, from the create's `voiceNoteId` or `imessage.voiceNoteInProgress.id`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a `ImessageVoiceNote`.

| Field | Type | Description |
| --- | --- | --- |
| `voiceNoteId` | integer (int64) | The voice note's id. |
| `status` | string | `generating` while Kenso makes it, `ready` once its audio can be sent, `sent` once a text carried it, `failed` when it could not be made (see `failureReason`), or `expired`. Stop polling at any value but `generating`. One still generating about 85 seconds after `createdAt` reads `failed` with `generation_unavailable`: make a new note. |
| `touchId` | integer (int64) | The iMessage touch it was made for (`touchId` at create). Omitted when none. |
| `threadId` | string | The iMessage thread it was made for, as its `thr_` id (`threadId` at create, or the person's latest thread when the create sent neither `touchId` nor `threadId`). Omitted when none: a note made for a `touchId` names only its touch. |
| `failureReason` | string | Why the note failed. Omitted unless status is `failed`. |
| `createdAt` | string (date-time) | When the note was asked for. |
| `createdByMemberId` | integer (int64) | The member who asked for the note, as their member id (the id the workspace's member list gives). Omitted for a note an API key with no member made. |
| `readyAt` | string (date-time) | When its audio was ready. Omitted until then, and for a note that failed. |
| `durationMs` | integer (int32) | The audio's length in milliseconds. Omitted until known. |
| `language` | string | The language of the script. Omitted when unknown. |
| `provider` | string | The voice service that made the audio. Omitted when unknown. |
| `voiceId` | string | The voice used for the audio. Omitted when unknown. |
| `scriptText` | string | The words spoken. Omitted until generated. |
| `audioAvailable` | boolean | True while Kenso keeps the audio. |
| `audioUrl` | string | The API route that plays the audio (`GET /v1/voice-notes/{voiceNoteId}/imessage-audio`). Omitted when there is no audio. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/voice-notes/812" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": {
    "voiceNoteId": 4410,
    "status": "ready",
    "touchId": 51842,
    "threadId": "thr_aW1lc3NhZ2U6NTUxMjA0",
    "createdAt": "2026-10-24T10:02:17Z",
    "createdByMemberId": 1093,
    "readyAt": "2026-10-24T10:02:31Z",
    "durationMs": 14200,
    "language": "en",
    "provider": "elevenlabs",
    "voiceId": "vc_7Qm2xB4kLpR9",
    "scriptText": "Hi Amanda, it's Alex. Thanks for getting back to me. Thursday at 2pm Central works, I'll send the invite now. Talk soon.",
    "audioAvailable": true,
    "audioUrl": "/v1/voice-notes/4410/imessage-audio"
  }
}
```

## Open the audio of a voice note on an iMessage text

`GET /v1/voice-notes/{voiceNoteId}/imessage-audio` - operationId `voice-notes.imessage-audio`

| Permission | Rate limit |
| --- | --- |
| Inbox view | 12,000 requests a minute per API key |

The same audio as `GET /v1/voice-notes/{voiceNoteId}/audio`, for the notes iMessage texts carry: it works
while iMessage is on for the workspace, even when LinkedIn voice notes are off. Redirects (302) to a link to the
audio that works for 1 hour; fetch a new one rather than keeping it. Requires Inbox view: without it `403 permission_denied`. Another
workspace's note, or a note with no audio, is `404`; a note still being generated
`409 voice_note_not_ready`, until about 85 seconds after it was asked for: one still generating then never
finishes and is `404`; audio deleted after the retention period (90 days) `410 gone`.
`503 voice_notes_unavailable` while voice notes are not available on Kenso's side: try again later.

Needs the `imessage` feature on your workspace. Until it is on, calls answer 404.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/voice-notes/GET/v1/voice-notes/%7BvoiceNoteId%7D/imessage-audio)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `voiceNoteId` | path | integer (int64) | yes | The voice note's id, from its `voiceNote` object or a text's `imessage.voiceNoteId`. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/voice-notes/812/imessage-audio" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

## Get a voice note's audio

`GET /v1/voice-notes/{voiceNoteId}/audio` - operationId `voice-notes.audio`

| Permission | Rate limit |
| --- | --- |
| Inbox view | 12,000 requests a minute per API key |

Redirects with `302` to a link to the note's audio. The link works for 1 hour, so call this again each time
you play the note instead of keeping the link.

Kenso deletes a note's audio 90 days after the note was sent, or after it was made when it was never sent.

Errors:

- `403 permission_denied`: the member cannot view the Inbox, so cannot hear its messages.
- `404 not_found`: the note is not in this workspace, it has no audio, or the workspace feature its source needs
is off: `linkedin_voice_notes` for a LinkedIn step's note, a preview or an iMessage note made with
`POST /v1/voice-notes`, `whatsapp` for a WhatsApp message's note, and either for a workflow step's note.
Play the note an iMessage text carries with `GET /v1/voice-notes/{voiceNoteId}/imessage-audio`, the
`audioUrl` it carries.
- `409 voice_note_not_ready`: Kenso is still making the audio. Try again shortly.
- `410 gone`: Kenso deleted the audio after 90 days.
- `503 voice_notes_unavailable`: voice notes are not available right now. Try again later.

Requires Inbox view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/voice-notes/GET/v1/voice-notes/%7BvoiceNoteId%7D/audio)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `voiceNoteId` | path | integer (int64) | yes | The voice note's id, from its `voiceNote` object. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/voice-notes/812/audio" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

## Types

Each named type the tables above use, nested ones included.

### LinkedInVoiceNoteSettings

The voice settings of a LinkedIn voice note step: which voice speaks, and where the words come from. Every value that names an option is a lowercase string.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | no | Who provides the voice: `deepgram` or `elevenlabs`. Variant A's value applies to every variant. |
| `voiceId` | string | yes | The voice's id at its provider, at most 200 characters. Required. Variant A's value applies to every variant. |
| `speed` | number (double) | no | How fast the voice speaks, from 0.50 to 1.50. Kenso applies it to Deepgram voices only. Null keeps the provider's default. Variant A's value applies to every variant. |
| `wordsMode` | string | no | Where the words come from: `ken_writes` (Ken writes each contact's note from `instructions`) or `script` (Kenso speaks `script`). |
| `instructions` | string | no | What Ken should say, at most 1,000 characters. Required when `wordsMode` is `ken_writes`, and must be empty when it is `script`. |
| `script` | string | no | The words to speak, at most 900 characters, with contact `{tokens}` filled in for each contact. Required when `wordsMode` is `script`, and must be empty when it is `ken_writes`. |
| `model` | string | no | The model Ken writes with: `haiku` or `sonnet`. Null or blank means `haiku`. |
| `matchLeadLanguage` | boolean | no | When true, the note is spoken in the contact's outreach language when Kenso knows it. |

All resources: [/docs.md](/docs.md).
