API Reference & Troubleshooting

Use Case Examples

Real-world examples showing how to integrate the Renamed.to API into common workflows. Each example includes complete code samples you can adapt for your needs.

async function processInvoice(file: File) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('strategy', 'by_date_issuer'); // Organize by year/vendor
  formData.append('templateMode', 'predefined');
  formData.append('templateId', 'standard'); // YYYY-MM-DD_Vendor_INV-Number.pdf

  const response = await fetch('https://www.renamed.to/api/v1/rename', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.RENAMED_TO_API_TOKEN}`
    },
    body: formData
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const result = await response.json();
  
  // Example result:
  // {
  //   "originalFilename": "invoice.pdf",
  //   "suggestedFilename": "2025-01-15_AcmeCorp_INV-12345.pdf",
  //   "folderPath": "2025/AcmeCorp",
  //   "confidence": 0.96
  // }
  
  return result;
}

async function renameWithLanguage(file: File, language: string) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('language', language); // 'de', 'fr', 'es', etc.
  formData.append('strategy', 'by_date_issuer');

  const response = await fetch('https://www.renamed.to/api/v1/rename', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.RENAMED_TO_API_TOKEN}`
    },
    body: formData
  });

  const result = await response.json();
  
  // With language='de':
  // {
  //   "originalFilename": "rechnung.pdf",
  //   "suggestedFilename": "2025-01-15_Musterfirma_Rechnung_12345.pdf",
  //   "folderPath": "2025/Musterfirma",
  //   "confidence": 0.95
  // }
  
  return result;
}

// Process files for different regions
const files = [
  { file: germanInvoice, language: 'de' },
  { file: frenchInvoice, language: 'fr' },
  { file: spanishInvoice, language: 'es' }
];

for (const { file, language } of files) {
  const result = await renameWithLanguage(file, language);
  console.log(`Renamed (${language}): ${result.suggestedFilename}`);
}

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format. All errors include an error field with a human-readable message.

Standard Error Response Format

All error responses follow this structure:

{
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Error Response Examples

{
  "error": "No file uploaded."
}

Retry Logic

Some errors are transient and can be retried. Follow these guidelines:

Idempotency

API requests are not idempotent by default. Each request consumes credits and processes files. If you need to retry a failed request:

• For 429 (Rate Limited) errors: Wait for the specified time, then retry the same request
• For 500/502 errors: Retry the same request with exponential backoff. Credits are only consumed on successful processing
• For 402 (Insufficient Credits): Add credits before retrying
• Note: If a file processing request fails after credits are deducted, credits are not automatically refunded. Contact support if you believe credits were incorrectly consumed.

Error Handling Best Practices

async function renameFileWithRetry(file: File, maxRetries = 3) {
  let lastError: Error | null = null;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const formData = new FormData();
      formData.append('file', file);
      
      const response = await fetch('https://www.renamed.to/api/v1/rename', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.RENAMED_TO_TOKEN}`
        },
        body: formData
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      const error = await response.json();
      
      // Don't retry non-retryable errors
      if ([400, 401, 402, 404, 413, 415].includes(response.status)) {
        throw new Error(`Non-retryable error: ${error.error}`);
      }
      
      // Handle rate limiting
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Waiting ${waitTime}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      // Retry server errors with exponential backoff
      if ([500, 502].includes(response.status)) {
        const waitTime = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        console.log(`Server error. Waiting ${waitTime}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      throw new Error(`Unexpected error: ${error.error}`);
    } catch (error) {
      lastError = error instanceof Error ? error : new Error(String(error));
      if (attempt === maxRetries - 1) {
        throw lastError;
      }
    }
  }
  
  throw lastError || new Error('Max retries exceeded');
}

Troubleshooting

Common issues and solutions when working with the Renamed.to API. If you encounter problems not covered here, contact support for assistance.

Common Issues and Solutions

import requests
import os

with open('document.pdf', 'rb') as f:
    # Include filename and content-type
    files = {'file': ('document.pdf', f, 'application/pdf')}
    headers = {'Authorization': f'Bearer {os.getenv("RENAMED_TO_TOKEN")}'}
    
    response = requests.post(
        'https://www.renamed.to/api/v1/rename',
        files=files,
        headers=headers
    )
    response.raise_for_status()

