> ## Documentation Index
> Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Import a translation memory
> Learn how to create a translation memory by declaring a TMX file, uploading it to a signed URL, and polling the import job.
This is how you create a translation memory: there is no endpoint that creates an empty one. Importing a TMX file creates the translation memory and fills it in a single job.
The request body describes the file you intend to upload; it does not carry the file. DeepL returns a signed `upload_url`, you upload the file to that URL, and processing starts automatically once the upload finishes.
## Importing a file
Send the file's name and size in bytes. The response returns the `job_id`, the `upload_url`, and the `expires_at` deadline for the upload.
```bash theme={null}
curl -X POST "https://api.deepl.com/v3/translation_memories/import" \
-H "Authorization: DeepL-Auth-Key " \
-H "Content-Type: application/json" \
-d '{
"source_file": {
"file_name": "legal.tmx",
"content_type": "application/xml",
"content_length": 1024
},
"parameters": {
"display_name": "Legal"
}
}'
```
```json theme={null}
{
"job_id": "0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40",
"upload_url": "https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40",
"expires_at": "2026-08-06T15:34:25.223Z"
}
```
`PUT` the file to `upload_url` before `expires_at`. The URL is already signed, so this request carries no DeepL credentials.
```bash theme={null}
curl -X PUT "https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40" \
-H "Content-Type: application/xml" \
--data-binary @legal.tmx
```
A successful upload returns no DeepL response body. Processing begins on its own, so there is no call to confirm the upload.
Check [the job](/api-reference/translation-memory/retrieve-a-translation-memory-job) until `status` is `completed` or `failed`.
```bash theme={null}
curl -X GET "https://api.deepl.com/v3/translation_memories/jobs/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40" \
-H "Authorization: DeepL-Auth-Key "
```
On completion, the job result carries the `translation_memory_id` of the new translation memory.
```json theme={null}
{
"job_id": "0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40",
"product": "translation_memory",
"operation": "import",
"creation_time": "2026-08-06T15:04:25.223Z",
"updated_time": "2026-08-06T15:06:11.418Z",
"source_file": {
"content_type": "application/xml",
"content_length": 1024
},
"parameters": {
"display_name": "Legal"
},
"results": [
{
"status": "completed",
"translation_memory_id": "a74d88fb-ed2a-4943-a664-a4512398b994",
"skipped_segment_count": 12
}
]
}
```
## Common mistakes
`content_length` must be greater than 0 and at most 1 GB. An oversize value is rejected as `400 Bad Request` with a message pointing at `source_file.content_length`.
`file_name` accepts at most 100 characters and `content_type` at most 127, both rejected as `400 Bad Request` if longer. TMX is the only supported format, so leave `content_type` unset or set it to `application/xml`.
A `202 Accepted` means the job exists, not that a translation memory does. Until the upload completes and the job reports `completed`, no translation memory has been created and there is no ID to reference.
If `expires_at` passes before you upload, the signed URL stops working. Create a new import job to get a fresh URL rather than retrying the old one.
A non-zero `skipped_segment_count` on a completed import is not a failure. Some segments were not stored, for example because they were malformed or duplicated an existing segment, but the rest imported normally. Check the value if you are reconciling segment counts against your source file.
If your account has reached its translation memory limit, the request returns `456`. Delete a translation memory before importing another.
## OpenAPI
````yaml post /v3/translation_memories/import
openapi: 3.0.3
info:
title: DeepL API Documentation
description: >-
The DeepL API provides programmatic access to DeepL’s language AI
technology.
Note: this OpenAPI spec is embedded into our API documentation and has
shortened descriptions.
termsOfService: https://www.deepl.com/pro-license
contact:
name: DeepL - Contact us
url: https://www.deepl.com/contact-us
version: 3.12.0
servers:
- url: https://api.deepl.com
description: DeepL API Pro
- url: https://api-free.deepl.com
description: DeepL API Free
security: []
tags:
- name: beta
description: >-
Experimental features that are under testing and not yet intended for
production use.
- name: TranslateText
description: >-
The text-translation API currently consists of a single endpoint,
`translate`, which is described below.
- name: TranslateDocuments
description: >-
The document translation API allows you to translate whole documents and
supports the following file types and extensions:
* `docx` - Microsoft Word Document
* `pptx` - Microsoft PowerPoint Document
* `xlsx` - Microsoft Excel Document
* `pdf` - Portable Document Format
* `htm / html` - HTML Document
* `txt` - Plain Text Document
* `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)
* `srt` - SRT Document
* `idml` - Adobe InDesign Markup Language
* `xml` - XML Document
* `json` - JSON Document
* `dita` - DITA topic (Darwin Information Typing Architecture)
* `mif` - Adobe FrameMaker Interchange Format
* `jpeg` / `jpg` / `png` - Image (currently in beta)
- name: RephraseText
description: >-
The `rephrase` endpoint is used to make corrections and adjustments to
texts based on style or tone.
- name: CorrectText
description: >-
The `correct` endpoint fixes spelling and grammar errors without broader
rephrasing. Use it when you want
a minimal-change correction pass rather than the broader rewriting
performed by `rephrase`.
- name: ManageSpokenTerms
description: >-
The *Spoken Terms* functions allow you to create, inspect, edit and delete
Spoken Terms collections.
Spoken Terms improve speech recognition in the Voice API: they ensure
specific words and phrases,
such as company names, acronyms, and product names, are transcribed
correctly. A collection contains
one or more term lists, each holding terms for a single language, and is
applied to a voice session
via the `spoken_terms_id` parameter.
- name: ManageMultilingualGlossaries
description: >-
The *glossary* functions allow you to create, inspect, edit and delete
glossaries.
Glossaries created with the glossary function can be used in translate
requests by specifying the
`glossary_id` parameter. A glossary contains (several) dictionaries.
A dictionary is a mapping of source phrases to target phrases for a single
language pair.
If you encounter issues, please let us know at support@DeepL.com.
Currently you can create glossaries with any of the languages DeepL
supports (with the exception of Thai).
The maximum size limit for a glossary is 10 MiB = 10485760 bytes and each
source/target text,
as well as the name of the glossary, is limited to 1024 UTF-8 bytes.
A total of 1000 glossaries are allowed per account.
When creating a dictionary with target language `EN`, `PT`, or `ZH`, it's
not necessary to specify a variant
(e.g. `EN-US`, `EN-GB`, `PT-PT`, `PT-BR`, or `ZH-HANS`).
Dictionaries with target language `EN` can be used in translations with
either English variant.
Similarly `PT`, and `ZH` dictionaries can be used in translations with
their corresponding variants.
(When you provide the ID of a glossary to a translation, the appropriate
dictionary is automatically applied. Currently glossaries can not yet be
used with source language detection.)
Glossaries created via the DeepL API are now unified with glossaries
created via the DeepL website and DeepL apps.
Please only use the v3 glossary API in conjunction with multilingual or
edited glossaries from the website.
- name: ManageGlossaries
description: >-
Please note that this is the spec for the (old) v2 glossary endpoint.
We recommend users switch to the newer v3 glossary endpoints, which
support editability and multilinguality.
The *glossary* functions allow you to create, inspect, and delete
glossaries.
Glossaries created with the glossary function can be used in translate
requests by specifying the
`glossary_id` parameter.
If you encounter issues, please let us know at support@DeepL.com.
Currently you can create glossaries with any of the languages DeepL
supports (with the exception of Thai).
- name: MetaInformation
description: Information about API usage and value ranges
- name: TranslationMemories
description: >-
The translation memory endpoints allow you to manage your account's
translation memories, used to store
and reuse previously created translations. You can list and retrieve
translation memories, page through
their stored segments, create one by importing a TMX file, export one back
to TMX, and delete one.
Editing the contents of an existing translation memory is not supported;
import a new one instead.
Importing and exporting run as background jobs. Create the job, then poll
`GET /v3/translation_memories/jobs/{job_id}` until it reports `completed`.
Translation memories can be used in text translation requests by
specifying the `translation_memory_id` parameter to denote a specific
translation memory and the
`translation_memory_threshold` which defines the minimum matching
percentage required for a translation memory
segment to be applied (recommended to be 75% or higher). A translation
request fails with `404` if the
translation memory does not exist or does not cover the requested language
pair.
- name: VoiceAPI
description: >-
The Voice API provides real-time voice transcription and translation
services.
Use a two-step flow: first request a streaming URL via REST, then
establish a WebSocket connection for streaming audio and receiving
transcriptions.
- name: VoiceTranslateJob
description: >-
**Alpha.** Async voice translation jobs. This API may change without
notice.
- name: AdminApi
description: >-
Endpoints for organization administrators to manage API keys and retrieve
usage analytics.
- name: QualityEvaluation
description: >-
**Closed alpha.** Evaluate translation quality. Submit source/target
segment pairs and retrieve per-segment quality issues categorized by error
type and severity, with character spans pointing to where each issue
occurs.
externalDocs:
description: DeepL Pro - Plans and pricing
url: https://www.deepl.com/pro#developer
paths:
/v3/translation_memories/import:
post:
tags:
- TranslationMemories
summary: Import a translation memory
description: >-
Create a translation memory by importing a TMX file.
This endpoint does not accept the file itself. It returns a short-lived
`upload_url`, and you
upload the TMX file to that URL with a separate `PUT` request.
Processing starts automatically
once the upload completes, so there is no third call to confirm it.
1. `POST /v3/translation_memories/import` with the file's name and size.
The response returns a
`job_id`, an `upload_url`, and the `expires_at` time after which the URL stops working.
2. `PUT` the TMX file to `upload_url`. Do not send your `Authorization`
header on this request,
because the URL is already signed.
3. Poll [Retrieve an import or export
job](/api-reference/translation-memory/retrieve-a-translation-memory-job)
until the status is `completed`. The new `translation_memory_id` is on the job result.
Requires an API key with the `translation_memories:write` scope.
operationId: createTranslationMemoryImport
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- source_file
properties:
source_file:
type: object
required:
- file_name
- content_length
properties:
file_name:
description: >-
The name of the TMX file you intend to upload, including
its extension. At most 100
characters.
type: string
maxLength: 100
example: legal.tmx
content_type:
description: >-
The MIME type of the file. Defaults to
`application/xml`, which is correct for TMX.
TMX is currently the only supported import format. At
most 127 characters.
type: string
default: application/xml
maxLength: 127
example: application/xml
content_length:
description: >-
The size of the file in bytes. Must be greater than 0
and at most 1 GB. An oversize
value is rejected with `400 Bad Request`.
type: integer
format: int64
minimum: 1
example: 1024
parameters:
type: object
properties:
display_name:
description: >-
The name to give the new translation memory. If you omit
this, the translation memory
is created without a name.
type: string
example: Legal
examples:
Basic:
value:
source_file:
file_name: legal.tmx
content_type: application/xml
content_length: 1024
parameters:
display_name: Legal
responses:
'202':
description: >-
The import job was created. Upload the file to `upload_url` before
`expires_at`.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
content:
application/json:
schema:
type: object
required:
- job_id
- upload_url
- expires_at
properties:
job_id:
description: >-
The identifier of the import job. Use it to poll the job's
status.
type: string
format: uuid
example: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
upload_url:
description: >-
A signed URL to `PUT` the TMX file to. Do not send your
`Authorization` header with the
upload request.
type: string
format: uri
example: >-
https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
expires_at:
description: >-
The time the `upload_url` stops accepting uploads, in the
ISO 8601-1:2019 format. After
this time, create a new import job.
type: string
format: date-time
example: '2026-08-06T15:34:25.223Z'
examples:
Basic:
value:
job_id: 0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
upload_url: >-
https://assets.deepl.com/upload/0f8b6c1e-4d2a-4c77-9a3e-1b5d8c9e2f40
expires_at: '2026-08-06T15:34:25.223Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/ForbiddenScoped'
'429':
$ref: '#/components/responses/TooManyRequests'
'456':
description: >-
You have reached the maximum number of translation memories for your
account. Delete a
translation memory before creating another one.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
$ref: '#/components/responses/InternalServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
security:
- auth_header: []
components:
headers:
X-Trace-ID:
description: >-
A unique identifier for the request that can be included in bug reports
to DeepL support.
schema:
type: string
example: 501c3d93cc0c4f11ae2f60a226c2f0f0
responses:
BadRequest:
description: Bad request. Please check error message and your parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: >-
Authorization failed. Please supply a valid `DeepL-Auth-Key` via the
`Authorization` header.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ForbiddenScoped:
description: >-
Authorization failed. Please supply a valid `DeepL-Auth-Key` via the
`Authorization` header. This error is also returned when the API key is
scoped but does not include the scope required for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
TooManyRequests:
description: Too many requests. Please wait and resend your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: Internal error.
ServiceUnavailable:
description: Resource currently unavailable. Try again later.
schemas:
ErrorResponse:
type: object
required:
- message
properties:
message:
type: string
description: A human-readable description of the error.
code:
type: string
description: >-
A machine-readable identifier for the error, when available. Clients
should match on this value rather than on `message` when branching
on error types.
example: invalid_content_type
securitySchemes:
auth_header:
type: apiKey
description: >
Authentication with `Authorization` header and `DeepL-Auth-Key`
authentication scheme. Example: `DeepL-Auth-Key `
name: Authorization
in: header
x-default: 'DeepL-Auth-Key '
````