Upload a file

The File Upload API allows you to programmatically manage files in your File Upload connectors. This guide explains how to use the API to list, upload, and delete files.

Prerequisites

Before using the File Upload API, you need:

A Vectorize account with API access
An API token (see Managing Access Tokens)
Your organization ID (found in the URL of the Vectorize platform)
A File Upload connector ID (created either through the UI or API)

Authentication

All API requests require authentication using your API token. Set the token in the Authorization header of your requests:

Authorization: your-token-here

API Endpoints

The base URL for the Vectorize API is:

https://api.vectorize.io/v1

Listing Files

To list all files in a connector, use the following endpoint:

GET /org/{org_id}/uploads/{connector_id}/files

Example

Python
Node.js

import os
import requests

# Authentication
token = os.getenv("VECTORIZE_TOKEN")
base_url = "https://api.vectorize.io/v1"

def list_files(org_id: str, connector_id: str):
    """
    List files in the specified connector.
    
    :param org_id: Your organization ID
    :param connector_id: The ID of the connector to list files for
    :return: The list of files
    """
    url = f"{base_url}/org/{org_id}/uploads/{connector_id}/files"
    headers = {"Authorization": token}

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        files = response.json()
        print(f"Files in connector {connector_id}: {files}")
        return files
    else:
        print(f"Error listing files: {response.status_code}")
        print(response.text)
        return []

const axios = require('axios');

// Authentication
const token = process.env.VECTORIZE_TOKEN;
const baseUrl = 'https://api.vectorize.io/v1';

/**
 * List files in the specified connector
 * 
 * @param {string} orgId - Your organization ID
 * @param {string} connectorId - The ID of the connector to list files for
 * @returns {Promise<Array>} - The list of files
 */
async function listFiles(orgId, connectorId) {
  try {
    const url = `${baseUrl}/org/${orgId}/uploads/${connectorId}/files`;
    const headers = { Authorization: token };
    
    const response = await axios.get(url, { headers });
    console.log(`Files in connector ${connectorId}:`, response.data);
    return response.data;
  } catch (error) {
    console.error(`Error listing files: ${error.response?.status}`);
    console.error(error.response?.data);
    return [];
  }
}

Response

A successful response will return a JSON object containing the list of files:

{
  "files": [
    {
      "name": "example.pdf",
      "size": 1234567,
      "contentType": "application/pdf",
      "uploadDate": "2023-05-01T12:34:56Z",
      "metadata": {
        "field-1": "example-value"
      }
    },
    // Additional files...
  ]
}

Uploading Files

Uploading a file is a two-step process:

Initiate the upload to get a pre-signed URL
Upload the file content to the pre-signed URL

Step 1: Initiate the Upload

PUT /org/{org_id}/uploads/{connector_id}/files

Request Body

{
  "name": "filename.pdf",
  "contentType": "application/pdf",
  "metadata": {
    "field-1": "example-value",
    "field-2": ["value1", "value2"],
    "field-3": {"nested": "value"}
  }
}

The metadata field is optional and can be used to store additional information about the file.

Step 2: Upload to Pre-signed URL

Use the URL returned from Step 1 to upload the file content.

Example

Python
Node.js

import os
import requests
import json
import mimetypes

# Authentication
token = os.getenv("VECTORIZE_TOKEN")
base_url = "https://api.vectorize.io/v1"

def upload_file(org_id: str, connector_id: str, file_path: str, metadata: dict = None):
    """
    Upload a file to the specified connector with optional metadata.

    :param org_id: Your organization ID
    :param connector_id: The ID of the connector to upload the file to
    :param file_path: The path to the file to upload
    :param metadata: Optional metadata to include with the upload
    :return: None
    """
    # Endpoint for direct file upload
    url = f"{base_url}/org/{org_id}/uploads/{connector_id}/files"
    
    # Set headers
    headers = {
        "Authorization": token,
        "Content-Type": "application/json"
    }
    
    # Determine file name and content type
    file_name = os.path.basename(file_path)
    content_type = mimetypes.guess_type(file_path)[0] or "application/octet-stream"
    
    # Prepare the request body
    request_body = {
        "name": file_name,
        "contentType": content_type
    }
    
    # Add metadata if provided
    if metadata:
        request_body["metadata"] = json.dumps(metadata)
    
    # Send PUT request with JSON body to initiate the upload
    put_response = requests.put(url, headers=headers, json=request_body)
    
    if put_response.status_code != 200:
        print(f"Error starting upload: {put_response.status_code}")
        print(put_response.text)
        return
    
    # Get upload URL from response
    upload_data = put_response.json()
    upload_url = upload_data.get("uploadUrl")
    
    if not upload_url:
        print("Error: No upload URL received")
        print(upload_data)
        return
    
    # Now upload the actual file to the provided URL
    with open(file_path, "rb") as file:
        upload_headers = {
            "Content-Type": content_type
        }
        upload_response = requests.put(upload_url, headers=upload_headers, data=file)
    
    if upload_response.status_code == 200:
        print("File uploaded successfully")
    else:
        print(f"Error uploading file: {upload_response.status_code}")
        print(upload_response.text)

