# Upload a resource file ZIP archive

`POST https://api.lingohub.com/v1/{workspaceUrl}/projects/{projectUrl}/resources/zip`

LingoHub API V1 · [Resources](https://developers.lingohub.com/reference/v1/operations/tags/resources.md) · operation `v1ResourceUploadResourceFileZip`

Uploads a ZIP archive containing multiple resource files to the specified project. The archive is extracted and all visible files within it are imported. Language detection is performed automatically based on file names and paths. Import behavior for source and target languages can be controlled through optional parameters.

## Parameters

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `workspaceUrl` | path | yes | string | workspaceUrl |
| `projectUrl` | path | yes | string | projectUrl |
| `source:createNew` | query | no | boolean | If this file belongs to the source language: If new segments should be created |
| `source:updateExisting` | query | no | boolean | If this file belongs to the source language: If changed segments should be updated |
| `source:deactivateMissing` | query | no | boolean | If this file belongs to the source language: If removed segments should be deactivated |
| `target:createNew` | query | no | boolean | If this file belongs to the target language: If new segments should be created |
| `target:updateExisting` | query | no | boolean | If this file belongs to the target language: If changed segments should be updated |
| `target:deactivateMissing` | query | no | boolean | If this file belongs to the target language: If removed segments should be deactivated |
| `branch` | query | no | string | Name of the project branch to import into. If omitted, the project's default branch is used. Returns 422 if the branch name does not exist in the project. |

## Example request

```sh
curl --request POST \
  --url https://api.lingohub.com/v1/WORKSPACE_URL/projects/PROJECT_URL/resources/zip \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@translations.json
```

## Responses

- `201`: Successfully uploaded and extracted the ZIP archive. All contained resource files have been scheduled for import.
- `400`: Bad Request: The ZIP archive is empty or contains no visible files.
- `401`: Unauthorized: Authentication credentials are missing or invalid.
- `403`: Forbidden: The authenticated user does not have resource management permission on this project.
- `404`: Not Found: The specified workspace or project does not exist.
- `422`: Unprocessable Entity: The specified branch name does not exist in the project, or an archive entry has an extension the project type cannot import (one files.invalid_extension error per entry, naming it).
- `500`: Internal Server Error: An unexpected error occurred during the import process.

## OpenAPI definition

The complete definition of this operation, with every schema it references:

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "LingoHub API V1",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.lingohub.com",
      "description": "Generated server url"
    }
  ],
  "tags": [
    {
      "name": "Resources",
      "description": "Endpoints for the operations that can be performed on the resource files"
    }
  ],
  "paths": {
    "/v1/{workspaceUrl}/projects/{projectUrl}/resources/zip": {
      "post": {
        "tags": [
          "Resources"
        ],
        "summary": "Upload a resource file ZIP archive",
        "description": "Uploads a ZIP archive containing multiple resource files to the specified project. The archive is extracted and all visible files within it are imported. Language detection is performed automatically based on file names and paths. Import behavior for source and target languages can be controlled through optional parameters.",
        "operationId": "v1ResourceUploadResourceFileZip",
        "parameters": [
          {
            "name": "workspaceUrl",
            "in": "path",
            "description": "workspaceUrl",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "projectUrl",
            "in": "path",
            "description": "projectUrl",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source:createNew",
            "in": "query",
            "description": "If this file belongs to the source language: If new segments should be created",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "source:updateExisting",
            "in": "query",
            "description": "If this file belongs to the source language: If changed segments should be updated",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "source:deactivateMissing",
            "in": "query",
            "description": "If this file belongs to the source language: If removed segments should be deactivated",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "target:createNew",
            "in": "query",
            "description": "If this file belongs to the target language: If new segments should be created",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "target:updateExisting",
            "in": "query",
            "description": "If this file belongs to the target language: If changed segments should be updated",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "target:deactivateMissing",
            "in": "query",
            "description": "If this file belongs to the target language: If removed segments should be deactivated",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "description": "Name of the project branch to import into. If omitted, the project's default branch is used. Returns 422 if the branch name does not exist in the project.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The zip file that will be uploaded"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully uploaded and extracted the ZIP archive. All contained resource files have been scheduled for import.",
            "content": {
              "application/json": {
                "examples": {
                  "zipUploadSuccess": {
                    "summary": "Successful ZIP upload",
                    "description": "zipUploadSuccess",
                    "value": {
                      "status": "Success"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request: The ZIP archive is empty or contains no visible files.",
            "content": {
              "application/json": {}
            }
          },
          "401": {
            "description": "Unauthorized: Authentication credentials are missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ErrorInfo"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden: The authenticated user does not have resource management permission on this project.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ErrorInfo"
                }
              }
            }
          },
          "404": {
            "description": "Not Found: The specified workspace or project does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ErrorInfo"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity: The specified branch name does not exist in the project, or an archive entry has an extension the project type cannot import (one files.invalid_extension error per entry, naming it).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ErrorResponse"
                },
                "examples": {
                  "unsupportedFile": {
                    "summary": "Unsupported file extension",
                    "description": "unsupportedFile",
                    "value": {
                      "validationErrors": [
                        {
                          "field": "files",
                          "errors": [
                            {
                              "code": "files.invalid_extension",
                              "description": "File 'Resources.en.txt' has an unsupported extension; this project imports: resx, resw.",
                              "parameters": {
                                "file": "Resources.en.txt"
                              }
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error: An unexpected error occurred during the import process.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1ErrorInfo"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "V1ErrorInfo": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "text": {
            "type": "string"
          }
        }
      },
      "V1ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/V1ErrorDetails"
          },
          "validationErrors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V1ValidationError"
            }
          }
        }
      },
      "V1ErrorDetails": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/HttpStatus"
          }
        }
      },
      "HttpStatus": {
        "allOf": [
          {
            "$ref": "#/components/schemas/HttpStatusCode"
          }
        ]
      },
      "HttpStatusCode": {
        "type": "object",
        "properties": {
          "error": {
            "type": "boolean"
          },
          "is4xxClientError": {
            "type": "boolean"
          },
          "is5xxServerError": {
            "type": "boolean"
          },
          "is1xxInformational": {
            "type": "boolean"
          },
          "is2xxSuccessful": {
            "type": "boolean"
          },
          "is3xxRedirection": {
            "type": "boolean"
          }
        }
      },
      "V1ValidationError": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V1FieldValidationError"
            }
          }
        }
      },
      "V1FieldValidationError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "parameters": {
            "type": "object",
            "additionalProperties": {}
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "API key authentication. Create API keys in your LingoHub workspace settings. Keys use the `lh-api_` prefix. Pass the full key as the Bearer token.",
        "scheme": "bearer"
      }
    }
  }
}
````
