WorqHat
Storage

Initialize the client with your API key

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.

JavaScript

fetch-file-by-id.js

import Worqhat from 'worqhat';// Initialize the client with your API keyconst 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 functionfetchDocument();

Example 2: File Retrieval with Download

This example shows how to fetch a file and then download it.

JavaScript

fetch-and-download.js

import Worqhat from 'worqhat';import fs from 'fs';// Initialize the client with your API keyconst 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

fileIdstringpathrequired

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

successbooleanrequired

true if the file was retrieved successfully, false otherwise.

fileobjectrequired

An object containing all the file metadata and information.

file.idstringrequired

The unique identifier of the file.

file.filenamestringrequired

The original name of the file when it was uploaded.

file.pathstringrequired

The full path where the file is stored in your organization's storage.

file.sizeintegerrequired

The size of the file in bytes.

file.contentTypestringrequired

The MIME type of the file (e.g., "application/pdf", "image/jpeg").

file.uploadedAtstringrequired

The timestamp when the file was originally uploaded (ISO 8601 format).

file.urlstringrequired

A signed URL for downloading the file. This URL expires in 1 hour and provides secure access to the file.

Example Response

response.json

{"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