Skip to main content
Get up and running with the Spoo.me v1 API in just a few minutes. This guide will show you how to make your first API call and shorten your first URL.
This guide uses the v1 API without authentication (anonymous mode). For higher rate limits and advanced features, check out API Keys.

​
Step 1: Make Your First API Call

No registration or API keys required! You can start using the v1 API immediately with anonymous access. 
curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com"
  }'
Expected Response: 
{
  "alias": "abc123",
  "short_url": "https://spoo.me/abc123",
  "long_url": "https://example.com",
  "owner_id": null,
  "created_at": 1704067200,
  "status": "ACTIVE",
  "private_stats": false
}

​
Step 2: Try Advanced Features

Try features like password protection, custom aliases, and emoji URLs.

​
Custom Alias

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://github.com/spoo-me",
    "alias": "github"
  }'

​
Password Protection

curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com",
    "password": "secure123"
  }'

​
Step 3: Get URL Statistics

Retrieve analytics for your shortened URL (public URLs only): 
curl -X GET "https://spoo.me/api/v1/stats?scope=anon&short_code=abc123"
Anonymous stats can only view statistics for public (non-private) URLs. For full analytics and private URL stats, use API key authentication.

​
Step 4: Additional Options

The v1 API supports several additional options: 
curl -X POST https://spoo.me/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com",
    "max_clicks": 100
  }'
Emoji URLs are available in the legacy v0 API. See our legacy documentation for emoji URL creation.

​
Common Use Cases

Marketing Campaigns

# Track campaign performance
campaign_url = shorten_url(
    "https://mysite.com/campaign",
    alias="summer2024",
    max_clicks=1000
)

Social Media

# Create shareable social links
social_url = shorten_url(
    "https://mysite.com/article",
    alias="latest-post"
)

Email Marketing

# Track email click-through rates
email_url = shorten_url(
    "https://mysite.com/newsletter",
    alias="newsletter-jan"
)

QR Code Generation

# Create QR-friendly URLs
qr_url = shorten_url(
    "https://mysite.com/menu",
    alias="menu"
)

​
Next Steps

1

Explore API Endpoints

Check out all available endpoints in our API Reference
2

Install Python Library

Use our Python library for easier integration
3

Add SpooBot to Discord

Try our Discord bot for team collaboration
4

Monitor Rate Limits

Understand rate limiting to optimize your usage

​
Error Handling

Always handle potential errors in your applications: 
import requests

def safe_shorten_url(long_url, **kwargs):
    try:
        response = requests.post(
            "https://spoo.me/api/v1/shorten",
            headers={"Content-Type": "application/json"},
            json={"long_url": long_url, **kwargs}
        )
        
        if response.status_code == 201:
            return response.json()["short_url"]
        elif response.status_code == 429:
            print("Rate limit exceeded. Please wait.")
            return None
        else:
            error_data = response.json()
            print(f"Error: {error_data.get('error', 'Unknown error')}")
            return None
            
    except requests.RequestException as e:
        print(f"Request failed: {e}")
        return None

# Usage
short_url = safe_shorten_url("https://example.com", alias="test")
if short_url:
    print(f"Success: {short_url}")

​
Testing Your Integration

Use these test URLs to verify your integration:
Test URLs:
  • https://httpbin.org/json - Returns JSON response
  • https://httpbin.org/delay/2 - Simulates slow loading
  • https://example.com - Simple test page

​
Need Help?

Join Discord

Get real-time help from our community

Email Support

Contact us for technical support
You’re now ready to start building with the Spoo.me API! 🚀