const axios = require('axios');
const fs = require('fs');
const path = require('path');
const mime = require('mime-types');

// Authentication
const token = process.env.VECTORIZE_TOKEN;
const baseUrl = 'https://api.vectorize.io/v1';

/**
 * Upload a file to the specified connector with optional metadata
 * 
 * @param {string} orgId - Your organization ID
 * @param {string} connectorId - The ID of the connector to upload the file to
 * @param {string} filePath - The path to the file to upload
 * @param {Object} metadata - Optional metadata to include with the upload
 * @returns {Promise<void>}
 */
async function uploadFile(orgId, connectorId, filePath, metadata = null) {
  try {
    // Endpoint for direct file upload
    const url = `${baseUrl}/org/${orgId}/uploads/${connectorId}/files`;
    
    // Set headers
    const headers = {
      Authorization: token,
      'Content-Type': 'application/json'
    };
    
    // Determine file name and content type
    const fileName = path.basename(filePath);
    const contentType = mime.lookup(filePath) || 'application/octet-stream';
    
    // Prepare the request body
    const requestBody = {
      name: fileName,
      contentType: contentType
    };
    
    // Add metadata if provided
    if (metadata) {
      requestBody.metadata = JSON.stringify(metadata);
    }
    
    // Send PUT request with JSON body to initiate the upload
    const putResponse = await axios.put(url, requestBody, { headers });
    
    // Get upload URL from response
    const uploadData = putResponse.data;
    const uploadUrl = uploadData.uploadUrl;
    
    if (!uploadUrl) {
      console.error('Error: No upload URL received');
      console.error(uploadData);
      return;
    }
    
    // Now upload the actual file to the provided URL
    const fileContent = fs.readFileSync(filePath);
    const uploadHeaders = {
      'Content-Type': contentType
    };
    
    const uploadResponse = await axios.put(uploadUrl, fileContent, { 
      headers: uploadHeaders 
    });
    
    console.log('File uploaded successfully');
  } catch (error) {
    console.error(`Error: ${error.response?.status || error.message}`);
    console.error(error.response?.data);
  }
}

Response from Step 1

{
  "uploadUrl": "https://presigned-url-for-upload.example.com",
  "fileName": "filename.pdf"
}

Deleting Files

To delete a file from a connector, use the following endpoint:

DELETE /org/{org_id}/uploads/{connector_id}/files

Request Body

{
  "fileName": "filename.pdf"
}

Example

Python
Node.js

import os
import requests

# Authentication
token = os.getenv("VECTORIZE_TOKEN")
base_url = "https://api.vectorize.io/v1"

def delete_file(org_id: str, connector_id: str, file_name: str):
    """
    Delete a file from the specified connector.

    :param org_id: Your organization ID
    :param connector_id: The ID of the connector to delete the file from
    :param file_name: The name of the file to delete
    :return: None
    """
    url = f"{base_url}/org/{org_id}/uploads/{connector_id}/files"
    headers = {"Authorization": token}

    response = requests.delete(url, headers=headers, json={"fileName": file_name})
    if response.status_code == 200:
        print("File deleted successfully:", response.json())
    else:
        print(f"Error deleting file: {response.status_code}")
        print(response.text)

const axios = require('axios');

// Authentication
const token = process.env.VECTORIZE_TOKEN;
const baseUrl = 'https://api.vectorize.io/v1';

/**
 * Delete a file from the specified connector
 * 
 * @param {string} orgId - Your organization ID
 * @param {string} connectorId - The ID of the connector to delete the file from
 * @param {string} fileName - The name of the file to delete
 * @returns {Promise<void>}
 */
async function deleteFile(orgId, connectorId, fileName) {
  try {
    const url = `${baseUrl}/org/${orgId}/uploads/${connectorId}/files`;
    const headers = { Authorization: token };
    
    const response = await axios.delete(url, { 
      headers, 
      data: { fileName: fileName } 
    });
    
    console.log('File deleted successfully:', response.data);
  } catch (error) {
    console.error(`Error deleting file: ${error.response?.status}`);
    console.error(error.response?.data);
  }
}

