Skip to main content
Translation memories store pairs of source segments and their approved translations, and reuse them when you translate matching text. This guide shows how to manage them with the v3 translation memory endpoints: import a TMX file as a new translation memory, inspect what it contains, export it, and delete it. TMX (Translation Memory eXchange) is the XML interchange format for translation memories, and the only format the API accepts. Reading and exporting need an API key with the translation_memories:read scope. Importing and deleting need translation_memories:write. See Permission Scopes.
To apply a translation memory in a translation request and tune how closely text must match, follow Using Translation Memories, a hands-on tutorial.

​
Import a translation memory

Importing a TMX file is how you create a translation memory over the API. The import runs as a background job in three steps: declare the file, upload it to the URL you get back, then poll the job for the new translation memory’s ID.
1

Declare the file

Send the file name and its size in bytes, plus the name to give the new translation memory. The request describes the file; it doesn’t carry it.
Example request
Example response
2

Upload the file

PUT the TMX file to upload_url before expires_at. The URL is already signed, so leave out your Authorization header. A successful upload returns no body, and processing starts as soon as the upload finishes.
Example request
3

Poll the job

Request the job until its status is completed, failed, or expired. A completed import carries the new translation_memory_id.
Example request
Example response
Until the job reports completed, no translation memory exists yet. A status of awaiting_input means the file hasn’t arrived, and processing means DeepL is still reading it. If the status is failed, error.message on the result says why. An expired job is too old to act on, so start a new import. A non-zero skipped_segment_count on a completed import is normal: those segments were malformed or duplicated an existing one, and the rest imported. If expires_at passes before you upload, start a new import rather than retrying the old URL. The import reference lists the file size and name limits and the error responses.

​
Inspect a translation memory

Retrieve a translation memory by ID to get its metadata: the name, source language, target languages, segment count, and when it was created and last updated. The contents are a separate request.
Example request
Example response
To page through all translation memories on your account instead, use GET /v3/translation_memories.

​
Read the stored segments

List the segments to read the content itself. Each entry is one source segment with its translation in every target language. Every source and target carries its own creation and update timestamps, plus a last-used timestamp once it has matched a translation.
Example request
Example response
last_used_time is when that segment was last applied in a translation. It’s absent on segments that have never matched, which makes it a quick way to find content nobody reuses. To get the next page, pass the response’s next_page_cursor as page_cursor; the last page has no cursor. To search the content, add filter_text with at least 2 characters:
Example request
The response has the same shape as above, with only matching segments. Start again without a cursor whenever you change the filter, and stop when next_page_cursor is absent rather than counting up to segment_count, which always reports the whole translation memory. The segments reference covers case-sensitive matching and the cursor rules in full.

​
Export a translation memory

Export a translation memory to get its contents as a TMX file. Like importing, this runs as a background job: start it, poll it, then download the file.
Example request
Example response
Poll the job the same way as an import, until its status is completed, failed, or expired. A completed export carries a download_url and the expires_at time after which it stops working:
Example request
Example response
Download the file right away rather than storing the URL. Like the upload URL, it’s signed, so send no Authorization header. If the URL has expired, start a new export.
Example request
A successful download writes the TMX file to legal-export.tmx and returns no other body. Starting an export doesn’t always start new work. If a recent export of the same translation memory is still available, the request returns 200 OK with that job instead of 202 Accepted, and you poll it in the same way. If an export is already running, the request returns 409 Conflict: poll the job you already have instead of retrying. See the export reference for details.

​
Delete a translation memory

Delete a translation memory to remove it and every segment in it. A successful request returns 204 No Content with an empty body.
Example request
Deletion is permanent. Export the translation memory first if you need a copy, and remove its ID from your translation requests before deleting, because those requests fail once it’s gone.

​
Edit a translation memory

Editing the contents of an existing translation memory over the API isn’t supported yet; support is in active development. Until then, to change what a translation memory contains:
  1. Export it and edit the TMX file
  2. Import the edited file as a new translation memory, which gets a new ID
  3. Switch your translation requests to the new ID
  4. Delete the old translation memory

​
Limits and restrictions