menu_book Contents

api URL Shortener API Documentation

Introduction

The 1URL Shortener API provides developers with a simple and powerful way to create shortened URLs programmatically. Our RESTful API allows you to integrate URL shortening functionality directly into your applications, websites, or services.

Whether you're building a social media tool, a marketing platform, or simply need to manage links at scale, our API offers a reliable solution for creating, managing, and tracking shortened URLs.

Key Features

speed

Fast Response Times

Our API is optimized for speed, ensuring quick response times for all your requests.

security

Secure & Reliable

Built with security in mind, using API keys for authentication and HTTPS for all communications.

analytics

Click Tracking & Analytics

Track clicks, gather geographic data, and analyze user agents for each shortened URL.

edit

Custom URL Slugs

Create memorable, branded short links with custom slugs of your choice.

Getting Started

1. Create an Account

To use the API, you'll need to register for an account. Registration is free and only takes a minute.

2. Generate an API Key

After registering and confirming your email, log in and navigate to the API section to generate your unique API key. This key will be used to authenticate all your API requests.

info

API Keys are only available for registered users

API keys can be generated when you create an account in your dashboard under the API section. Each user receives a unique API key that should be kept secure and not shared with others. If your key is compromised, you can regenerate it.

3. Make Your First API Call

With your API key in hand, you're ready to make your first API call. See the documentation below for examples in various programming languages.

API Endpoint

Create a Shortened URL

Endpoint

POST https://1url.at/api/shorten

Headers

Content-Type: application/json
X-API-Key: your_api_key

Request Body

{
"original_url": "https://example.com",
"short_name": "custom-url"
// 'short_name' is optional
 }

cURL Example

curl -X POST https://1url.at/api/shorten \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"original_url":"https://example.com","short_name":"custom-url"}'

Success Response

{
"success": true,
"slug": "custom-url",
"full_url": "https://1url.at/custom-url"
}

Error Responses

// Missing API Key

{
"detail": "API key is missing"
}

// Invalid API Key

{
"detail": "Invalid API key"
}

// Invalid URL Format

{
"detail": "Invalid URL format"
}

// Custom Name Already Taken

{
"detail": "Custom name already in use"
}

Code Examples

cURL Examples

Create a Shortened URL

curl -X POST https://1url.at/api/shorten \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{"original_url":"https://example.com","short_name":"custom-url"}'

Python

import requests

url = "https://1url.at/api/shorten"
headers = {
 "Content-Type": "application/json",
 "X-API-Key": "your_api_key"
}
data = {
 "original_url": "https://example.com",
 "short_name": "custom-url"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

JavaScript

fetch("https://1url.at/api/shorten", {
 method: "POST",
 headers: {
  "Content-Type": "application/json",
  "X-API-Key": "your_api_key"
 },
 body: JSON.stringify({
  original_url: "https://example.com",
  short_name: "custom-url"
 })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

Pros and Cons

thumb_up Advantages

  • check_circle Simple API: Straightforward endpoints and responses make integration easy
  • check_circle Performance: Fast response times and reliable service
  • check_circle Analytics: Comprehensive click tracking and statistics
  • check_circle Custom Slugs: Create branded, memorable short URLs
  • check_circle Security: API key authentication and HTTPS encryption
  • check_circle Free Tier: Available for developers to get started

thumb_down Limitations

  • error Usage Limits: Free accounts have rate limits and URL quotas
  • error Registration Required: API key requires account creation
  • error Limited Customization: Some advanced features only available on premium plans
  • error No Bulk Operations: No native support for bulk URL creation

Usage Limits

User Type Rate Limit URLs Limit
Anonymous 10 req/min 50
Registered 20 req/min 1,000

Frequently Asked Questions

Is the API free to use?

Yes, we offer a free tier with reasonable limits for developers. For higher usage needs, we offer premium plans with increased limits and additional features.

How secure are the shortened URLs?

All communications with our API use HTTPS encryption. We also implement rate limiting and API key authentication to prevent abuse. URLs are randomly generated with a secure algorithm unless you specify a custom slug.

How do I get an API key?

API keys can be generated for registered users. After creating an account and verifying your email, you can find your API key in the API section of your dashboard. Each user receives a unique key that identifies their API requests and allows access to their own shortened URLs. New API key can be regenerated.

Can I track clicks on my shortened URLs?

Yes, we provide comprehensive analytics for each shortened URL, including click counts, geographic data, browser information, and temporal patterns.

Do URLs expire?

No, URLs do not expire. Once created, they remain active until manually deleted.

Can I create custom short URLs?

Yes, you can specify a custom slug when creating a shortened URL, as long as it's not already taken and follows our naming guidelines (letters, numbers, hyphens, and underscores only).

Ready to Get Started?

Create an account today and start using our URL Shortener API in your applications.

person_add Register for Free