Renamed.to REST API v1

Turn messy uploads into consistent, human-readable filenames with a single API call. Renamed.to reads the file itself (OCR for scans, NLP for text) to extract the right fields, then applies your naming template to return the exact filename you expect—every time. Clean JSON in/out with Bearer token authentication, so you can integrate in minutes.

Rename files from their content, not their existing names.

Reads the file (OCR for scans) to extract real metadata
Templates you control: auto, ready-made, or natural-language custom
Consistent, safe output with characters that work everywhere
JSON-first REST API with Bearer token authentication
Optional folder path for smart routing and organization
Privacy-first defaults that avoid long-term content storage

Get started: 50 free credits for new accounts.

Base URL

https://www.renamed.to/api/v1

Quick Start: Generate an API token in Settings → API Tokens, then make your first request using the examples below.

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.

Create an Account

Generate an API Token

Navigate to Settings → API Tokens and create a new API token. Tokens are shown only once when created—make sure to save it securely.

Tip: Use descriptive names for your tokens (e.g., "Production Server", "Development") to help manage multiple tokens.

Make Your First Request

Use your API token to authenticate requests. The service will automatically extract metadata from your PDF files. Here's a minimal example:

Note: These are simplified examples for getting started. For production code with comprehensive error handling, retry logic, and validation, see the Error Handling section and the Rename endpoint documentation.

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

Handle the Response

A successful response includes the generated filename and folder path with extracted metadata:

Common Issues

Python 415 Error: If using Python, ensure file uploads include filename and content-type (see Python File Upload Requirements)
401 Errors: Verify your API token is correct and has necessary permissions
File Size: Maximum file size is 25 MB for PDF files and scanned images (JPG, PNG, TIFF)

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

Need help? Check our documentation or contact support if you run into any issues.

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:

https://www.renamed.to/api/v1

Versioning Policy

Backward Compatibility

We maintain backward compatibility within each major version. New features and non-breaking changes are added to the current version without requiring code changes in your integration.

Breaking Changes

Breaking changes (removed endpoints, changed response formats, removed fields) will result in a new major version (e.g., v2). When a new major version is released:

The previous version remains available for at least 12 months
We provide migration guides and deprecation notices
Breaking changes are announced at least 90 days in advance

Deprecation Timeline

When a version is deprecated, we follow this timeline:

90 days notice: Deprecation announcement with migration guide
12 months support: Deprecated version remains functional
Sunset: Deprecated version is retired after support period

Requesting a Specific Version

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

https://www.renamed.to/api/v1/rename✓ Current version

https://www.renamed.to/api/v2/renameFuture version (not yet available)

Version Headers

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

Header	Description	Example
`API-Version`	The API version used for the request	v1

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

Note: API v1 is stable and actively maintained. We have no plans to deprecate v1 in the near future. When v2 is released, both versions will be supported simultaneously.

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

API Endpoints

Rename Endpoints

Rename PDF files and scanned images using AI-extracted metadata.

PDF Split Endpoints

Split multi-page PDFs into individual documents with automatic naming.

Account & Resources

Manage user profiles, check credit balances, and team membership.

Reference & Troubleshooting

Error codes, rate limits, troubleshooting guides, and FAQ.