Rename Endpoints

Endpoint – Rename a file

POST /api/v1/rename

Request

Upload a PDF file or scanned image (JPG, PNG, TIFF) 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. Scanned images use OCR to extract text content.

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 and scanned images 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