# Upload a file through a connector

> Source: https://docs.clonepartner.com/api-reference/connectors/upload-connector-file/

`POST /api/connectors/{id}/files`

Multipart upload to a connector that implements file storage (csv, yaml, s3, azure-blob).
Requires admin or superadmin role. Max file size is controlled by `connectors.upload_max_bytes`
in the server config and defaults to 25 MiB.

**Operation ID:** `uploadConnectorFile`

## Authentication

### Option 1

- **BearerAuth** (`http bearer`)
  API key token. Create via POST /api/api-keys. Format: `envoy_<hex>`

### Option 2

- **CookieAuth** (`apiKey`)
  Session cookie set after login + TOTP verification

## Path parameters

- `id` — `integer`, `required`
  Resource ID

## Request body

The request body is required.

### `multipart/form-data`

- Type: `object`
- Properties:
  - `file` (`string`, `required`) — File contents to upload
    - Description: File contents to upload
    - Format: `binary`
  - `path` (`string`, `required`) — Destination path (S3 key, blob name, or relative path under csv/yaml directory)
  - `resource` (`string`) — Alias for path (accepted for compatibility)
  - `content_type` (`string`) — Optional Content-Type override
  - `overwrite` (`string`) — Set to "true" or "1" to replace an existing object
  - `metadata` (`string`) — JSON object of string metadata (object-store connectors only)

## Success responses

### 201

File uploaded

**Content type:** `application/json`

- Reference: `ConnectorFileUploadResponse`
  - Type: `object`
  - Properties:
    - `path` (`string`, `required`) — Uploaded destination path
    - `size` (`integer`) — Uploaded size in bytes
    - `content_type` (`string | null`)
      - Nullable: yes
    - `etag` (`string | null`)
      - Nullable: yes
    - `last_modified` (`string | null`)
      - Format: `date-time`
      - Nullable: yes
    - `url` (`string | null`) — Object URL when provided by the connector
      - Description: Object URL when provided by the connector
      - Nullable: yes

## Error responses

### 400

Validation error

**Content type:** `application/json`

- Reference: `Error`
  - Type: `object`
  - Properties:
    - `error` (`string`)
      - Example: `NOT_FOUND`
    - `message` (`string`)
      - Example: `Resource not found`

Example:

```json
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input"
}
```

### 403

Insufficient permissions


### 404

Resource not found

**Content type:** `application/json`

- Reference: `Error`
  - Type: `object`
  - Properties:
    - `error` (`string`)
      - Example: `NOT_FOUND`
    - `message` (`string`)
      - Example: `Resource not found`

Example:

```json
{
  "error": "NOT_FOUND",
  "message": "Resource not found"
}
```

### 409

File already exists and overwrite was not set

**Content type:** `application/json`

- Reference: `Error`
  - Type: `object`
  - Properties:
    - `error` (`string`)
      - Example: `NOT_FOUND`
    - `message` (`string`)
      - Example: `Resource not found`

### 413

File too large

**Content type:** `application/json`

- Reference: `Error`
  - Type: `object`
  - Properties:
    - `error` (`string`)
      - Example: `NOT_FOUND`
    - `message` (`string`)
      - Example: `Resource not found`

### 415

Unsupported file extension for connector type

**Content type:** `application/json`

- Reference: `Error`
  - Type: `object`
  - Properties:
    - `error` (`string`)
      - Example: `NOT_FOUND`
    - `message` (`string`)
      - Example: `Resource not found`

### 501

Connector type does not support file uploads

**Content type:** `application/json`

- Reference: `Error`
  - Type: `object`
  - Properties:
    - `error` (`string`)
      - Example: `NOT_FOUND`
    - `message` (`string`)
      - Example: `Resource not found`

## Examples

### cURL

```bash
curl --request POST \
  --url 'https://your-envoy.example.com/api/connectors/YOUR_ID/files' \
  --header 'Authorization: Bearer $API_KEY' \
  --form 'file=@path/to/file' \
  --form 'path=string'
```

### JavaScript (fetch)

```javascript
const form = new FormData();
form.append('file', file);
form.append('path', "string");

const response = await fetch('https://your-envoy.example.com/api/connectors/YOUR_ID/files', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: form,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = response.status === 204 ? null : await response.json();
console.log(data);
```