Complete reference guide for integrating Io URL Shortener into your applications. Enterprise-grade REST API with comprehensive authentication and rate limiting.
Welcome to the Io URL Shortener API! This guide will help you integrate our enterprise-grade URL shortening service into your applications.
To get started, you'll need to register for an account and obtain your API key. Verified users get unlimited API requests and access to custom endpoints.
Standard RESTful API with JSON responses. Supports all CRUD operations for URL management.
Secure authentication using JSON Web Tokens with access and refresh token mechanism.
Enterprise-grade rate limiting with different tiers based on user verification status.
Comprehensive analytics with geographic data, device information, and click tracking.
All API requests should be made to the following base URL:
https://knps.dev/api/v1/
https://knps.dev/api/v1/{endpoint}
https://knps.dev/{short_code}
https://knps.dev/qr/{short_code}
All API calls must be made over HTTPS. HTTP requests will be rejected for security reasons.
Io uses JWT (JSON Web Tokens) for authentication. You'll need to obtain an access token by registering and logging in through our authentication endpoints.
Create a new user account with email and password
Authenticate with credentials to receive tokens
Include access token in Authorization header for API calls
Use refresh token to get new access token when expired
Include your access token in the Authorization header using the Bearer scheme:
Authorization: Bearer YOUR_ACCESS_TOKENcurl -X GET "https://knps.dev/api/v1/urls" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
-H "Content-Type: application/json"Io implements enterprise-grade rate limiting to ensure fair usage and protect against abuse. Rate limits vary based on user verification status and endpoint type.
API responses include rate limit information in the headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200When rate limit is exceeded, the API returns a 429 status code:
{
"error": true,
"message": "Rate limit exceeded",
"error_code": "RATE_LIMIT_EXCEEDED",
"retry_after": 3600
}The API uses conventional HTTP response codes to indicate the success or failure of requests. Error responses include detailed information to help you debug issues.
All error responses follow a consistent JSON format:
{
"error": true,
"message": "Validation failed",
"error_code": "VALIDATION_ERROR",
"errors": {
"original_url": ["This field is required"]
}
}Authentication endpoints handle user registration, login, and token management.
Create a new user account with email and password.
{
"username": "johndoe",
"email": "john@example.com",
"password": "SecurePassword123!"
}{
"success": true,
"message": "User registered successfully",
"data": {
"user": {
"id": 1,
"username": "johndoe",
"email": "john@example.com",
"is_verified": false
},
"access_token": "eyJ0eXAiOiJKV1Q...",
"token_type": "Bearer"
}
}Authenticate user and receive access tokens.
{
"email": "john@example.com",
"password": "SecurePassword123!"
}{
"success": true,
"message": "Login successful",
"data": {
"user": {
"id": 1,
"username": "johndoe",
"email": "john@example.com",
"is_verified": false
},
"access_token": "eyJ0eXAiOiJKV1Q...",
"token_type": "Bearer"
}
}Get a new access token using refresh token.
{
"success": true,
"data": {
"access_token": "eyJ0eXAiOiJKV1Q...",
"token_type": "Bearer"
}
}URL management endpoints for creating, retrieving, updating, and deleting short URLs.
Create a new short URL with optional customization.
{
"original_url": "https://example.com/very-long-url",
"custom_alias": "my-link",
"title": "My Example Link",
"description": "A demonstration link",
"expires_in_days": 30
}{
"success": true,
"message": "URL created successfully",
"data": {
"id": 123,
"original_url": "https://example.com/very-long-url",
"short_url": "https://knps.dev/my-link",
"short_code": "my-link",
"title": "My Example Link",
"qr_code_url": "https://knps.dev/qr/my-link",
"expires_at": "2025-02-14T10:30:00Z"
}
}Get paginated list of user's URLs with optional filtering.
?page=1&per_page=20&search=example&status=active{
"success": true,
"data": {
"urls": [
{
"id": 123,
"original_url": "https://example.com",
"short_url": "https://knps.dev/abc123",
"short_code": "abc123",
"clicks": 42,
"created_at": "2025-01-14T10:30:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 100,
"pages": 5
}
}
}Analytics endpoints provide comprehensive click tracking and reporting data.
Retrieve detailed analytics for a specific URL.
?days=30{
"success": true,
"data": {
"total_clicks": 1250,
"unique_clicks": 890,
"daily_clicks": [
{"date": "2025-01-14", "clicks": 42},
{"date": "2025-01-13", "clicks": 38}
],
"top_countries": [
{"country": "United States", "clicks": 450},
{"country": "United Kingdom", "clicks": 200}
],
"device_breakdown": {
"desktop": 60,
"mobile": 35,
"tablet": 5
}
}
}Public endpoints that don't require authentication for basic functionality.
Create a temporary URL that expires in 15 minutes (no auth required).
{
"original_url": "https://example.com"
}{
"success": true,
"message": "Temporary URL created successfully",
"data": {
"original_url": "https://example.com",
"short_url": "https://knps.dev/temp123",
"short_code": "temp123",
"expires_at": "2025-01-14T11:45:00Z",
"qr_code_url": "https://knps.dev/api/v1/public/qr/temp123"
}
}Practical examples for common use cases and integration patterns.
Simple script to test API key authentication for URL creation.
"""
Test script for API key authentication in the Io URL Shortener.
"""
import requests
import sys
def test_api_key_auth(api_key):
"""Test API key authentication for URL creation."""
base_url = "http://knps.dev/api/v1"
session = requests.Session()
# Set API key in headers
session.headers.update({
'Content-Type': 'application/json',
'X-API-Key': api_key
})
# Try creating a URL with API key
print(f"Testing URL creation with API key: {api_key[:10]}...")
response = session.post(
f"{base_url}/urls",
json={
"original_url": "https://github.com/KanopusDev/Kale",
"title": "API Key Test"
}
)
print(f"Status code: {response.status_code}")
if response.status_code in (200, 201):
data = response.json()['data']
print("URL created successfully with API key!")
print(f"Original URL: {data['original_url']}")
print(f"Short URL: {data['short_url']}")
print(f"Short code: {data['short_code']}")
return True
else:
print("Failed to create URL with API key.")
print(f"Response: {response.text}")
return False
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: python test_api_key.py <api_key>")
sys.exit(1)
api_key = sys.argv[1]
test_api_key_auth(api_key)Usage: python test_api_key.py YOUR_API_KEY
curl -X POST "https://knps.dev/api/v1/urls" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"original_url": "https://example.com",
"title": "API Key Test"
}'curl -X GET "https://knps.dev/api/v1/analytics/123?days=30" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Track the latest updates and improvements to the Io API.