Skip to main content
Retrieves a file from storage by its unique ID. Returns the file metadata and a download URL that you can use to access the file. 
GET https://api.worqhat.com/storage/fetch/{fileId}

​
What Does This Endpoint Do?

This endpoint allows you to retrieve a file that you previously uploaded to WorqHat storage. Think of it like getting a file from a secure locker - you provide the unique key (file ID) and get back the file information and a way to access it.

​
When to Use Fetch File by ID

You’ll find this endpoint useful when you need to:
  • Retrieve uploaded files: Get files that were previously uploaded
  • Generate download links: Create temporary URLs for file downloads
  • Check file metadata: Get information about file size, type, and upload date
  • Verify file existence: Check if a file still exists in storage
  • Build file management systems: Create interfaces for users to access their files
  • Process stored files: Retrieve files for AI processing or analysis

​
How It Works

  1. You provide the file ID (obtained when you uploaded the file)
  2. The API looks up the file in your organization’s storage
  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

This example shows how to fetch a file using its ID.
  • 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 fetchDocument() {
  try {
    const fileId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
    
    // Call the retrieveFileByID method
    const response = await client.storage.retrieveFileByID(fileId);
    
    // 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('Uploaded at:', response.file.uploadedAt);
    return response;
  } catch (error) {
    // Handle any errors
    console.error('Error fetching file:', error.message);
  }
}

// Call the function
fetchDocument();

​
Example 2: File Retrieval with Download

This example shows how to fetch a file and then download it.
  • Node.js
  • Python
  • Go
  • cURL
import Worqhat from 'worqhat';
import fs from 'fs';

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

async function downloadDocument() {
  try {
    const fileId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
    
    // Fetch file metadata
    const response = await client.storage.retrieveFileByID(fileId);
    
    // Download the file using the signed URL
    const downloadResponse = await fetch(response.file.url);
    const fileBuffer = await downloadResponse.arrayBuffer();
    
    // Save the file locally
    fs.writeFileSync(`./downloads/${response.file.filename}`, Buffer.from(fileBuffer));
    
    console.log(`File downloaded: ${response.file.filename}`);
    console.log(`File size: ${response.file.size} bytes`);
    return response;
  } catch (error) {
    console.error('Error downloading file:', error.message);
  }
}

downloadDocument();

​
Request Parameters

​
fileId
string
required
The unique identifier of the file to retrieve. This is the ID that was returned when you uploaded the file.Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
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 ID doesn’t exist or has been deletedCheck that the file ID is correct and the file still exists
”Invalid file ID”The file ID format is incorrectUse a valid UUID format for the file ID
”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

  • Save file IDs when you upload files so you can retrieve them later
  • Use the download URL quickly as it expires in 1 hour
  • Check file existence before trying to download large files
  • Handle errors gracefully when files might have been deleted
  • Consider caching file metadata for frequently accessed files
  • Use appropriate file types based on the content type returned
⌘I