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

# Text translation

> **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.

Translate plain text into one language, for example a reply so a member can read it. The translation keeps line breaks, names, links, numbers and `{placeholders}`. Each call counts against a per-workspace limit, and a translation Kenso makes anew costs credits.

Campaigns. 1 endpoint 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/translations/openapi.json](/docs/api/translations/openapi.json).

- `POST /v1/translations` - Translate text (`translations.create`): [/docs/api/translations/create.md](/docs/api/translations/create.md)

## Translate text

`POST /v1/translations` - operationId `translations.create`

| Permission | Credits | Rate limit |
| --- | --- | --- |
| Inbox view and the `ask` permission | Varies with the request (`translation`) | 20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day) |

Translates plain text into the language you name and reports the language of the input. Use it to read a reply
written in a language you do not speak.

Send `text`, at most 8,000 characters, and `targetLanguage`, a two-letter ISO 639-1 code such as
`en`. The translation keeps the input's line breaks, names, links, numbers and `{placeholders}`. In the
response, `sourceLanguage` is the input's ISO 639-1 code, or `und` when Kenso could not tell.

`messageId` is optional. With the `msg_` id of an email in this workspace, Kenso stores the translation
on that email, and a later call with the same `messageId`, text and language returns it without translating
again. Kenso
accepts a LinkedIn `msg_` id but stores nothing for it.

Each call uses one unit of the workspace's translation limit: 20 a minute and 500 a day. A translation Kenso makes
anew costs credits for the AI work it takes (`translation` on the rate card), and a stored translation
costs nothing. A member's translations count toward their monthly credit limit, and so do translations made with
an API key that belongs to a member: they count toward the key's owner.

Errors:

- `400 validation_failed`: `text` is missing or longer than 8,000 characters, `targetLanguage` is not a two-letter code, or `messageId` is not a message id.
- `402 plan_limit_reached`: the workspace has no credits left. The error's `refusal` says what to do.
- `402 member_credit_limit_reached`: the caller, or the member who owns the caller's API key, reached their monthly credit limit in this workspace. The error's `refusal` says what to do.
- `404 not_found`: `messageId` names an email that does not exist in this workspace.
- `429 quota_exceeded`: the workspace used up its translation limit. Retry after the seconds in `Retry-After`.
- `503 service_unavailable`: the translation failed. Try again.

Requires Inbox view and the `ask` permission.

Needs the `multilingual_outreach` 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/translations/POST/v1/translations)

### 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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | no | Plain text to translate, at most 8,000 characters. Kenso keeps its line breaks. |
| `targetLanguage` | string | no | Two-letter ISO 639-1 code of the language to translate into, such as `en` or `de`. |
| `messageId` | string | no | Optional `msg_` id of the message the text comes from. For an email, Kenso stores the translation on the message and returns it to a later call with the same message, text and language. For a LinkedIn message, Kenso stores nothing. |

### Response 200

`data` is a `Translation`.

| Field | Type | Description |
| --- | --- | --- |
| `text` | string | The translated plain text, with the input's line breaks. |
| `sourceLanguage` | string | ISO 639-1 code of the input's language, or `und` when Kenso could not tell. |

### Request

```bash
curl -X POST "https://api.ken.so/v1/translations" \
  -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 '{
  "text": "string",
  "targetLanguage": "en",
  "messageId": "msg_ZW1haWw6NDAyMjg0LjJAZXhhbXBsZS5jb20"
}'
```

### Example response

```json
{
  "success": true,
  "data": {
    "text": "string",
    "sourceLanguage": "string"
  }
}
```

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