API Documentation

oos.lol provides a simple and powerful REST API for URL shortening. Our service is designed for speed, reliability, and ease of integration.

Base URL

https://oos.lol/api/v1

Response Format

All responses are in JSON format

Content-Type: application/json

Request Format

Send JSON data in request body

Content-Type: application/json

Authentication

Basic usage requires no authentication. Premium features require an API key.

Free Tier

100 URLs per month, no API key required

Premium Tier

Unlimited URLs, custom domains, analytics

Using API Keys

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST https://oos.lol/api/v1/shorten \
     -d '{"url": "https://example.com"}'

Rate Limiting

Plan	Rate Limit	Burst
Free	10 req/min	20 req
Premium	1000 req/min	2000 req

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Responses

When rate limit is exceeded:

{
  "error": "Rate limit exceeded",
  "code": 429,
  "success": false,
  "retry_after": 60
}

Error Handling

oos.lol uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code	Description
200	OK - Request successful
400	Bad Request - Invalid parameters
403	Forbidden - URL blocked for security
404	Not Found - Short code doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "error": "URL cannot be empty",
  "code": 400,
  "success": false
}

Security Errors

When a URL is blocked for security reasons:

{
  "error": "URL bloquée pour des raisons de sécurité: Domain is on blocklist",
  "code": 403,
  "success": false
}

Shorten URL

POST /api/v1/shorten

Creates a shortened URL from a long URL.

Request Body

{
  "url": "https://example.com/very/long/url/that/needs/shortening"
}

Response

{
  "success": true,
  "short_url": "https://oos.lol/abc123",
  "code": "abc123",
  "original_url": "https://example.com/very/long/url/that/needs/shortening",
  "time_ms": 15
}

Example

curl -X POST https://oos.lol/api/v1/shorten \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com"}'

Expand URL

GET /api/v1/expand/{code}

Gets the original URL from a short code.

Response

{
  "success": true,
  "code": "abc123",
  "original_url": "https://example.com",
  "time_ms": 5
}

Example

curl https://oos.lol/api/v1/expand/abc123

Get Statistics

GET /api/v1/stats

Gets global service statistics.

Response

{
  "success": true,
  "stats": {
    "total_urls": 1245678,
    "total_clicks": 8941234,
    "urls_today": 15432,
    "clicks_today": 89123,
    "uptime_seconds": 2635200,
    "uptime_human": "720h0m0s",
    "uptime_percentage": 99.9,
    "avg_response_time_ms": 45,
    "success_rate": 99.8,
    "cache_hit_rate": 0.85
  }
}

Health Check

GET /api/v1/health

Check if the service is running and healthy.

Response

{
  "status": "healthy",
  "timestamp": 1640995200,
  "uptime_seconds": 3600,
  "version": "1.0.0"
}

Example

curl https://oos.lol/api/v1/health

Status Codes

Code	Status	Description
200	healthy	Service is running normally
503	unhealthy	Service is experiencing issues

Code Examples

JavaScript

async function shortenUrl(url) {
  const response = await fetch('https://oos.lol/api/v1/shorten', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url })
  });
  
  const data = await response.json();
  return data.short_url;
}

Python

import requests

def shorten_url(url):
    response = requests.post('https://oos.lol/api/v1/shorten', 
                           json={'url': url})
    return response.json()['short_url']

# Usage
short_url = shorten_url('https://example.com')
print(short_url)

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

type ShortenRequest struct {
    URL string `json:"url"`
}

type ShortenResponse struct {
    ShortURL string `json:"short_url"`
}

func shortenURL(url string) (string, error) {
    reqBody, _ := json.Marshal(ShortenRequest{URL: url})
    
    resp, err := http.Post("https://oos.lol/api/v1/shorten",
                          "application/json", 
                          bytes.NewBuffer(reqBody))
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()
    
    var result ShortenResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return result.ShortURL, nil
}

PHP

<?php
function shortenUrl($url) {
    $data = json_encode(['url' => $url]);
    
    $options = [
        'http' => [
            'header'  => "Content-type: application/json\r\n",
            'method'  => 'POST',
            'content' => $data
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents('https://oos.lol/api/v1/shorten', false, $context);
    
    $response = json_decode($result, true);
    return $response['short_url'];
}

// Usage
$shortUrl = shortenUrl('https://example.com');
echo $shortUrl;
?>

cURL Examples

# Basic URL shortening
curl -X POST https://oos.lol/api/v1/shorten \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com"}'

# Get statistics
curl https://oos.lol/api/v1/stats

# Health check
curl https://oos.lol/api/v1/health

# Expand a short code
curl https://oos.lol/api/v1/expand/abc123

Official SDKs

We provide official SDKs for popular programming languages to make integration easier.

JavaScript/Node.js

NPM package for browser and Node.js

npm install oos-lol-sdk

Python

PyPI package for Python applications

pip install oos-lol

Go

Go module for Go applications

go get github.com/oos-lol/go-sdk

Webhooks

Webhooks allow you to receive real-time notifications when certain events occur.

Supported Events

Event	Description
url.created	A new short URL was created
url.clicked	A short URL was accessed
payment.completed	A cryptocurrency payment was confirmed

Webhook Payload Example

{
  "event": "url.created",
  "timestamp": 1640995200,
  "data": {
    "code": "abc123",
    "short_url": "https://oos.lol/abc123",
    "original_url": "https://example.com",
    "created_at": "2025-08-28T10:00:00Z"
  }
}

Crypto Payments

oos.lol supports cryptocurrency payments for premium plans. Supported currencies include Bitcoin (BTC), Ethereum (ETH), Litecoin (LTC), and Dogecoin (DOGE).

Create Payment

POST /api/v1/payment/create

{
  "currency": "BTC",
  "plan": "lifetime",
  "user_email": "user@example.com"
}

Response

{
  "success": true,
  "payment": {
    "id": "pay_abc123",
    "amount": "0.0003",
    "currency": "BTC",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "expires_at": "2025-08-28T23:00:00Z"
  }
}