Renamed.to REST API v1

Programmatically rename files with AI-extracted metadata. The API is JSON-first, secured by HTTPS and rate-limited to 40 000 renames/day per account.

https://renamed.to/api/v1

Authentication

Every request must be authenticated. There are two supported methods:

Session cookie (Browser) – automatically sent after you log in via the web app.
Bearer token – Send Authorization: Bearer <JWT>. You can generate a token in the API Tokens section.

Note: The free anonymous batch on the landing page is not available through the API.

Endpoint – Rename a file

POST /api/v1/rename

Request

Multipart form-data with a single field:

Field	Type	Notes
`file`	File	Max 10 MB. PDF, JPG, PNG, TIFF, HEIC.

Successful response (200)

{
  "originalFilename": "invoice.pdf",
  "suggestedFilename": "2024-01-15_invoice_1234_acme.pdf"
}

Error responses

Status	Code	Description
401	unauthorized	Missing / invalid credentials or free batch exhausted.
402	payment_required	Account has 0 credits.
413	payload_too_large	File exceeds 10 MB limit.
415	unsupported_media_type	File type not supported.
500	server_error	Unhandled processing error.

Quick Start

# Rename a messy invoice file
curl -X POST https://renamed.to/api/v1/rename \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F file=@"Invoice_scan_IMG_20241215.pdf"

# Response: "2024-12-15_invoice_acme_corp_inv-12345.pdf"

JavaScript/TypeScript

// Rename files in your Node.js app
import { readFile } from 'fs/promises';

async function renameDocument(filePath: string) {
  const file = await readFile(filePath);
  const formData = new FormData();
  formData.append('file', new Blob([file]), filePath.split('/').pop());

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

  const result = await response.json();
  console.log(`Renamed: ${result.originalFilename} → ${result.suggestedFilename}`);
  return result.suggestedFilename;
}

// Usage
await renameDocument('./downloads/messy_receipt_scan.pdf');

Python

import requests
import os

def rename_file(file_path):
    """Rename a file using renamed.to API"""
    with open(file_path, 'rb') as f:
        files = {'file': f}
        headers = {'Authorization': f'Bearer {os.getenv("RENAMED_TO_TOKEN")}'}
        
        response = requests.post(
            'https://renamed.to/api/v1/rename',
            files=files,
            headers=headers
        )
        
        if response.ok:
            result = response.json()
            print(f"✅ {result['originalFilename']} → {result['suggestedFilename']}")
            return result['suggestedFilename']
        else:
            print(f"❌ Error: {response.json().get('error', 'Unknown error')}")

# Rename a batch of files
import glob
for pdf_file in glob.glob("./invoices/*.pdf"):
    rename_file(pdf_file)

Limits & Quotas

40 000 renames / 24 h per account (soft limit – contact us for more).
10 MB per file.
Concurrent requests: 20.
Rate limit bursts: 60 requests / minute.

Changelog

2024-06-14 – v1

Initial release – single rename endpoint.