> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoo.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with the Spoo.me API in minutes

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.

<Info>
  This guide uses the **v1 API without authentication** (anonymous mode). For higher rate limits and advanced features, check out [API Keys](/api-keys).
</Info>

## Step 1: Make Your First API Call

No registration or API keys required! You can start using the v1 API immediately with anonymous access.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://spoo.me/api/v1/shorten \
    -H "Content-Type: application/json" \
    -d '{
      "long_url": "https://example.com"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

**Expected Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://spoo.me/api/v1/shorten \
    -H "Content-Type: application/json" \
    -d '{
      "long_url": "https://github.com/spoo-me",
      "alias": "github"
    }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Password Protection

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://spoo.me/api/v1/shorten \
    -H "Content-Type: application/json" \
    -d '{
      "long_url": "https://example.com",
      "password": "secure123"
    }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

## Step 3: Get URL Statistics

Retrieve analytics for your shortened URL (public URLs only):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://spoo.me/api/v1/stats?scope=anon&short_code=abc123"
  ```

  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>

<Note>
  **Anonymous stats** can only view statistics for public (non-private) URLs. For full analytics and private URL stats, use [API key authentication](/api-keys).
</Note>

## Step 4: Additional Options

The v1 API supports several additional options:

<CodeGroup>
  ```bash cURL - Max Clicks theme={null}
  curl -X POST https://spoo.me/api/v1/shorten \
    -H "Content-Type: application/json" \
    -d '{
      "long_url": "https://example.com",
      "max_clicks": 100
    }'
  ```

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

  ```bash cURL - Block Bots theme={null}
  curl -X POST https://spoo.me/api/v1/shorten \
    -H "Content-Type: application/json" \
    -d '{
      "long_url": "https://example.com",
      "block_bots": true
    }'
  ```
</CodeGroup>

<Tip>
  **Emoji URLs** are available in the legacy v0 API. See our [legacy documentation](/api-reference) for emoji URL creation.
</Tip>

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Marketing Campaigns" icon="goal">
    ```python theme={null}
    # Track campaign performance
    campaign_url = shorten_url(
        "https://mysite.com/campaign",
        alias="summer2024",
        max_clicks=1000
    )
    ```
  </Card>

  <Card title="Social Media" icon="share">
    ```python theme={null}
    # Create shareable social links
    social_url = shorten_url(
        "https://mysite.com/article",
        alias="latest-post"
    )
    ```
  </Card>

  <Card title="Email Marketing" icon="mail">
    ```python theme={null}
    # Track email click-through rates
    email_url = shorten_url(
        "https://mysite.com/newsletter",
        alias="newsletter-jan"
    )
    ```
  </Card>

  <Card title="QR Code Generation" icon="qr-code">
    ```python theme={null}
    # Create QR-friendly URLs
    qr_url = shorten_url(
        "https://mysite.com/menu",
        alias="menu"
    )
    ```
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Explore API Endpoints">
    Check out all available endpoints in our [API Reference](/api-reference/url-shortening/create-shortened-url)
  </Step>

  <Step title="Install Python Library">
    Use our [Python library](/tools/python-library) for easier integration
  </Step>

  <Step title="Add SpooBot to Discord">
    Try our [Discord bot](/tools/spoobot) for team collaboration
  </Step>

  <Step title="Monitor Rate Limits">
    Understand [rate limiting](/rate-limits) to optimize your usage
  </Step>
</Steps>

## Error Handling

Always handle potential errors in your applications:

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```javascript JavaScript theme={null}
  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}`);
  }
  ```
</CodeGroup>

## Testing Your Integration

Use these test URLs to verify your integration:

<Note>
  **Test URLs:**

  * `https://httpbin.org/json` - Returns JSON response
  * `https://httpbin.org/delay/2` - Simulates slow loading
  * `https://example.com` - Simple test page
</Note>

## Need Help?

<CardGroup cols={2}>
  <Card title="Join Discord" icon="discord" href="https://spoo.me/discord">
    Get real-time help from our community
  </Card>

  <Card title="Email Support" icon="mail" href="mailto:support@spoo.me">
    Contact us for technical support
  </Card>
</CardGroup>

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