# Upload a resource file

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

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

Uploads a single resource file to the specified project. The file's language is detected automatically from the file name, or can be explicitly set via the iso2_slug/iso2_code parameter. Import behavior for source and target languages (create new segments, update existing, deactivate missing) can be controlled through optional parameters. If the upload might cause a file name collision, set force=true to proceed.

## Parameters

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `workspaceUrl` | path | yes | string | workspaceUrl |
| `projectUrl` | path | yes | string | projectUrl |
| `path` | query | no | string | Path the resource container (file) will be uploaded to |
| `iso2_slug` | query | no | string | The iso code of the resource file locale. Overrides the language information that might be given in the path. Alias of 'iso2_code'. |
| `iso2_code` | query | no | string | The iso code of the resource file locale. Overrides the language information that might be given in the path. Alias of 'iso2_slug'. |
| `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 |
| `force` | query | no | boolean | Force the upload. Override potential security measures, eg. a collision between file names |
| `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 \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@translations.json
```

## Responses

- `201`: Successfully uploaded the resource file.
- `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.
- `406`: Not Acceptable: A file name collision was detected and force=true was not set. Specify a path or use force=true to override.
- `422`: Unprocessable Entity: The specified branch name does not exist in the project, or the file has an extension the project type cannot import (error code files.invalid_extension, naming the file).
- `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": {
      "post": {
        "tags": [
          "Resources"
        ],
        "summary": "Upload a resource file",
        "description": "Uploads a single resource file to the specified project. The file's language is detected automatically from the file name, or can be explicitly set via the iso2_slug/iso2_code parameter. Import behavior for source and target languages (create new segments, update existing, deactivate missing) can be controlled through optional parameters. If the upload might cause a file name collision, set force=true to proceed.",
        "operationId": "v1ResourceUploadResourceFile",
        "parameters": [
          {
            "name": "workspaceUrl",
            "in": "path",
            "description": "workspaceUrl",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "projectUrl",
            "in": "path",
            "description": "projectUrl",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "path",
            "in": "query",
            "description": "Path the resource container (file) will be uploaded to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "iso2_slug",
            "in": "query",
            "description": "The iso code of the resource file locale. Overrides the language information that might be given in the path. Alias of 'iso2_code'.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "iso2_code",
            "in": "query",
            "description": "The iso code of the resource file locale. Overrides the language information that might be given in the path. Alias of 'iso2_slug'.",
            "required": false,
            "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": "force",
            "in": "query",
            "description": "Force the upload. Override potential security measures, eg. a collision between file names",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "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": "File that will be uploaded"
                  }
                },
                "required": [
                  "file"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully uploaded the resource file.",
            "content": {
              "application/json": {
                "examples": {
                  "uploadSuccess": {
                    "summary": "Successful upload",
                    "description": "uploadSuccess",
                    "value": {
                      "status": "Success"
                    }
                  }
                }
              }
            }
          },
          "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"
                }
              }
            }
          },
          "406": {
            "description": "Not Acceptable: A file name collision was detected and force=true was not set. Specify a path or use force=true to override.",
            "content": {
              "application/json": {
                "examples": {
                  "collisionDetected": {
                    "summary": "Path collision detected",
                    "description": "collisionDetected",
                    "value": {
                      "status": "Not acceptable",
                      "message": "A situation has been detected that might lead to an unwanted upload action..."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity: The specified branch name does not exist in the project, or the file has an extension the project type cannot import (error code files.invalid_extension, naming the file).",
            "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"
      }
    }
  }
}
````
