LinkScale API (1.0.0)

Create a new shortened link with optional customization options

Retrieve a paginated list of your links with optional filtering

Retrieve detailed information about a specific link

Update an existing link (partial update). Only provided fields will be updated.

Permanently delete a link. This action cannot be undone.

Create a new template for the authenticated project with customization options

Retrieve all templates for the authenticated project

Retrieve a specific template by ID from the authenticated project

Update a specific template from the authenticated project. Only provided fields will be updated.

Permanently delete a template from the authenticated project. This action cannot be undone.

Generate a secure signature for uploading files directly to Uploadcare CDN.

Complete Upload Workflow

Step 1: Request Upload Signature

Call this endpoint to get a secure upload signature that expires after your specified time (default: 10 minutes).

const response = await fetch('https://dashboard.linkscale.to/api/v1/assets', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    expiration_minutes: 10
  })
});

const { upload_config, project } = await response.json();

Step 2: Upload File to Uploadcare

Use the signature to upload your file directly to Uploadcare using multipart/form-data.

Required FormData Fields:

• UPLOADCARE_PUB_KEY: Public key from upload_config
• UPLOADCARE_STORE: Set to 'auto' for automatic storage
• signature: Secure signature from upload_config
• expire: Unix timestamp from upload_config
• file: Your file as Blob/File object
• metadata[project_id]: Project ID from upload_config.metadata
• metadata[api_key_id]: API key ID from upload_config.metadata

Supported File Types:

• Images: PNG, JPEG, GIF, WebP, SVG
• Videos: MP4, WebM, MOV, AVI
• Audio: MP3, WAV, OGG, M4A
• Documents: PDF, ZIP, JSON, XML
• Text: TXT, CSV, HTML, CSS

Complete Upload Example (Browser):

const formData = new FormData();
formData.append('UPLOADCARE_PUB_KEY', upload_config.public_key);
formData.append('UPLOADCARE_STORE', 'auto');
formData.append('signature', upload_config.signature);
formData.append('expire', upload_config.expire.toString());
formData.append('file', fileInput.files[0]); // Browser File object
formData.append('metadata[project_id]', upload_config.metadata.project_id);
formData.append('metadata[api_key_id]', upload_config.metadata.api_key_id);

const uploadResponse = await fetch(upload_config.upload_url, {
  method: 'POST',
  body: formData
});

const { file: fileId } = await uploadResponse.json();
console.log('File ID:', fileId); // e.g., "17be4678-dab7-4bc7-8753-28914a22960a"

Complete Upload Example (Node.js):

const fs = require('fs');
const path = require('path');

// Read file and create Blob
const fileBuffer = fs.readFileSync('./image.jpg');
const fileName = path.basename('./image.jpg');

// Detect MIME type from extension
const mimeTypes = {
  '.png': 'image/png',
  '.jpg': 'image/jpeg',
  '.jpeg': 'image/jpeg',
  '.gif': 'image/gif',
  '.webp': 'image/webp',
  '.svg': 'image/svg+xml',
  '.mp4': 'video/mp4',
  '.webm': 'video/webm',
  '.pdf': 'application/pdf',
  '.json': 'application/json',
  '.txt': 'text/plain'
};

const fileExtension = path.extname('./image.jpg').toLowerCase();
const mimeType = mimeTypes[fileExtension] || 'application/octet-stream';
const fileBlob = new Blob([fileBuffer], { type: mimeType });

// Create FormData with all required fields
const formData = new FormData();
formData.append('UPLOADCARE_PUB_KEY', upload_config.public_key);
formData.append('UPLOADCARE_STORE', 'auto');
formData.append('signature', upload_config.signature);
formData.append('expire', upload_config.expire.toString());
formData.append('file', fileBlob, fileName);
formData.append('metadata[project_id]', upload_config.metadata.project_id);
formData.append('metadata[api_key_id]', upload_config.metadata.api_key_id);

const uploadResponse = await fetch(upload_config.upload_url, {
  method: 'POST',
  body: formData
});

const { file: fileId } = await uploadResponse.json();

Step 3: Poll for Validation

After uploading, poll GET /api/v1/assets/{file_id} until the file is validated (usually 2-3 seconds).

