Skip to main content
Retrieves a file from storage by its path within your organization’s storage. Returns the file metadata and a download URL that you can use to access the file. 
GET https://api.worqhat.com/storage/fetch-by-path

​
What Does This Endpoint Do?

This endpoint allows you to retrieve a file using its path instead of its ID. Think of it like finding a file in a folder by its location - you provide the path to the file and get back the file information and a way to access it.

​
When to Use Fetch File by Path

You’ll find this endpoint useful when you need to:
  • Retrieve files by location: Get files when you know their path but not their ID
  • Access organized files: Retrieve files from specific folders you created
  • Build file browsers: Create interfaces that navigate by folder structure
  • Process files by category: Get files from specific organizational paths
  • Backup and restore: Retrieve files from known backup locations
  • Organize file access: Access files based on your organizational structure

​
How It Works

  1. You provide the file path (the path where the file is stored)
  2. The API looks up the file in your organization’s storage using the path
  3. The API returns file metadata and a signed download URL
  4. You can use the download URL to access the file (URL expires in 1 hour)

​
Code Examples

​
Example 1: Basic File Retrieval by Path

This example shows how to fetch a file using its path.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY, // Always use environment variables for API keys
});

async function fetchDocumentByPath() {
  try {
    const filePath = 'documents/invoices/invoice_2025.pdf';
    
    // Call the retrieveFileByPath method
    const response = await client.storage.retrieveFileByPath({
      filepath: filePath
    });
    
    // Handle the successful response
    console.log('File retrieved successfully!');
    console.log('File name:', response.file.filename);
    console.log('File size:', response.file.size, 'bytes');
    console.log('Download URL:', response.file.url);
    console.log('Full path:', response.file.path);
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error fetching file:', error.message);
  }
}

// Call the function
fetchDocumentByPath();

​
Example 2: Retrieve Files from Organized Structure

This example shows how to fetch files from different organizational paths.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';

// Initialize the client with your API key
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY,
});

async function fetchOrganizedFiles() {
  try {
    // Fetch files from different organized paths
    const paths = [
      'invoices/2025/january/invoice_001.pdf',
      'documents/contracts/contract_2025.pdf',
      'user-uploads/images/profile_photo.jpg'
    ];
    
    for (const path of paths) {
      try {
        const response = await client.storage.retrieveFileByPath({
          filepath: path
        });
        
        console.log(`Found file: ${response.file.filename} at ${path}`);
        console.log(`Size: ${response.file.size} bytes`);
        console.log(`Type: ${response.file.contentType}`);
      } catch (error) {
        console.log(`File not found at path: ${path}`);
      }
    }
  } catch (error) {
    console.error('Error fetching files:', error.message);
  }
}

fetchOrganizedFiles();

​
Request Parameters

​
filepath
string
required
The path to the file within your organization’s storage. This should match the path structure you used when uploading the file.Examples:
  • "documents/invoice.pdf"
  • "invoices/2025/january/invoice_001.pdf"
  • "user-uploads/images/profile.jpg"

​
Response Fields Explained

​
success
boolean
true if the file was retrieved successfully, false otherwise.
​
file
object
An object containing all the file metadata and information.
​
file.id
string
The unique identifier of the file.
​
file.filename
string
The original name of the file when it was uploaded.
​
file.path
string
The full path where the file is stored in your organization’s storage.
​
file.size
integer
The size of the file in bytes.
​
file.contentType
string
The MIME type of the file (e.g., “application/pdf”, “image/jpeg”).
​
file.uploadedAt
string
The timestamp when the file was originally uploaded (ISO 8601 format).
​
file.url
string
A signed URL for downloading the file. This URL expires in 1 hour and provides secure access to the file.

​
Example Response

{
  "success": true,
  "file": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filename": "invoice_2025.pdf",
    "path": "org_123/documents/invoices/invoice_2025.pdf",
    "size": 245678,
    "contentType": "application/pdf",
    "uploadedAt": "2025-07-26T03:28:08.123Z",
    "url": "https://storage.worqhat.com/org_123/documents/invoices/invoice_2025.pdf?signature=..."
  }
}

​
Common Errors and How to Fix Them

ErrorCauseSolution
”File not found”The file path doesn’t existCheck that the file path is correct and the file exists
”Invalid path format”The path format is incorrectUse proper path format without leading slashes
”Unauthorized”Invalid or missing API keyCheck that you’re using a valid API key
”File access denied”You don’t have permission to access this fileEnsure the file belongs to your organization

​
Tips for Successful File Retrieval by Path

  • Use consistent path structures when uploading files
  • Remember the exact path used during upload
  • Use organized folder structures for better file management
  • Handle missing files gracefully as paths might change
  • Consider using file IDs for more reliable file access
  • Document your path conventions for team consistency
⌘I