Response

{
  "success": true,
  "message": "File deleted successfully"
}

Complete Example

Here's a complete example that demonstrates listing files, uploading a file with metadata, and deleting a file:

Python
Node.js

import os
import requests
import json
import mimetypes

# Authentication and configuration
token = os.getenv("VECTORIZE_TOKEN")
base_url = "https://api.vectorize.io/v1"
org_id = "your-organization-id"
connector_id = "your-connector-id"
file_path = "path/to/your/file.pdf"

# Example metadata
metadata = {
    "field-1": "example-value",
    "field-2": ["value1", "value2"],
    "field-3": {"nested": "value"}
}

def list_files(org_id: str, connector_id: str):
    """List files in the specified connector."""
    url = f"{base_url}/org/{org_id}/uploads/{connector_id}/files"
    headers = {"Authorization": token}

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        files = response.json()
        print(f"Files in connector {connector_id}: {files}")
        return files
    else:
        print(f"Error listing files: {response.status_code}")
        print(response.text)
        return []

def upload_file(org_id: str, connector_id: str, file_path: str, metadata: dict = None):
    """Upload a file to the specified connector with optional metadata."""
    url = f"{base_url}/org/{org_id}/uploads/{connector_id}/files"
    
    headers = {
        "Authorization": token,
        "Content-Type": "application/json"
    }
    
    file_name = os.path.basename(file_path)
    content_type = mimetypes.guess_type(file_path)[0] or "application/octet-stream"
    
    request_body = {
        "name": file_name,
        "contentType": content_type
    }
    
    if metadata:
        request_body["metadata"] = json.dumps(metadata)
    
    put_response = requests.put(url, headers=headers, json=request_body)
    
    if put_response.status_code != 200:
        print(f"Error starting upload: {put_response.status_code}")
        print(put_response.text)
        return
    
    upload_data = put_response.json()
    upload_url = upload_data.get("uploadUrl")
    
    if not upload_url:
        print("Error: No upload URL received")
        print(upload_data)
        return
    
    with open(file_path, "rb") as file:
        upload_headers = {
            "Content-Type": content_type
        }
        upload_response = requests.put(upload_url, headers=upload_headers, data=file)
    
    if upload_response.status_code == 200:
        print("File uploaded successfully")
    else:
        print(f"Error uploading file: {upload_response.status_code}")
        print(upload_response.text)

def delete_file(org_id: str, connector_id: str, file_name: str):
    """Delete a file from the specified connector."""
    url = f"{base_url}/org/{org_id}/uploads/{connector_id}/files"
    headers = {"Authorization": token}

    response = requests.delete(url, headers=headers, json={"fileName": file_name})
    if response.status_code == 200:
        print("File deleted successfully:", response.json())
    else:
        print(f"Error deleting file: {response.status_code}")
        print(response.text)

# Example usage
if __name__ == "__main__":
    try:
        # List files before any action
        print("Listing files before any action:")
        list_files(org_id, connector_id)

        # Upload file without metadata
        print("\nUploading file without metadata:")
        upload_file(org_id, connector_id, file_path)

        # List files after upload without metadata
        print("\nListing files after upload without metadata:")
        list_files(org_id, connector_id)
        
        # Delete file
        print("\nDeleting file:")
        file_name = os.path.basename(file_path)
        delete_file(org_id, connector_id, file_name)
        
        # List files after deletion
        print("\nListing files after deletion:")
        list_files(org_id, connector_id)

        # Upload file with metadata
        print("\nUploading file with metadata:")
        upload_file(org_id, connector_id, file_path, metadata)

        # List files after upload with metadata
        print("\nListing files after upload with metadata:")
        list_files(org_id, connector_id)

        # Delete file
        print("\nDeleting file:")
        delete_file(org_id, connector_id, file_name)

        # List files after deletion
        print("\nListing files after deletion:")
        list_files(org_id, connector_id)
        
    except Exception as e:
        print(f"Error: {e}")

const axios = require('axios');
const fs = require('fs');
const path = require('path');
const mime = require('mime-types');

// Authentication and configuration
const token = process.env.VECTORIZE_TOKEN;
const baseUrl = 'https://api.vectorize.io/v1';
const orgId = 'your-organization-id';
const connectorId = 'your-connector-id';
const filePath = 'path/to/your/file.pdf';