const pollValidation = async (fileId, maxAttempts = 10, delayMs = 2000) => {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`https://dashboard.linkscale.to/api/v1/assets/${fileId}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    
    if (response.ok) {
      const data = await response.json();
      console.log('✅ File validated!');
      return data; // Asset ready to use
    }
    
    if (response.status === 404) {
      console.log(`⏳ Still processing... (${i + 1}/${maxAttempts})`);
      await new Promise(resolve => setTimeout(resolve, delayMs));
      continue;
    }
    
    throw new Error('Validation failed');
  }
  throw new Error('Timeout - file may still be processing');
};

const asset = await pollValidation(fileId);
console.log('CDN URL:', asset.asset.provider_file_url);

Step 4: Use Your Asset

Once validated, use the provider_file_url from the asset object to access your file via CDN.

// Use in your application
const cdnUrl = asset.asset.provider_file_url;
// Example: "https://ucarecdn.com/17be4678-dab7-4bc7-8753-28914a22960a/"

Security Features

• Time-limited signatures: Signatures expire after specified time (1-60 minutes)
• MIME type restrictions: Optionally restrict allowed file types
• File size limits: Optionally set maximum file size in bytes
• Metadata tracking: Automatically tagged with project_id and api_key_id
• Direct upload: Files never transit through your server
• Automatic validation: Webhook validates files asynchronously
• Invalid files deleted: Files failing validation are automatically removed

Common MIME Types

Images:

• image/png - PNG images
• image/jpeg - JPEG images
• image/gif - GIF images
• image/webp - WebP images
• image/svg+xml - SVG images

Videos:

• video/mp4 - MP4 videos
• video/webm - WebM videos

Documents:

• application/pdf - PDF documents
• application/json - JSON files

Text:

• text/plain - Text files
• text/csv - CSV files

Expected Timing

• Signature generation: < 100ms
• Upload to Uploadcare: Depends on file size and connection
• Validation (webhook): 1-3 seconds (normal)
• Recommended polling: Every 2 seconds for max 30 seconds

Error Handling

Signature Request Errors:

• 400: Invalid expiration_minutes (must be 1-60)
• 401: Missing or invalid API key

Upload Errors:

• Check Uploadcare response for upload failures
• Common: signature expired, file too large, invalid MIME type

Validation Errors:

• 404: File not yet validated (keep polling)
• Timeout after 30 seconds: File may still be processing or failed validation

Retrieve a paginated list of all validated assets for your project with optional search and filtering.

Features:

• Search by filename or MIME type
• Filter by file category (image, video, audio, document, text)
• Pagination with limit and offset
• Returns rich metadata (file size, dimensions, duration, etc.)

File Type Categories:

• image: PNG, JPEG, GIF, WebP, SVG, etc.
• video: MP4, WebM, MOV, AVI, etc.
• audio: MP3, WAV, OGG, M4A, etc.
• application: PDF, ZIP, JSON, XML, etc.
• text: TXT, CSV, HTML, CSS, etc.

Use Cases:

• Display asset galleries
• File managers
• Search functionality
• Asset selection interfaces

Retrieve information about a specific asset by its Uploadcare file ID.

Primary Use: Validation Polling

After uploading a file to Uploadcare, you MUST poll this endpoint to verify the file has been validated by the webhook.

Why Polling is Required

The upload process is asynchronous:

1. You upload → File goes to Uploadcare CDN
2. Uploadcare → Sends webhook notification to LinkScale
3. LinkScale webhook → Validates file, extracts metadata (dimensions, duration, etc.)
4. Database → Asset saved with all metadata
5. You poll → Get confirmation that asset is ready

Processing includes:

• File metadata extraction (size, MIME type, filename)
• Image analysis (dimensions, format, color mode, DPI)
• Video analysis (duration, bitrate, codecs)
• Audio analysis (duration, bitrate, codec)
• Validation checks
• Automatic deletion of invalid files

Validation Flow

Upload to Uploadcare → Get file_id → Poll this endpoint → 200 OK → Use asset
                                        ↓
                                      404 = Still processing (wait 2s, retry)

Expected Timing

• Normal validation: 1-3 seconds
• Large files: Up to 5-10 seconds
• Recommended polling: Every 2 seconds
• Maximum attempts: 10-30 attempts (20-60 seconds total)
• Give up after: 30 seconds (file likely failed validation)

Complete Polling Implementation

Basic Polling (Recommended):

const pollValidation = async (fileId, maxAttempts = 10, delayMs = 2000) => {
  console.log('⏳ Polling for validation...');
  
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const response = await fetch(
        `https://dashboard.linkscale.to/api/v1/assets/${fileId}`,
        {
          method: 'GET',
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );
    
    if (response.ok) {
        const data = await response.json();
        console.log('✅ File validated and ready!');
        console.log('CDN URL:', data.asset.provider_file_url);
        return data;
    }
    
    if (response.status === 404) {
        console.log(`Attempt ${i + 1}/${maxAttempts}: Still processing...`);
        await new Promise(resolve => setTimeout(resolve, delayMs));
      continue;
    }
    
      // Other error
      const errorText = await response.text();
      throw new Error(`Validation check failed: ${response.status} - ${errorText}`);
      
    } catch (error) {
      console.warn(`Attempt ${i + 1}/${maxAttempts} error:`, error.message);
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
  
  throw new Error('Validation timeout - file may still be processing or failed');
};

