Renamed.to REST API v1

Getting Started

Get up and running with the Renamed.to REST API in minutes. Follow these steps to make your first API call and start renaming PDF files programmatically.

curl -X POST https://www.renamed.to/api/v1/rename \
  -H "Authorization: Bearer rt_your_token_here" \
  -F file=@invoice.pdf

Common Issues

Next Steps

• Read the Authentication section for detailed token management
• Explore the Rename endpoint documentation for advanced options
• Review Error Handling to implement robust error handling
• Check out Use Case Examples for real-world integration patterns
• See Troubleshooting for solutions to common problems

API Versioning

The Renamed.to API uses URL-based versioning to ensure stability and backward compatibility as we evolve the platform.

Current Version

The current API version is v1, accessible at:

Versioning Policy

Requesting a Specific Version

The API version is specified in the URL path. Always include the version number in your requests:

Version Headers

While versioning is handled via URL path, API responses include version information in headers:

Staying Up to Date

To stay informed about API changes and version updates:

• Check the Changelog section for recent updates
• Subscribe to our API changelog RSS feed (coming soon)
• Monitor the API-Version header in responses
• Follow our status page for API availability and incidents

Authentication

Every request must be authenticated using a Bearer token. API tokens are long-lived API keys that provide full access to your account.

Token Format

API tokens are prefixed with rt_ followed by 64 hexadecimal characters. Example: rt_abc123def456...

Getting Your Token

Generate API tokens in the API Tokens section of your settings. Tokens are shown only once when created—make sure to save them securely.

Using Your Token

Include your token in the Authorization header with the Bearer prefix:

curl -X GET https://www.renamed.to/api/v1/user \
  -H "Authorization: Bearer rt_your_token_here"

Token Permissions

API tokens provide access to all API endpoints, including file renaming, user profile information, credit balance, and team information.

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

Token Security

• Store tokens securely—never commit them to version control or expose them in client-side code
• Use environment variables or secure secret management systems
• Rotate tokens regularly by creating new tokens and deleting old ones from Settings → API Tokens
• If a token is compromised, delete it immediately from your settings

Endpoint – Rename a file

POST /api/v1/rename

Request

Upload a PDF file using multipart form-data. The service automatically analyzes the document content to extract metadata (vendor names, dates, invoice numbers, amounts, document types) and generates a descriptive filename.

Request fields:

Language Examples

Here are examples showing how filenames differ based on the language parameter:

// Request
POST /api/v1/rename
language=en

// Result
{
  "suggestedFilename": "2025-01-15_AcmeCorp_Invoice_12345.pdf",
  "folderPath": "2025/AcmeCorp"
}

Common Mistakes

Successful response (200)

The service analyzes your PDF file and returns a response with the generated filename based on extracted metadata:

{
  "originalFilename": "invoice.pdf",
  "suggestedFilename": "2025-01-15_invoice_1234_acme.pdf",
  "folderPath": "2025/AcmeCorp/Invoices"
}

Response Fields

Organization Strategies

Organization strategies determine how files are organized into folder structures. The folder path uses forward slashes (/) as separators.

Template Modes

Template modes control how filenames are generated. Choose the mode that best fits your needs:

Language Options

Control the language used for generated filenames and folder names. The service will use the specified language for issuer names and other text extracted from documents. Document type names remain in English (e.g., "Invoice", "Receipt"), but company names, vendor names, and other metadata will be formatted in the selected language.

Error responses

Error responses follow this format:

Python File Upload Requirements

Code Examples

Production-ready examples with error handling, validation, and timeout support. The service automatically analyzes uploaded PDF files to extract metadata and generate filenames. Choose the example that matches your environment:

# Rename a messy invoice file
# The service analyzes the PDF content and extracts metadata (vendor, date, invoice number)
curl -X POST https://www.renamed.to/api/v1/rename \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F file=@"Invoice_scan_IMG_20251215.pdf" \
  -F strategy="by_date_issuer" \
  -F language="en"

# Response:
# {
#   "originalFilename": "Invoice_scan_IMG_20251215.pdf",
#   "suggestedFilename": "2025-12-15_invoice_acme_corp_inv-12345.pdf",
#   "folderPath": "2025/AcmeCorp/Invoices"
# }

# Use custom AI prompt for filename generation
curl -X POST https://www.renamed.to/api/v1/rename \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F file=@"invoice.pdf" \
  -F templateMode="custom" \
  -F customTemplate="Use format: YYYY-MM-DD_company-name_document-type_number"

Endpoint – Rename a file from URL

POST /api/v1/rename-from-url

Request

Provide a publicly accessible URL to a PDF file. The service downloads the file, analyzes its content to extract metadata (vendor names, dates, invoice numbers, amounts, document types), and generates a descriptive filename. This endpoint is ideal for automation workflows where files are already hosted online.

Note: This endpoint requires authentication (API token or session). Credits are only deducted after successful processing to avoid charging for failed downloads or invalid files.

Request body (JSON):

Successful response (200)

The service downloads the PDF file from the provided URL, analyzes its content, and returns a response with the generated filename based on extracted metadata. The response format is identical to the Rename endpoint.

{
  "originalFilename": "invoice.pdf",
  "suggestedFilename": "2025-01-15_invoice_1234_acme.pdf",
  "folderPath": "2025/AcmeCorp/Invoices"
}

Error responses

Security & URL validation

Code Examples

Production-ready examples with error handling and validation. The service downloads the PDF from the URL, analyzes its content, and generates a filename:

# Rename a PDF file from a public URL
curl -X POST https://www.renamed.to/api/v1/rename-from-url \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://example.com/invoices/invoice_2025.pdf",
    "strategy": "by_date_issuer",
    "language": "en"
  }'

Use Cases

Endpoint – Get user profile

GET /api/v1/user

Description

Returns basic profile information for the authenticated user (the user to which the API token belongs), including id, email, and name.

Successful response (200)

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe"
}

Error responses

Code Examples

curl -X GET https://www.renamed.to/api/v1/user \
  -H "Authorization: Bearer rt_your_token_here"

Endpoint – Get credit balance

GET /api/v1/credits

Description

Returns the current credit balance for the authenticated user. Credits are consumed when renaming files via the API.

Successful response (200)

{
  "credits": 150
}

Error responses

Code Examples

curl -X GET https://www.renamed.to/api/v1/credits \
  -H "Authorization: Bearer rt_your_token_here"

Endpoint – Get team information

GET /api/v1/team

Description

Returns team information if the authenticated user is part of a team. Returns null if not part of a team.

Successful response (200)

{
  "id": "team_123",
  "name": "Acme Corp",
  "teamMembers": [
    {
      "user": {
        "id": "user_123",
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ]
}

Error responses

Code Examples

curl -X GET https://www.renamed.to/api/v1/team \
  -H "Authorization: Bearer rt_your_token_here"

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 using the API?

Upload a PDF file 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.

What file formats does the API support?

The API currently supports PDF files up to 25 MB in size. Metadata extraction works with both native PDFs and scanned documents.

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.