---
updatedAt: 2026-06-15T14:45:23.000Z
agentTools:
  projectIndex: https://developers.lokalise.com/llms.txt
---

# Download files (Async)

Starts a project export process. The progress of the process can be tracked using the <a href="https://developers.lokalise.com/reference/list-all-processes">list all processes</a> API endpoint. Once complete, the download URL can be accessed using the <a href="https://developers.lokalise.com/reference/retrieve-a-process">Retrieve process</a> API endpoint. For general details about the Download endpoint, please refer to the <a href="https://developers.lokalise.com/reference/download-files">Download files</a> API endpoint.

In Documents projects, every format except <code>offline_xliff</code> ignores the following options and uses fixed values instead: <code>original_filenames</code> is <code>true</code>, <code>bundle_structure</code> is <code>%PROJECT_NAME%-%LANG_ISO%.%FORMAT%</code>, <code>directory_prefix</code> is <code>%LANG_ISO%/</code>, <code>export_sort</code> is <code>first_added</code>, <code>include_comments</code>, <code>include_description</code> and <code>disable_references</code> are <code>false</code>, and <code>filter_data</code>, <code>replace_breaks</code>, <code>custom_translation_status_ids</code> and <code>include_pids</code> are not applied. Documents projects export document formats such as <code>docx</code>, <code>pptx</code>, <code>html</code> and <code>idml</code>, plus <code>offline_xliff</code>; key-based formats such as <code>json</code> are rejected. <code>filter_langs</code>, <code>filter_task_id</code>, <code>language_mapping</code>, <code>webhook_url</code> and <code>triggers</code> still apply.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Default projects",
    "version": "1.0.0",
    "description": "Describes the API for default projects.\\n\\n**Project Type Compatibility**: Many API endpoints have different compatibility with project types:\\n- **Software projects** (localization_files) - Support individual key management, no file deletion\\n- **Documents projects** (paged_documents) - Support file management, no individual key operations\\n- **Marketing projects** (content_integration, marketing, marketing_integrations) - Mixed support depending on specific type\\n\\nBranching is only supported for Software projects. See individual endpoint documentation for specific compatibility information."
  },
  "servers": [
    {
      "url": "https://api.lokalise.com/api2"
    }
  ],
  "paths": {
    "/projects/{project_id}/files/async-download": {
      "post": {
        "responses": {
          "200": {
            "description": "OK",
            "headers": {},
            "content": {
              "application/json": {
                "example": {
                  "process_id": "74738ff5-5367-5958-9aee-98fffdcd1876"
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "process_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "summary": "Download files (Async)",
        "operationId": "Download files (Async)",
        "description": "Starts a project export process. The progress of the process can be tracked using the <a href=\"https://developers.lokalise.com/reference/list-all-processes\">list all processes</a> API endpoint. Once complete, the download URL can be accessed using the <a href=\"https://developers.lokalise.com/reference/retrieve-a-process\">Retrieve process</a> API endpoint. For general details about the Download endpoint, please refer to the <a href=\"https://developers.lokalise.com/reference/download-files\">Download files</a> API endpoint.\n\nIn Documents projects, every format except <code>offline_xliff</code> ignores the following options and uses fixed values instead: <code>original_filenames</code> is <code>true</code>, <code>bundle_structure</code> is <code>%PROJECT_NAME%-%LANG_ISO%.%FORMAT%</code>, <code>directory_prefix</code> is <code>%LANG_ISO%/</code>, <code>export_sort</code> is <code>first_added</code>, <code>include_comments</code>, <code>include_description</code> and <code>disable_references</code> are <code>false</code>, and <code>filter_data</code>, <code>replace_breaks</code>, <code>custom_translation_status_ids</code> and <code>include_pids</code> are not applied. Documents projects export document formats such as <code>docx</code>, <code>pptx</code>, <code>html</code> and <code>idml</code>, plus <code>offline_xliff</code>; key-based formats such as <code>json</code> are rejected. <code>filter_langs</code>, <code>filter_task_id</code>, <code>language_mapping</code>, <code>webhook_url</code> and <code>triggers</code> still apply.",
        "tags": [
          "Files"
        ],
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "description": "A unique project identifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "format": "json"
              },
              "schema": {
                "type": "object",
                "required": [
                  "format"
                ],
                "properties": {
                  "format": {
                    "type": "string",
                    "description": "File format (e.g. json, strings, xml). Must be file extension of any of the file formats we support. May also be <code>ios_sdk</code> or <code>android_sdk</code> for respective OTA SDK bundles."
                  },
                  "original_filenames": {
                    "type": "boolean",
                    "default": true,
                    "description": "Enable to use original filenames/formats. If set to <code>false</code> all keys will be export to a single file per language. Always <code>false</code> for the <code>offline_xliff</code> format."
                  },
                  "bundle_structure": {
                    "type": "string",
                    "description": "Bundle structure, used when <code>original_filenames</code> set to <code>false</code>). Allowed placeholders are <code>%LANG_ISO%</code>, <code>%LANG_NAME%</code>, <code>%FORMAT%</code> and <code>%PROJECT_NAME%</code>). Defaults to <code>locale/%LANG_ISO%.%FORMAT%</code>, or <code>%LANG_ISO%.lproj/Localizable.%FORMAT%</code> for the <code>ios_sdk</code> format."
                  },
                  "directory_prefix": {
                    "type": "string",
                    "description": "Directory prefix in the bundle, used when <code>original_filenames</code> set to <code>true</code>). Allowed placeholder is <code>%LANG_ISO%</code>. Defaults to <code>%LANG_ISO%/</code>, or <code>%LANG_ISO%.lproj/</code> for <code>strings</code> and <code>stringsdict</code>, and <code>values-%LANG_ISO%/</code> for <code>xml</code>."
                  },
                  "all_platforms": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable to include all platform keys. If disabled, only the keys, associated with the platform of the <code>format</code> will be exported."
                  },
                  "filter_langs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of languages to export. Omit this parameter for all languages."
                  },
                  "filter_data": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "last_reviewed_only",
                        "nonhidden",
                        "reviewed",
                        "reviewed_only",
                        "translated",
                        "untranslated",
                        "verified"
                      ]
                    },
                    "description": "Narrow export data range. Allowed values are <code>translated</code> or <code>untranslated</code>, <code>reviewed</code> (or <code>reviewed_only</code>), <code>last_reviewed_only</code>, <code>verified</code> and <code>nonhidden</code>."
                  },
                  "filter_filenames": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only keys attributed to selected files will be included. Leave empty for all."
                  },
                  "add_newline_eof": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable to add new line at end of file (if supported by format)."
                  },
                  "custom_translation_status_ids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only translations attributed to selected custom statuses will be included. Leave empty for all."
                  },
                  "include_tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Narrow export range to tags specified."
                  },
                  "exclude_tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Specify to exclude keys with these tags."
                  },
                  "export_sort": {
                    "type": "string",
                    "default": "a_z",
                    "description": "Export key sort mode. Allowed value are <code>first_added</code>, <code>last_added</code>, <code>last_updated</code>, <code>a_z</code>, <code>z_a</code>."
                  },
                  "export_empty_as": {
                    "type": "string",
                    "default": "empty",
                    "description": "Select how you would like empty translations to be exported. Allowed values are <code>empty</code> to keep empty, <code>base</code> to replace with the base language value, <code>null</code> to replace with null (YAML export only), or <code>skip</code> to omit.",
                    "enum": [
                      "base",
                      "empty",
                      "null",
                      "skip"
                    ]
                  },
                  "export_null_as": {
                    "type": "string",
                    "default": "empty",
                    "description": "(Ruby on Rails YAML export only) Select how you would like null (void) translations to be exported. Allowed values are <code>null</code> to keep null, <code>empty</code> to replace with empty string.",
                    "enum": [
                      "empty",
                      "null"
                    ]
                  },
                  "include_comments": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable to include key comments and description in exported file (if supported by the format)."
                  },
                  "include_description": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable to include key description in exported file (if supported by the format)."
                  },
                  "include_pids": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Other projects ID's, which keys should be included with this export."
                  },
                  "triggers": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "amazons3",
                        "azure",
                        "bitbucket",
                        "gcs",
                        "github",
                        "gitlab"
                      ]
                    },
                    "description": "Trigger integration exports (must be enabled in project settings). Allowed values are <code>amazons3</code>, <code>gcs</code>, <code>github</code>, <code>github-enterprise</code>, <code>gitlab</code>, <code>bitbucket</code>, <code>bitbucket-enterprise</code>, <code>azure</code>."
                  },
                  "filter_repositories": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Pull requests will be created only for listed repositories (<code>organization/repository</code> format). Leave empty array to process all configured integrations by platform only."
                  },
                  "replace_breaks": {
                    "type": "boolean",
                    "default": true,
                    "description": "Enable to replace line breaks in exported translations with \\n."
                  },
                  "disable_references": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable to skip automatic replace of key reference placeholders (e.g. [%key:hello_world%]) with their corresponding translations."
                  },
                  "plural_format": {
                    "type": "string",
                    "description": "Override the default plural format for the file type. Allowed values are <code>json_string</code>, <code>icu</code>, <code>array</code>, <code>generic</code>, <code>symfony</code>, <code>i18next</code>, <code>i18next_v4</code>. See Plurals and placeholders for more information about plural support for specific file formats.",
                    "enum": [
                      "array",
                      "generic",
                      "i18next",
                      "i18next_v4",
                      "icu",
                      "json_string",
                      "symfony"
                    ]
                  },
                  "placeholder_format": {
                    "type": "string",
                    "description": "Override the default placeholder format for the file type. Allowed values are <code>printf</code>, <code>ios</code>, <code>icu</code>, <code>net</code>, <code>symfony</code>, <code>i18n</code>, <code>raw</code>). See Plurals and placeholders for more information.",
                    "enum": [
                      "icu",
                      "ios",
                      "net",
                      "printf",
                      "symfony",
                      "i18n",
                      "raw"
                    ]
                  },
                  "webhook_url": {
                    "type": "string",
                    "description": "Once the export is complete, sends a HTTP POST with the generated bundle URL to the specified URL."
                  },
                  "language_mapping": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "original_language_iso": {
                          "type": "string",
                          "description": "Original language code as defined in language settings."
                        },
                        "custom_language_iso": {
                          "type": "string",
                          "description": "Language code to replace the original one with."
                        }
                      }
                    },
                    "description": "List of languages to override default iso codes for this export."
                  },
                  "icu_numeric": {
                    "type": "boolean",
                    "default": false,
                    "description": "If enabled, plural forms <code>zero</code>, <code>one</code> and <code>two</code> will be replaced with <code>=0</code>, <code>=1</code> and <code>=2</code> respectively. Only works for ICU plural format."
                  },
                  "escape_percent": {
                    "type": "boolean",
                    "default": false,
                    "description": "Only works for printf placeholder format. When enabled, all universal percent placeholders \"[%]\" will be always exported as \"%%\"."
                  },
                  "indentation": {
                    "type": "string",
                    "description": "Provide to override default indentation in supported files. Allowed values are <code>default</code>, <code>1sp</code>, <code>2sp</code>, <code>3sp</code>, <code>4sp</code>, <code>5sp</code>, <code>6sp</code>, <code>7sp</code>, <code>8sp</code> and <code>tab</code>.",
                    "enum": [
                      "1sp",
                      "2sp",
                      "3sp",
                      "4sp",
                      "5sp",
                      "6sp",
                      "7sp",
                      "8sp",
                      "default",
                      "tab"
                    ]
                  },
                  "yaml_include_root": {
                    "type": "boolean",
                    "default": false,
                    "description": "(YAML export only). Enable to include language ISO code as root key."
                  },
                  "json_unescaped_slashes": {
                    "type": "boolean",
                    "default": false,
                    "description": "(JSON export only). Enable to leave forward slashes unescaped."
                  },
                  "java_properties_encoding": {
                    "type": "string",
                    "default": "utf-8",
                    "description": "(Java Properties export only). Encoding for .properties files. Allowed values are <code>utf-8</code> and <code>latin-1</code>."
                  },
                  "java_properties_separator": {
                    "type": "string",
                    "default": "=",
                    "description": "(Java Properties export only). Separator for keys/values in .properties files. Allowed values are <code>=</code> and <code>:</code>."
                  },
                  "bundle_description": {
                    "type": "string",
                    "default": "",
                    "description": "Description of the created bundle. Applies to <code>ios_sdk</code> or <code>android_sdk</code> OTA SDK bundles."
                  },
                  "filter_task_id": {
                    "type": "number",
                    "description": "Only keys attributed to the task will be included. Available only for offline_xliff file format."
                  },
                  "compact": {
                    "type": "boolean",
                    "default": false,
                    "description": "(ARB export only). Export the minimum required structure for use in production. Don't include metadata such as context, comments and screenshots."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Token"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}
```