API Reference

Upload a file through a connector

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 IDuploadConnectorFile

Authentication

BearerAuth·http bearer·API key token (envoy_<hex>). Create keys from Settings → API Keys — see Using the API.

Path parameters

idintegerrequired

Resource ID

Request body

This request body is required.

Content typemultipart/form-data

requestobject

6 properties

filestring · binaryrequired

File contents to upload

pathstringrequired

Destination path (S3 key, blob name, or relative path under csv/yaml directory)

resourcestring

Alias for path (accepted for compatibility)

content_typestring

Optional Content-Type override

overwritestring

Set to "true" or "1" to replace an existing object

metadatastring

JSON object of string metadata (object-store connectors only)

Success response body

201File uploaded

File uploaded

Content typeapplication/json

responseobject

6 properties

pathstringrequired

Uploaded destination path

sizeinteger

Uploaded size in bytes

content_typestring | null

Nullable: yes

etagstring | null

Nullable: yes

last_modifiedstring | null · date-time

Nullable: yes

urlstring | null

Object URL when provided by the connector

Nullable: yes

Error responses

400Validation error

Validation error

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

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

403Insufficient permissions

Insufficient permissions

No response content schema is documented.

404Resource not found

Resource not found

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

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

409File already exists and overwrite was not set

File already exists and overwrite was not set

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

413File too large

File too large

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

415Unsupported file extension for connector type

Unsupported file extension for connector type

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

501Connector type does not support file uploads

Connector type does not support file uploads

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Code examples

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'

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);