// Usage
try {
  const asset = await pollValidation(fileId);
  // Asset is ready! Use the CDN URL
  const cdnUrl = asset.asset.provider_file_url;
  console.log('Use this URL:', cdnUrl);
} catch (error) {
  console.error('Upload failed:', error.message);
}

Advanced Polling with Exponential Backoff:

const pollValidationWithBackoff = async (fileId) => {
  const delays = [1000, 2000, 2000, 3000, 5000]; // Progressive delays
  
  for (let i = 0; i < delays.length; i++) {
    const response = await fetch(
      `https://dashboard.linkscale.to/api/v1/assets/${fileId}`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    );
    
    if (response.ok) {
      return await response.json(); // ✅ Success!
    }
    
    if (response.status === 404 && i < delays.length - 1) {
      console.log(`⏳ Waiting ${delays[i]}ms...`);
      await new Promise(r => setTimeout(r, delays[i]));
      continue;
    }
    
    if (response.status !== 404) {
      throw new Error(`Validation failed: ${response.status}`);
    }
  }
  
  throw new Error('Timeout after multiple attempts');
};

Response Data

Once validated (200 OK), the response includes:

• File metadata: ID, name, MIME type, size
• CDN URL: provider_file_url for accessing the file
• Upload info: Original upload timestamp
• Image metadata (if image): width, height, format, color mode, DPI
• Video metadata (if video): duration, bitrate, codecs
• Project info: Which project owns this asset

Error Handling

404 Response: File not yet validated

• Action: Wait 2 seconds and retry
• Normal: This is expected during polling
• Maximum retries: 10-30 attempts recommended

401 Response: Unauthorized

• Cause: Invalid or missing API key
• Action: Check your Authorization header

Other errors: Validation failed

• Action: File may be invalid or corrupted

Complete Upload + Polling Example

const uploadFile = async (file) => {
  // Step 1: Get signature
  const sigResponse = await fetch('https://dashboard.linkscale.to/api/v1/assets', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({ expiration_minutes: 10 })
  });
  
  const { upload_config } = await sigResponse.json();
  
  // Step 2: Upload to Uploadcare
  const formData = new FormData();
  formData.append('UPLOADCARE_PUB_KEY', upload_config.public_key);
  formData.append('UPLOADCARE_STORE', 'auto');
  formData.append('signature', upload_config.signature);
  formData.append('expire', upload_config.expire.toString());
  formData.append('file', file);
  formData.append('metadata[project_id]', upload_config.metadata.project_id);
  formData.append('metadata[api_key_id]', upload_config.metadata.api_key_id);
  
  const uploadResponse = await fetch(upload_config.upload_url, {
    method: 'POST',
    body: formData
  });
  
  const { file: fileId } = await uploadResponse.json();
  console.log('📤 File uploaded, ID:', fileId);
  
  // Step 3: Poll for validation (THIS ENDPOINT)
  const asset = await pollValidation(fileId);
  console.log('✅ Upload complete!');
  console.log('CDN URL:', asset.asset.provider_file_url);
  
  return asset;
};

Retrieve a simple list of all folders in your project without statistics or analytics.

This is a lightweight endpoint designed for quick folder listing. For detailed analytics and statistics, use /api/v1/folders/stats instead.

Key Features:

• Fast performance (no analytics computation)
• Returns basic folder information with links count
• Sorted by creation date (newest first)
• Requires folders.read permission

Use this endpoint when you need to:

• Display a folder selector/dropdown
• List available folders without analytics
• Get folder metadata quickly

Use /api/v1/folders/stats when you need:

• Traffic analytics and statistics
• Date-range based metrics
• Detailed performance data

Get comprehensive statistics for your entire project. Supports optional timezone and lazy-loading of traffic data via traffic_data_type.

Get statistics for all folders in your project.

Get detailed statistics for a specific folder. Supports optional timezone and lazy-loading of traffic data via traffic_data_type.

Retrieve analytics data for a specific link within a date range. Includes click aggregates from ClickHouse.

Authorization: Bearer API key

Required permission: statistics.read_link

Backward compatible: Existing fields unchanged; new field analytics.clicks added.