> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elanlanguages.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File Management

> On this page, we'll dive into the different file management endpoints you can use to manage translation files.

File management endpoints allow you to upload, list, download, and delete translation files. These endpoints support files up to 100MB in size and provide a simple way to manage your translation file storage.

## The translation file upload response model

The upload response model contains information about the uploaded file.

### Properties

<ResponseField name="message" type="string">
  A message describing the result of the operation.
</ResponseField>

<ResponseField name="file_name" type="string">
  The name of the uploaded file.
</ResponseField>

<ResponseField name="file_type" type="string">
  The file extension type.
</ResponseField>

<ResponseField name="file_size" type="integer">
  Size of the file in bytes.
</ResponseField>

<ResponseField name="uploaded_at" type="timestamp">
  Timestamp of when the file was uploaded.
</ResponseField>

***

## The translation file list response model

The list response model contains information about files in a folder.

### Properties

<ResponseField name="files" type="array">
  Array of file objects in the folder.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of files in the folder.
</ResponseField>

<ResponseField name="folder_path" type="string">
  The folder path that was listed.
</ResponseField>

***

## The translation file delete response model

The delete response model confirms the file deletion.

### Properties

<ResponseField name="message" type="string">
  A message describing the result of the operation.
</ResponseField>

<ResponseField name="deleted_file" type="string">
  The path of the deleted file.
</ResponseField>

***

## Upload a translation file

**`POST /files/upload`**

This endpoint allows you to upload a file to be translated. The maximum file size is 100MB.

### Required attributes

<ParamField body="file" type="file" required>
  The file to upload (max 100MB).
</ParamField>

<ParamField body="folder_path" type="string" required>
  Storage location for the file.
</ParamField>

### Optional attributes

<ParamField header="X-Org-Id" type="string">
  Organization identifier (header). If not provided, uses your default organization.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.elanlanguages.ai/v1/files/upload \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -F "file=@/path/to/file.txt" \
    -F "folder_path=/translations"
  ```
</CodeGroup>

```json Response theme={null}
{
  "message": "File uploaded successfully",
  "file_name": "file.txt",
  "file_type": "txt",
  "file_size": 1024,
  "uploaded_at": "2025-12-21T10:30:00.000Z"
}
```

***

## List translation files

**`GET /v1/files/list`**

This endpoint allows you to list translation files in a specific folder.

### Required attributes

<ParamField query="folder_path" type="string" required>
  Directory path for file listing.
</ParamField>

### Optional attributes

<ParamField header="X-Org-Id" type="string">
  Organization identifier (header). If not provided, uses your default organization.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.elanlanguages.ai/v1/files/list \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -d folder_path="/translations"
  ```
</CodeGroup>

```json Response theme={null}
{
  "files": [
    {
      "file_name": "file.txt",
      "file_path": "/translations/file.txt",
      "size": 1024,
      "modified_at": "2025-12-21T10:30:00Z"
    }
  ],
  "total": 1,
  "folder_path": "/translations"
}
```

***

## Download a translation file

**`GET /v1/files/download`**

This endpoint allows you to download a translation file. File path should have URL-encoded special characters.

### Required attributes

<ParamField query="file_path" type="string" required>
  File location (URL encoded).
</ParamField>

### Optional attributes

<ParamField header="X-Org-Id" type="string">
  Organization identifier (header). If not provided, uses your default organization.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.elanlanguages.ai/v1/files/download \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -d file_path="/translations/file.txt" \
    -o downloaded_file.txt
  ```
</CodeGroup>

The file will be downloaded directly. Make sure to properly URL-encode the file\_path parameter if it contains special characters.

***

## Get file details

**`GET /v1/files/details`**

This endpoint allows you to retrieve details about a file, including analysis results such as word count and detected language. You can poll this endpoint after upload to check when background analysis completes (`analysis_status` changes from `pending` to `completed`).

### Required attributes

<ParamField query="file_path" type="string" required>
  File location to inspect.
</ParamField>

### Optional attributes

<ParamField header="X-Org-Id" type="string">
  Organization identifier (header). If not provided, uses your default organization.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.elanlanguages.ai/v1/files/details \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -d file_path="/translations/file.txt"
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": 1,
  "s3_key": "translations/file.txt",
  "file_name": "file.txt",
  "file_type": "txt",
  "file_size": 1024,
  "mime_type": "text/plain",
  "uploaded_at": "2025-12-21T10:30:00.000Z",
  "word_count": 182,
  "detected_language": "en",
  "detected_language_confidence": 0.98,
  "analysis_status": "completed"
}
```

***

## Get a file stream URL

**`GET /v1/files/stream-url`**

This endpoint returns a short-lived presigned GET URL for streaming a file directly from S3. This is useful for media playback, as it allows the browser to range-request (and seek) large files such as videos instead of downloading the whole object through the API.

### Required attributes

<ParamField query="file_path" type="string" required>
  Unprefixed file key (the form returned by the upload endpoint).
</ParamField>

### Optional attributes

<ParamField header="X-Org-Id" type="string">
  Organization identifier (header). If not provided, uses your default organization.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.elanlanguages.ai/v1/files/stream-url \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -d file_path="/translations/file.txt"
  ```
</CodeGroup>

The response contains a short-lived presigned URL that can be used to stream the file directly from S3.

***

## Delete a translation file

**`DELETE /v1/files/delete`**

This endpoint allows you to delete a translation file.

### Required attributes

<ParamField query="file_path" type="string" required>
  File location to remove.
</ParamField>

### Optional attributes

<ParamField header="X-Org-Id" type="string">
  Organization identifier (header). If not provided, uses your default organization.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.elanlanguages.ai/v1/files/delete \
    -H "Authorization: Bearer {token}" \
    -H "X-Org-Id: {orgId}" \
    -d file_path="/translations/file.txt"
  ```
</CodeGroup>

```json Response theme={null}
{
  "message": "File deleted successfully",
  "deleted_file": "/translations/file.txt"
}
```