Quick Start

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"
  }'

import requests

response = requests.post(
    "https://spoo.me/api/v1/shorten",
    headers={"Content-Type": "application/json"},
    json={"long_url": "https://example.com"}
)

print(response.json())

fetch('https://spoo.me/api/v1/shorten', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        long_url: 'https://example.com'
    })
})
.then(response => response.json())
.then(data => console.log(data));

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"
  }'

import requests

response = requests.post(
    "https://spoo.me/api/v1/shorten",
    headers={"Content-Type": "application/json"},
    json={
        "long_url": "https://github.com/spoo-me",
        "alias": "github"
    }
)

print(response.json())

Password Protection

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

import requests

response = requests.post(
    "https://spoo.me/api/v1/shorten",
    headers={"Content-Type": "application/json"},
    json={
        "long_url": "https://example.com",
        "password": "secure123"
    }
)

print(response.json())

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"

import requests

response = requests.get(
    "https://spoo.me/api/v1/stats",
    params={
        "scope": "anon",
        "short_code": "abc123"
    }
)

stats = response.json()
print(f"Total clicks: {stats['summary']['total_clicks']}")
print(f"Unique clicks: {stats['summary']['unique_clicks']}")

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
  }'

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

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

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

Explore API Endpoints

Check out all available endpoints in our API Reference

Install Python Library

Use our Python library for easier integration

Add SpooBot to Discord

Try our Discord bot for team collaboration

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}")

async function safeShortenerUrl(long_url, options = {}) {
    try {
        const response = await fetch('https://spoo.me/api/v1/shorten', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ long_url, ...options })
        });
        
        if (response.status === 201) {
            const data = await response.json();
            return data.short_url;
        } else if (response.status === 429) {
            console.log('Rate limit exceeded. Please wait.');
            return null;
        } else {
            const errorData = await response.json();
            console.log(`Error: ${errorData.error || 'Unknown error'}`);
            return null;
        }
    } catch (error) {
        console.log(`Request failed: ${error.message}`);
        return null;
    }
}

// Usage
const shortUrl = await safeShortenerUrl('https://example.com', { alias: 'test' });
if (shortUrl) {
    console.log(`Success: ${shortUrl}`);
}

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

You’re now ready to start building with the Spoo.me API! 🚀

Getting Started

API v1 Reference

API v0 Reference (Legacy)

Tools & Libraries

Self Hosting

Step 1: Make Your First API Call

Step 2: Try Advanced Features

Custom Alias

Password Protection

Step 3: Get URL Statistics

Step 4: Additional Options

Common Use Cases

Marketing Campaigns

Social Media

Email Marketing

QR Code Generation

Next Steps

Error Handling

Testing Your Integration

Need Help?

Join Discord

Email Support

​Step 1: Make Your First API Call

​Step 2: Try Advanced Features

​Custom Alias

​Password Protection

​Step 3: Get URL Statistics

​Step 4: Additional Options

​Common Use Cases

Marketing Campaigns

Social Media

Email Marketing

QR Code Generation

​Next Steps

​Error Handling

​Testing Your Integration

​Need Help?

Join Discord

Email Support

Step 1: Make Your First API Call

Step 2: Try Advanced Features

Custom Alias

Password Protection

Step 3: Get URL Statistics

Step 4: Additional Options

Common Use Cases

Next Steps

Error Handling

Testing Your Integration

Need Help?