Skip to Content
Campaigns

Text translation

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.

Campaigns1 endpointKen-Version: 2026-11-02AuthenticationWorkspacesErrors
MarkdownOpenAPI

Headers

The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.

NameInTypeRequiredDescription
Ken-Versionheaderstring, one of: 2026-11-02, 1.1optionalThe 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 date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Idheaderinteger (int64)optionalThe 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.

Translate text

POST/v1/translationstranslations.create
Permission
Inbox view and the ask permission
Credits
Varies with the request (translation)
Rate limit
20 requests a minute and 500 a day per workspace (Free plan: 2 a minute and 50 a day)
Needs the multilingual_outreach feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

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. An API key's translations count toward no member's limit.

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

Request body

application/json, optional.

FieldTypeRequiredDescription
textstringoptionalPlain text to translate, at most 8,000 characters. Kenso keeps its line breaks.
targetLanguagestringoptionalTwo-letter ISO 639-1 code of the language to translate into, such as en or de.
messageIdstringoptionalOptional 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.
Request
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"
}'

Response 200

data is a Translation.

Show the 2 response fields and an example

The fields and an example are also on this endpoint's Markdown page.


On this page