// Example metadata
const metadata = {
  'field-1': 'example-value',
  'field-2': ['value1', 'value2'],
  'field-3': {'nested': 'value'}
};

/**
 * List files in the specified connector
 */
async function listFiles(orgId, connectorId) {
  try {
    const url = `${baseUrl}/org/${orgId}/uploads/${connectorId}/files`;
    const headers = { Authorization: token };
    
    const response = await axios.get(url, { headers });
    console.log(`Files in connector ${connectorId}:`, response.data);
    return response.data;
  } catch (error) {
    console.error(`Error listing files: ${error.response?.status}`);
    console.error(error.response?.data);
    return [];
  }
}

/**
 * Upload a file to the specified connector with optional metadata
 */
async function uploadFile(orgId, connectorId, filePath, metadata = null) {
  try {
    const url = `${baseUrl}/org/${orgId}/uploads/${connectorId}/files`;
    
    const headers = {
      Authorization: token,
      'Content-Type': 'application/json'
    };
    
    const fileName = path.basename(filePath);
    const contentType = mime.lookup(filePath) || 'application/octet-stream';
    
    const requestBody = {
      name: fileName,
      contentType: contentType
    };
    
    if (metadata) {
      requestBody.metadata = JSON.stringify(metadata);
    }
    
    const putResponse = await axios.put(url, requestBody, { headers });
    
    const uploadData = putResponse.data;
    const uploadUrl = uploadData.uploadUrl;
    
    if (!uploadUrl) {
      console.error('Error: No upload URL received');
      console.error(uploadData);
      return;
    }
    
    const fileContent = fs.readFileSync(filePath);
    const uploadHeaders = {
      'Content-Type': contentType
    };
    
    const uploadResponse = await axios.put(uploadUrl, fileContent, { 
      headers: uploadHeaders 
    });
    
    console.log('File uploaded successfully');
  } catch (error) {
    console.error(`Error: ${error.response?.status || error.message}`);
    console.error(error.response?.data);
  }
}

/**
 * Delete a file from the specified connector
 */
async function deleteFile(orgId, connectorId, fileName) {
  try {
    const url = `${baseUrl}/org/${orgId}/uploads/${connectorId}/files`;
    const headers = { Authorization: token };
    
    const response = await axios.delete(url, { 
      headers, 
      data: { fileName: fileName } 
    });
    
    console.log('File deleted successfully:', response.data);
  } catch (error) {
    console.error(`Error deleting file: ${error.response?.status}`);
    console.error(error.response?.data);
  }
}

// Example usage
async function main() {
  try {
    // List files before any action
    console.log('Listing files before any action:');
    await listFiles(orgId, connectorId);

    // Upload file without metadata
    console.log('\nUploading file without metadata:');
    await uploadFile(orgId, connectorId, filePath);

    // List files after upload without metadata
    console.log('\nListing files after upload without metadata:');
    await listFiles(orgId, connectorId);
    
    // Delete file
    console.log('\nDeleting file:');
    const fileName = path.basename(filePath);
    await deleteFile(orgId, connectorId, fileName);
    
    // List files after deletion
    console.log('\nListing files after deletion:');
    await listFiles(orgId, connectorId);

    // Upload file with metadata
    console.log('\nUploading file with metadata:');
    await uploadFile(orgId, connectorId, filePath, metadata);

    // List files after upload with metadata
    console.log('\nListing files after upload with metadata:');
    await listFiles(orgId, connectorId);

    // Delete file
    console.log('\nDeleting file:');
    await deleteFile(orgId, connectorId, fileName);

    // List files after deletion
    console.log('\nListing files after deletion:');
    await listFiles(orgId, connectorId);
    
  } catch (error) {
    console.error(`Error: ${error.message}`);
  }
}

main();

API Reference

For a complete reference of the File Upload API, see the Vectorize API Reference.

Prerequisites​

Authentication​

API Endpoints​

Listing Files​

Example​

Response​

Uploading Files​

Step 1: Initiate the Upload​

Request Body​

Step 2: Upload to Pre-signed URL​

Example​

Response from Step 1​

Deleting Files​

Request Body​

Example​

Response​

Complete Example​

API Reference​

Prerequisites

Authentication

API Endpoints

Listing Files

Example

Response

Uploading Files

Step 1: Initiate the Upload

Request Body

Step 2: Upload to Pre-signed URL

Example

Response from Step 1

Deleting Files

Request Body

Example

Response

Complete Example

API Reference