{"openapi":"3.1.0","info":{"title":"Localizely API","description":"<h2>Getting started</h2><p>Localizely API is built on <a href=\"https://en.wikipedia.org/wiki/Representational_state_transfer\" target=\"_blank\">REST</a>. <br>You can use this API for importing & exporting your localization files in order to automate the process with `curl` scripts or external <a href=\"https://en.wikipedia.org/wiki/Continuous_integration\" target=\"_blank\">CI</a> tools. <br>Response is returned in JSON form even in case of error. <br></p><p>If you Authenticate with your API token on this page by clicking \"Authorize\" button, you can make API calls directly from here with \"Try it out\", and generate such `curl` examples. </p><h2>API Authentication</h2><p>Authenticate your account by sending your API token as a request header `X-Api-Token`. <br>The token can be found under <a href=\"https://app.localizely.com/account\" target=\"_blank\">My Profile</a> page. <br>A user must have an Admin role in the project in order to access the project with his token. <br>API requests without authentication will fail.</p><h2>Rate Limiting</h2><p>Access to all endpoints is limited to 400 requests per minute. This limit is applied per API token and per IP address. If you exceed the limit, a 429 HTTP status code will be returned. <br>If you should need higher rate limits, <a href=\"https://app.localizely.com/support\" target=\"_blank\">contact us</a>.</p><p><b>Base url:</b> `https://api.localizely.com`</p>","termsOfService":"https://localizely.com/terms-of-service/","version":"1.2.1"},"servers":[{"url":"https://api.localizely.com","description":"Generated server url"}],"paths":{"/v1/projects/{project_id}/files/upload":{"post":{"tags":["Upload API"],"summary":"Upload translations for a language","operationId":"importLocalizationFile","parameters":[{"name":"project_id","in":"path","description":"Project ID - Can be found on 'My projects' page","required":true,"schema":{"type":"string"}},{"name":"branch","in":"query","description":"Name of the branch to upload file into. Only in case of activated branching feature.","required":false,"schema":{"type":"string"}},{"name":"lang_code","in":"query","description":"Language to upload, specified as language code. e.g. `en`, `en_GB` or `en-GB`","required":true,"schema":{"type":"string"}},{"name":"overwrite","in":"query","description":"If translation in given language should be overwritten with modified translation from uploading file.","required":false,"schema":{"type":"boolean","default":false}},{"name":"reviewed","in":"query","description":"If uploading translations, that are added, should be marked as Reviewed. For uploading translations that are only modified it will have effect only if `overwrite` is set to `true`. When omitted, file formats with a translation state (iOS xcstrings) set it per translation from that state (`translated` is reviewed, `needs_review` and `new` are not; in the main language only `needs_review` is not reviewed), other formats import as not reviewed.","required":false,"schema":{"type":"boolean"}},{"name":"tag_added","in":"query","description":"Optional list of tags to add to new translations from uploading file. <br><br>Multiple tags can be defined in a following way: `&tag_added_keys=NEW&tag_added_keys=NEW_SPRINT05`","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"tag_updated","in":"query","description":"Optional list of tags to add to updated translations from uploading file. <br><br>Multiple tags can be defined in a following way: `&tag_updated_keys=UPDATED&tag_updated_keys=UPDATED_SPRINT05`","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"tag_removed","in":"query","description":"Optional list of tags to add to removed translations from uploading file. <br><br>Multiple tags can be defined in a following way: `&tag_removed_keys=REMOVED&tag_removed_keys=REMOVED_SPRINT05`","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"tag_in_file","in":"query","description":"Optional. Tags that mirror the file: added to every string key present in the file and removed from the string keys of the branch that are not in the file. One tag per platform or app (e.g. `android`) routes string keys to the right download via `include_tags`.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"placeholder_format","in":"query","description":"Optional. Placeholder syntax of the file, only for projects with universal placeholders and generic file formats (JSON, properties, CSV, XLSX, XLIFF). Allowed values are `printf_java`, `printf_ios`, `printf_c`, `icu`, `dotnet`, `ruby`, `i18next` and `raw`. Defaults to the project setting. Opinionated formats (Android, iOS, ARB, RESX, Rails, gettext) always use their own syntax; `raw` disables conversion for any format.","required":false,"schema":{"type":"string","enum":["printf_java","printf_ios","printf_c","icu","dotnet","ruby","i18next","raw"]}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Uploading file. Supported following formats: `Flutter ARB, Android XML, iOS strings, iOS stringsdict, iOS xcstrings, XLIFF (Angular XLF, Articulate Rise 360, ...), Gettext PO, Gettext POT, Java properties, Ruby on Rails yaml, .NET resx, flat json, csv, Excel .xlsx, Excel .xls`"}},"required":["file"]}}}},"responses":{"400":{"description":"Error codes:<br />&nbsp;<br />- `invalid_import_file` when file invalid. Returned with `errors` list<br />- `max_upload_size_exceeded` when uploading file exceeds size limit<br />- `upgrade_required` when uploading more string keys than accepted by owner's account plan limit<br />- `projects_limit_read_only` when project is in read-only state due to exceeded projects limit\n`'bad_request'` when request generally is not well formed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/InvalidImportFileErrorDto"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"200":{"description":"OK, file uploaded"}},"security":[{"API auth":[]}]}},"/v1/projects/{project_id}/branches/{branch}":{"post":{"tags":["Branch API"],"summary":"Create a new branch","operationId":"createBranch","parameters":[{"name":"project_id","in":"path","description":"Project ID - Can be found on 'My projects' page","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"branch","in":"path","description":"Name of the branch to be created","required":true,"schema":{"type":"string","maxLength":200,"minLength":0}},{"name":"source_branch","in":"query","description":"Name of the source branch from which new branch will be created","required":true,"schema":{"type":"string"}}],"responses":{"400":{"description":"Error codes:<br />&nbsp;<br />- `bad_request` when request generally is not well formed<br />- `limit_reached` when project already has max allowed number of branches<br />- `projects_limit_read_only` when project is in read-only state due to exceeded projects limit","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"200":{"description":"OK, created"}},"security":[{"API auth":[]}]}},"/v1/projects/{project_id}/status":{"get":{"tags":["Translation Status API"],"summary":"Get Translation Status for the project","operationId":"getTranslationStatus","parameters":[{"name":"project_id","in":"path","description":"Project ID - Can be found on 'My projects' page","required":true,"schema":{"type":"string"}},{"name":"branch","in":"query","description":"Name of the branch to get translation status for. Only in case of activated branching feature.","required":false,"schema":{"type":"string"}}],"responses":{"400":{"description":"Error codes:<br />&nbsp;<br />- `bad_request` when request generally is not well formed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"200":{"description":"OK, data returned","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ProjectStatusDto"}}}}},"security":[{"API auth":[]}]}},"/v1/projects/{project_id}/files/download":{"get":{"tags":["Download API"],"summary":"Download translations for a language in a specified file format","description":"<b>Note:</b> This endpoint is intended for getting translation files to your source-code. This endpoint should not be called directly from you app in runtime, as it has <b>rate-limiting</b>. <br/>For over-the-air translation updates please consider using our <a href=\"https://localizely.com/flutter-over-the-air/\" target=\"_blank\">SDK for Flutter</a> or <a href=\"https://localizely.com/aws-s3-integration/\" target=\"_blank\">integrate with AWS S3 bucket</a>.","operationId":"getLocalizationFile","parameters":[{"name":"project_id","in":"path","description":"Project ID - Can be found on 'My projects' page","required":true,"schema":{"type":"string"}},{"name":"branch","in":"query","description":"Name of the branch to download file from. Only in case of activated branching feature.","required":false,"schema":{"type":"string"}},{"name":"lang_codes","in":"query","description":"Language to download, specified as language code. e.g. `en`, `en_GB` or `en-GB`. For multiple languages use comma separator. If omitted, all languages are downloaded.","required":false,"schema":{"type":"string"}},{"name":"type","in":"query","description":"File format","required":true,"schema":{"type":"string","enum":["android_xml","ios_strings","ios_stringsdict","ios_xcstrings","java_properties","rails_yaml","angular_xlf","xliff","flutter_arb","dotnet_resx","po","pot","json","csv","xlsx"]}},{"name":"java_properties_encoding","in":"query","description":"(Only for Java .properties files download) Character encoding. Default is `latin_1`.","required":false,"schema":{"type":"string","enum":["utf_8","latin_1"]}},{"name":"include_tags","in":"query","description":"Optional list of tags to be downloaded. <br>If not set, all string keys will be considered for download. <br><br>Multiple tags can be defined in a following way: `&include_tags=ANDROID&include_tags=ANDROID_SPRINT05`.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"exclude_tags","in":"query","description":"Optional list of tags to be excluded from download. <br>If not set, all string keys will be considered for download. <br><br> Multiple tags can be defined in a following way: `&exclude_tags=REMOVED&exclude_tags=REMOVED_SPRINT05`.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"export_empty_as","in":"query","description":"Optional. How you would like empty translations to be exported. Allowed values are `empty` to keep empty, `main` to replace with the main language value, or `skip` to omit.","required":false,"schema":{"type":"string","default":"empty","enum":["empty","main","skip"]}},{"name":"placeholder_format","in":"query","description":"Optional. Placeholder syntax of the file, only for projects with universal placeholders and generic file formats (JSON, properties, CSV, XLSX, XLIFF). Allowed values are `printf_java`, `printf_ios`, `printf_c`, `icu`, `dotnet`, `ruby`, `i18next` and `raw`. Defaults to the project setting. Opinionated formats (Android, iOS, ARB, RESX, Rails, gettext) always use their own syntax; `raw` disables conversion for any format.","required":false,"schema":{"type":"string","enum":["printf_java","printf_ios","printf_c","icu","dotnet","ruby","i18next","raw"]}}],"responses":{"400":{"description":"Error codes:<br />&nbsp;<br />- `file_download_excel_cell_too_long` when some translations exceed Excel cell limit (returns int parameter: 'errorData.cellCharsLimit')<br />- `invalid_export_data_rails_yaml` when data collision for yaml download<br />- `bad_request` when request generally is not well formed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"404":{"description":"Not Found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDto"}}}},"200":{"description":"OK, file returned"}},"security":[{"API auth":[]}]}}},"components":{"schemas":{"ErrorDto":{"type":"object","properties":{"errorCode":{"type":"string","enum":["already_exists","too_long","too_many_requests","bad_request","not_configured","bad_captcha","bad_turnstile","bad_url","confirmation_invalid","ownership_transfer_required","forbidden_email","main_locale_invalid","branching_disabled","not_activated","invalid_password","invalid_import_file","invalid_export_data_rails_yaml","forbidden","internal_error","not_found","upgrade_required","subscription_change_disabled_in_past_due","subscription_creation_still_processing","order_creation_still_processing","branching_not_supported","string_keys_limit","projects_limit","projects_limit_read_only","limit_reached","import_keys_limit_exceeded","max_upload_size_exceeded","file_download_excel_cell_too_long","prevention_limit_reached","tags_prevention_limit_reached","string_key_not_found","qa_checks_failed","merge_outdated","mt_locale_not_supported","mt_main_translation_empty","mt_main_translation_not_supported","mt_source_translation_too_long","mt_chars_missing","mt_no_selected_strings","ait_locale_not_supported","ait_main_translation_empty","ait_main_translation_not_supported","ait_source_translation_too_long","ait_chars_missing","ait_no_selected_strings","ait_in_progress","placeholder_normalization_in_progress","placeholder_name_invalid","tm_upload_file_invalid","tm_upload_file_max_entries_exceeded","tm_upload_file_version_not_supported","tm_max_total_entries_exceeded","tm_max_total_memories_exceeded","glossary_locale_cant_remove","glossary_upload_file_invalid","glossary_upload_file_column_separator_invalid","glossary_upload_file_headers_invalid","glossary_upload_file_max_terms_exceeded","glossary_max_total_terms_exceeded","glossary_max_total_glossaries_exceeded","order_oversize","github_token_invalid","github_token_scope_invalid","github_url_invalid","github_branch_invalid","github_repo_invalid","github_config_file_missing","github_config_file_invalid","github_push_no_changes","github_invalid_export_data","gitlab_token_invalid","gitlab_token_scope_invalid","gitlab_url_invalid","gitlab_branch_invalid","gitlab_repo_invalid","gitlab_config_file_missing","gitlab_config_file_invalid","gitlab_push_no_changes","gitlab_invalid_export_data","bitbucket_token_invalid","bitbucket_token_scope_invalid","bitbucket_url_invalid","bitbucket_branch_invalid","bitbucket_repo_invalid","bitbucket_config_file_missing","bitbucket_config_file_invalid","bitbucket_push_no_changes","bitbucket_invalid_export_data","aws_s3_credentials_invalid","aws_s3_permissions_invalid","aws_s3_bucket_invalid","aws_s3_region_invalid","join_request_already_pending","expired","unauthorized","unexpected_error","service_unavailable"]},"errorMessage":{"type":"string"},"errorData":{"type":"object","additionalProperties":{}}}},"ImportFileError":{"type":"object","properties":{"line":{"type":"integer","format":"int32"},"position":{"type":"integer","format":"int32"},"errorMessage":{"type":"string"}}},"InvalidImportFileErrorDto":{"type":"object","properties":{"errorCode":{"type":"string","enum":["already_exists","too_long","too_many_requests","bad_request","not_configured","bad_captcha","bad_turnstile","bad_url","confirmation_invalid","ownership_transfer_required","forbidden_email","main_locale_invalid","branching_disabled","not_activated","invalid_password","invalid_import_file","invalid_export_data_rails_yaml","forbidden","internal_error","not_found","upgrade_required","subscription_change_disabled_in_past_due","subscription_creation_still_processing","order_creation_still_processing","branching_not_supported","string_keys_limit","projects_limit","projects_limit_read_only","limit_reached","import_keys_limit_exceeded","max_upload_size_exceeded","file_download_excel_cell_too_long","prevention_limit_reached","tags_prevention_limit_reached","string_key_not_found","qa_checks_failed","merge_outdated","mt_locale_not_supported","mt_main_translation_empty","mt_main_translation_not_supported","mt_source_translation_too_long","mt_chars_missing","mt_no_selected_strings","ait_locale_not_supported","ait_main_translation_empty","ait_main_translation_not_supported","ait_source_translation_too_long","ait_chars_missing","ait_no_selected_strings","ait_in_progress","placeholder_normalization_in_progress","placeholder_name_invalid","tm_upload_file_invalid","tm_upload_file_max_entries_exceeded","tm_upload_file_version_not_supported","tm_max_total_entries_exceeded","tm_max_total_memories_exceeded","glossary_locale_cant_remove","glossary_upload_file_invalid","glossary_upload_file_column_separator_invalid","glossary_upload_file_headers_invalid","glossary_upload_file_max_terms_exceeded","glossary_max_total_terms_exceeded","glossary_max_total_glossaries_exceeded","order_oversize","github_token_invalid","github_token_scope_invalid","github_url_invalid","github_branch_invalid","github_repo_invalid","github_config_file_missing","github_config_file_invalid","github_push_no_changes","github_invalid_export_data","gitlab_token_invalid","gitlab_token_scope_invalid","gitlab_url_invalid","gitlab_branch_invalid","gitlab_repo_invalid","gitlab_config_file_missing","gitlab_config_file_invalid","gitlab_push_no_changes","gitlab_invalid_export_data","bitbucket_token_invalid","bitbucket_token_scope_invalid","bitbucket_url_invalid","bitbucket_branch_invalid","bitbucket_repo_invalid","bitbucket_config_file_missing","bitbucket_config_file_invalid","bitbucket_push_no_changes","bitbucket_invalid_export_data","aws_s3_credentials_invalid","aws_s3_permissions_invalid","aws_s3_bucket_invalid","aws_s3_region_invalid","join_request_already_pending","expired","unauthorized","unexpected_error","service_unavailable"]},"errorMessage":{"type":"string"},"errorData":{"type":"object","additionalProperties":{}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ImportFileError"}}}},"ProjectLocaleStatsDto":{"type":"object","properties":{"langCode":{"type":"string","description":"Language code (ie `en` or `en-US`)"},"langName":{"type":"string","description":"Language name (ie `English` or `English (US)`)"},"strings":{"type":"integer","format":"int32","description":"Total number of string keys in the project"},"reviewed":{"type":"integer","format":"int32","description":"Number of reviewed string keys for a language"},"reviewedProgress":{"type":"integer","format":"int32","description":"Reviewed progress for a language, in percentage"}}},"ProjectStatusDto":{"type":"object","properties":{"strings":{"type":"integer","format":"int32","description":"Total number of string keys in the project"},"reviewedProgress":{"type":"integer","format":"int32","description":"Total reviewed progress across all languages, in percentage"},"languages":{"type":"array","description":"Translation status per language","items":{"$ref":"#/components/schemas/ProjectLocaleStatsDto"}}}}},"securitySchemes":{"API auth":{"type":"apiKey","name":"X-Api-Token","in":"header"}}}}