Limits & Quotas

The following limits apply to all API requests. Limits are enforced per account and reset on a rolling 24-hour window.

Rate Limiting

Rate limits use rolling windows, not fixed daily limits. This means limits reset continuously based on when requests are made, not at midnight UTC.

Rate Limit Headers

All API responses include rate limit information in headers. Check these headers to monitor your usage and handle rate limits gracefully:

Handling Rate Limits

When you receive a 429 Too Many Requests response:

1. Check the Retry-After header for the number of seconds to wait
2. Alternatively, calculate wait time from X-RateLimit-Reset timestamp
3. Wait for the specified duration before retrying
4. Implement exponential backoff if you continue to hit rate limits

Rate Limit Examples

const response = await fetch('https://www.renamed.to/api/v1/rename', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RENAMED_TO_TOKEN}`
  },
  body: formData
});

// Read rate limit headers
const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

console.log(`Rate limit: ${remaining}/${limit} remaining`);
console.log(`Resets at: ${new Date(parseInt(reset || '0')).toISOString()}`);

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  const waitSeconds = retryAfter ? parseInt(retryAfter) : 60;
  console.log(`Rate limited. Wait ${waitSeconds} seconds before retrying.`);
}

Frequently Asked Questions

Common questions about the Renamed.to REST API for programmatic file renaming.

How do I rename PDF files and scanned images using the API?

Upload a PDF file or scanned image (JPG, PNG, TIFF) via POST /api/v1/rename endpoint with Bearer token authentication. The service extracts metadata and returns a suggested filename with vendor, date, invoice number, and other relevant information. Scanned images use OCR to extract text content.

What file formats does the API support?

The API supports PDF files and scanned images (JPG, PNG, TIFF) up to 25 MB in size. Metadata extraction works with both native PDFs and scanned documents. Scanned images use OCR (Optical Character Recognition) to extract text content.

How many API calls can I make per day?

The API is rate-limited to 10,000 renames per day per account. Rate limits reset daily at midnight UTC. See the Limits section for more details.

Does the API support multiple languages?

Yes, the API supports 20+ languages for filename generation, including English, German, French, Spanish, Japanese, Chinese, Arabic, and more. Document types remain in English (e.g., "Invoice", "Receipt"), but issuer names and other text use the specified language. See the Language Options section for the complete list.

How do I get an API token?

Generate API tokens in Settings → API Tokens. Tokens are shown only once when created—make sure to save them securely. See the Authentication section for details.

How does automated file renaming work?

Automated file renaming extracts metadata from PDF documents (like vendor names, dates, invoice numbers, amounts, document types) and generates descriptive, consistent filenames. The service analyzes document content, structure, and context to identify key information without manual configuration.

Can I customize the filename format?

Yes, you can use predefined templates or provide custom prompts to control filename generation. The API supports three template modes: auto (service selects best pattern), predefined (use standard templates), and custom (provide natural language instructions). See the Template Modes section for details.

How accurate is the metadata extraction?

The service achieves high accuracy for most document types. Each response includes a confidence score so you can validate results before applying them. The API processes millions of documents including invoices, receipts, contracts, and legal documents.

What happens if I run out of credits?

If your account has 0 credits, API requests will return a 402 Payment Required error. You can check your credit balance using the Credits endpoint or purchase additional credits through your account settings.

Cloud integrations (OneDrive, Dropbox, Google Drive): If you run out of credits while files are being processed, those jobs will be automatically paused and marked as "pending credits." When you add credits to your account (via purchase or admin grant), processing will automatically resume for all pending jobs. Jobs older than 30 days will not be automatically retried to avoid processing outdated files.

Related Resources

Explore these resources to learn more about using Renamed.to for automated document organization.

Changelog

2025-11-11 – v1

• Changed configuration options from query parameters to POST body form fields (breaking change).
• Added folderPath to rename response.
• Added endpoints: GET /api/v1/user, GET /api/v1/credits, GET /api/v1/team. All endpoints support API token authentication.
• Enhanced documentation with examples for custom AI prompts and form fields.

2025-06-14 – v1 Initial Release

• Initial release – single rename endpoint.