The TranslationRequests API from Knak — 5 operation(s) for translationrequests.
openapi: 3.1.0
info:
description: '## Overview
An API specification to provide a Custom Sync Location in Knak.
By implementing a service conforming to this API specification, you will be able to send asset data to your own service and have that service specify a sync location based on that data.
## Authentication
Knak provides two options for authentication:
- **Basic Authentication**: Knak will use Basic Authentication to authenticate with your API. You will just need to provide a username and password when configuring the integration.
- **OAuth2**: Knak will use OAuth2 to authenticate with your API. You will need to implement endpoints under a specified authorization path to support this. The default path will be `/oauth/token` but you can provide a separate path when configuring the integration if you so choose. The flow used is the standard [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1).
Knak will use the tokens generated to make requests from your service.
## Custom Sync Location
When a user has a custom sync location configured and they have set up a sync restriction that leverages the custom sync location.
Knak will call the `/knak-sync-location` (or your own specified path) endpoint with the asset data when an asset is synced. Your service should return a response with the sync location for the asset.
When your service provides a sync location, Knak will use that location to display only the available sync location to the user.
'
version: V1
title: Custom Sync Location API Reference Asset Custom Fieldsets TranslationRequests API
x-logo:
url: https://s3.amazonaws.com/assets.knak.io/img/Knak-Logo-Medium.png
servers:
- url: https://yourService.com/your-sync-location-api
tags:
- name: TranslationRequests
paths:
/translation-requests:
get:
description: "Retrieve all [translation requests](#tag/translation_request) that the API user has access to based on their brand scopes.\n\n **NOTE:** Only translation requests created from custom translation integrations will be visible. Steps to set up a custom translation integration can be found [here](https://help.knak.io/en/articles/9687639-knak-custom-translation-integration-setup-guide)."
summary: List all translation requests
parameters:
- name: page
in: query
required: false
description: Page number
example: 1
schema:
type: integer
- name: per_page
in: query
required: false
description: Number of items per page
example: 10
schema:
type: integer
- name: filter[status]
in: query
description: Filter by status. Exact match filter.
required: false
schema:
type: string
example: requested
- name: filter[asset_id]
in: query
description: Filter by asset ID. Exact match filter. (Corresponds to `base_asset_id` in response)
required: false
schema:
type: string
example: 609ca344d1b1b
- name: filter[created_at_before]
in: query
description: Filter translation requests created before a specific date, formatted in ISO 8601 format. Can be used in conjunction with `created_at_after` filter
required: false
schema:
type: string
example: '2023-04-01T00:00:00Z'
- name: filter[created_at_after]
in: query
description: Filter translation requests created after a specific date, formatted in ISO 8601 format. Can be used in conjunction with `created_at_before` filter
required: false
schema:
type: string
example: '2023-04-03T00:00:00Z'
- name: sort
in: query
description: Sort by field (`created_at`, `updated_at`), use '-' to reverse order of sort (e.g. -created_at).
required: false
schema:
type: string
example: created_at
tags:
- TranslationRequests
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequestList'
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
post:
description: 'Create one or more [translation requests](#tag/translation_request) for an asset using a custom translation integration. One translation request is created per code supplied in `language_codes`, and newly created requests start with a `status` of `requested`.
The `integration_id` must reference a `custom_translation` integration that belongs to your company. Every code in `language_codes` must be one of your company''s supported translation languages — call `GET /translation-languages` first to retrieve the valid set.
**NOTE:** Only `custom_translation` integrations are supported by this endpoint. Integrations for marketing platforms or other translation providers (Smartling, TransPerfect, Lazarus) are rejected with `422 Unprocessable Entity`. Steps to set up a custom translation integration can be found [here](https://help.knak.io/en/articles/9687639-knak-custom-translation-integration-setup-guide).'
summary: Create translation requests
tags:
- TranslationRequests
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- integration_id
- asset_id
- language_codes
properties:
integration_id:
type: string
description: ID of the `custom_translation` integration to use. Must belong to your company.
example: 609ca344d1caa
asset_id:
type: string
description: ID of the asset (email or landing page) to translate.
example: 609ca344d1b1b
language_codes:
type: array
description: One or more target language codes. Each must be a supported translation language for your company (see `GET /translation-languages`). Values must be unique; one translation request is created per code.
minItems: 1
items:
type: string
example:
- fr-CA
- es-ES
notes:
type: string
nullable: true
description: Optional notes or context stored on each created request. If omitted, the value will be null.
example: Please prioritize this campaign
due_date:
type: string
nullable: true
description: Optional due date for the translation, in ISO 8601 format. If omitted, the value will be null.
example: '2026-07-01'
responses:
'201':
description: Created. Returns the translation requests that were created, one per language code.
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequestCreatedList'
example:
data:
- type: translation-request
id: 609d7ce223411
attributes:
id: 609d7ce223411
language_code: fr-CA
status: requested
base_asset_id: 609ca344d1b1b
asset_version_id: 67d19607cbb1d4.78284760
integration_id: 609ca344d1caa
user:
id: 609d7ce223400
name: John Doe
email: john.doe@email.com
roles:
- Email Creator
notes: Please prioritize this campaign
due_date: '2026-07-01'
created_at: '2026-06-08T17:07:12+00:00'
updated_at: '2026-06-08T17:07:12+00:00'
- type: translation-request
id: 609d7ce223412
attributes:
id: 609d7ce223412
language_code: es-ES
status: requested
base_asset_id: 609ca344d1b1b
asset_version_id: 67d19607cbb1d4.78284760
integration_id: 609ca344d1caa
user:
id: 609d7ce223400
name: John Doe
email: john.doe@email.com
roles:
- Email Creator
notes: Please prioritize this campaign
due_date: '2026-07-01'
created_at: '2026-06-08T17:07:12+00:00'
updated_at: '2026-06-08T17:07:12+00:00'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Validation Error for language_codes
detail: The language codes field is required.
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Resource Not Found.
detail: Could not find the asset you were looking for.
'422':
description: Unprocessable Entity. Returned when `integration_id` is not a `custom_translation` integration belonging to your company, or when one or more `language_codes` are not supported for your company.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_integration:
summary: integration_id is not a valid custom_translation integration
value:
errors:
- status: '422'
title: Unprocessable Entity
detail: The integration_id is not a custom_translation integration belonging to your company.
meta:
integration_id: 609ca344d1caa
unsupported_language_code:
summary: One or more language codes are not supported
value:
errors:
- status: '422'
title: Unprocessable Entity
detail: 'These language codes are not supported for your company: zz-ZZ, ja-JP. Use GET /v1/translation-languages to list supported codes.'
meta:
unsupported_language_codes:
- zz-ZZ
- ja-JP
/translation-requests/{id}:
get:
description: Retrieve a [translation request](#tag/translation_request) created from a custom translation integration.
summary: Retrieve a translation request
tags:
- TranslationRequests
parameters:
- name: id
in: path
required: true
description: ID of the translation request to retrieve
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequest'
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Resource Not Found.
detail: Could not find the translation request you were looking for.
patch:
description: Update the status of a [translation request](#tag/translation_request).
summary: Update a translation request
tags:
- TranslationRequests
parameters:
- name: id
in: path
required: true
description: ID of the translation request to update
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- processing
- completed
- failed
- cancelled
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequest'
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Resource Not Found.
detail: Could not find the translation request you were looking for.
/translation-requests/{id}/download-source:
get:
description: Download the source file for a [translation request](#tag/translation_request) in the specified format. The `content-type` of the response will change depending on the format requested.
summary: Download source file for translation request
tags:
- TranslationRequests
parameters:
- name: id
in: path
required: true
description: ID of the translation request to download the source file for
schema:
type: string
- name: format
in: query
required: false
description: Format of the source file to download
schema:
type: string
enum:
- arb
- xliff-1.2
- xliff-2.0
responses:
'200':
description: Success
content:
application/xml:
schema:
type: string
format: binary
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Resource Not Found.
detail: Could not find the translation request you were looking for.
/translation-requests/{id}/upload-translation:
post:
description: Upload a completed translation file for a [translation request](#tag/translation_request). The file is validated synchronously and the result of the validation is given by the response. If the file is valid (indicated by a 200 response), then the translation will be applied in Knak asynchronously. Once applied, the `status` of the translation request will be updated to `completed` automatically.
summary: Upload translated file
tags:
- TranslationRequests
parameters:
- name: id
in: path
required: true
description: ID of the translation request to upload a translation file for
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: The translated file to apply
responses:
'200':
description: The file was uploaded successfully
'400':
description: File validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Validation error for file.
detail: The file must be a valid XLIFF file.
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Resource Not Found.
detail: Could not find the translation request you were looking for.
/translation-languages:
get:
description: Retrieve the translation languages supported for your company, ordered by ISO code. Each `iso_code` returned is a valid value for the `language_codes` field when creating a [translation request](#tag/translation_request) via `POST /translation-requests`.
summary: List supported translation languages
tags:
- TranslationRequests
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationLanguageList'
example:
data:
- type: translation_language
id: en-US
attributes:
iso_code: en-US
name: English (United States)
- type: translation_language
id: es-ES
attributes:
iso_code: es-ES
name: Spanish (Spain)
- type: translation_language
id: fr-CA
attributes:
iso_code: fr-CA
name: French (Canada)
'401':
description: Unauthenticated
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Unauthenticated.
detail: Authenticate before continuing.
'403':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
- title: Forbidden.
detail: This user is not authorized to perform this action. Please adjust permissions before continuing.
components:
schemas:
TranslationRequestItem:
type: object
properties:
type:
type: string
example: translation-request
id:
type: string
example: 609d7ce223411
attributes:
$ref: '#/components/schemas/TranslationRequestItemAttributes'
TranslationRequestList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TranslationRequestItem'
links:
type: object
properties:
first:
type: string
example: https://enterprise.knak.io/api/published/v1/translation-requests?page=1
last:
type: string
example: https://enterprise.knak.io/api/published/v1/translation-requests?page=3
prev:
type: string
nullable: true
example: https://enterprise.knak.io/api/published/v1/translation-requests?page=1
next:
type: string
nullable: true
example: https://enterprise.knak.io/api/published/v1/translation-requests?page=3
meta:
type: object
properties:
current_page:
type: integer
example: 2
from:
type: integer
example: 1
last_page:
type: integer
example: 3
links:
type: array
items:
type: object
properties:
url:
type: string
nullable: true
example: https://enterprise.knak.io/api/published/v1/translation-requests?page=2
label:
type: string
example: Next
active:
type: boolean
example: true
path:
type: string
example: https://enterprise.knak.io/api/published/v1/translation-requests?page=2
per_page:
type: integer
example: 10
to:
type: integer
example: 3
total:
type: integer
example: 3
TranslationRequestAttributes:
type: object
properties:
id:
type: string
example: 609d7ce223411
language_code:
description: The language code of the translation target
type: string
example: zh-CN
source_language_code:
description: The language code of the translation source. If not set, the value will be null
type: string
nullable: true
example: en-US
status:
type: string
enum:
- cancelled
- completed
- deleted
- failed
- manually_translating
- processing
- reopened
- requested
- re_requested
example: processing
base_asset_id:
description: The ID of the Asset that should be translated
type: string
example: 609ca344d1b1b
asset_version_id:
description: The ID of the Asset Version that should be translated
type: string
example: 67d19607cbb1d4.78284760
integration_id:
type: string
description: The ID of the integration that was used to request the translation
example: 609ca344d1caa
user:
$ref: '#/components/schemas/User'
required:
- email
notes:
type: string
description: Any notes or context relating to the translation request. If not set, the value will be null
nullable: true
example: Need a translation for this asset soon
due_date:
type: string
description: The date the translation is due. If not set, the value will be null
nullable: true
example: '2023-02-08'
created_at:
type: string
example: '2023-02-08T17:07:12+00:00'
updated_at:
type: string
example: '2023-02-08T17:07:12+00:00'
TranslationRequestItemAttributes:
type: object
properties:
id:
type: string
example: 609d7ce223411
language_code:
description: The language code of the translation target
type: string
example: zh-CN
source_language_code:
description: The language code of the translation source. If not set, the value will be null
type: string
nullable: true
example: en-US
status:
type: string
enum:
- cancelled
- completed
- deleted
- failed
- manually_translating
- processing
- reopened
- requested
- re_requested
example: processing
base_asset_id:
description: The ID of the Asset that should be translated
type: string
example: 609ca344d1b1b
asset_version_id:
description: The ID of the Asset Version that should be translated
type: string
example: 67d19607cbb1d4.78284760
integration_id:
type: string
description: The ID of the integration that was used to request the translation
example: 609ca344d1caa
creator_id:
type: string
description: The ID of the user who requested the translation
example: 609ca344d1b1b
notes:
type: string
description: Any notes or context relating to the translation request. If not set, the value will be null
nullable: true
example: Need a translation for this asset soon
due_date:
type: string
description: The date the translation is due. If not set, the value will be null
nullable: true
example: '2023-02-08'
created_at:
type: string
example: '2023-02-08T17:07:12+00:00'
updated_at:
type: string
example: '2023-02-08T17:07:12+00:00'
User:
type: object
properties:
id:
type: string
example: 609d7ce223411
name:
type: string
example: John Doe
email:
type: string
example: john.doe@email.com
roles:
type: array
example:
- Email Creator
- Collaborator
description: The roles for the user. Can be any of the roles defined for the company including custom roles.
items:
type: string
TranslationRequestCreatedList:
type: object
properties:
data:
type: array
description: The translation requests that were created, one per requested language code.
items:
$ref: '#/components/schemas/TranslationRequest'
TranslationLanguage:
type: object
properties:
type:
type: string
example: translation_language
id:
type: string
description: The ISO language code. Used as the resource id and as a value for `language_codes` when creating a translation request.
example: fr-CA
attributes:
type: object
properties:
iso_code:
type: string
description: The ISO language code supported for translation requests.
example: fr-CA
name:
type: string
description: Human-readable language name.
example: French (Canada)
TranslationLanguageList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TranslationLanguage'
Error:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
description: HTTP status code as a string. Returned by endpoints that use the JSON:API error shape.
example: '409'
title:
type: string
detail:
type: string
meta:
type: object
description: Additional context for the error. Returned by endpoints that use the JSON:API error shape.
additionalProperties: true
TranslationRequest:
type: object
properties:
type:
type: string
example: translation-request
id:
type: string
example: 609d7ce223411
attributes:
$ref: '#/components/schemas/TranslationRequestAttributes'