API Documentation

Introduction

The RandomNumber.net API provides programmatic access to our random number generation services. With this API, you can integrate high-quality random number generation into your own applications, websites, or services.

Our API is RESTful and uses JSON for request and response bodies. All API endpoints are accessed via HTTPS to ensure data security during transmission.

Base URL: https://randomnumber.net/api/

Authentication

The RandomNumber.net API uses CSRF tokens for authentication. To make API requests, you need to:

1. Include a valid CSRF token in the X-CSRF-Token header of your request
2. Send requests from a browser that has a valid session with RandomNumber.net

CSRF tokens are automatically generated when you visit the RandomNumber.net website and are available in the global JavaScript variable CSRF_TOKEN.

fetch('https://randomnumber.net/api/generate.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': CSRF_TOKEN
    },
    body: JSON.stringify({
        min: 1,
        max: 100,
        count: 5
    })
})

Rate Limits

To ensure fair usage and system stability, the API has the following rate limits:

• 100 requests per hour per IP address
• Maximum of 10,000 random numbers per request

If you exceed these limits, the API will return a 429 Too Many Requests response. If you need higher limits for your application, please contact us.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request:

• 200 OK - The request was successful
• 400 Bad Request - The request was invalid or missing required parameters
• 403 Forbidden - Authentication failed or you don't have permission to access the resource
• 429 Too Many Requests - You've exceeded the rate limit
• 500 Internal Server Error - An error occurred on the server

Error responses include a JSON object with an error field that provides more information about the error:

{
    "error": "Count cannot exceed the range of possible values when duplicates are not allowed"
}

Endpoints

POST /api/generate.php
Content-Type: application/json
X-CSRF-Token: your_csrf_token

{
    "min": 1,
    "max": 100,
    "count": 5,
    "allowDuplicates": false
}

{
    "numbers": [23, 47, 12, 89, 56],
    "timestamp": 1740693045,
    "hash": "8f7d6a5e4c3b2a1098765432109876543210abcdef1234567890abcdef123456"
}

POST /api/generate-password.php
Content-Type: application/json
X-CSRF-Token: your_csrf_token

{
    "length": 12,
    "includeUppercase": true,
    "includeLowercase": true,
    "includeNumbers": true,
    "includeSymbols": false
}

{
    "password": "A7bX2pQ9cR5d"
}

POST /api/verify.php
Content-Type: application/json
X-CSRF-Token: your_csrf_token

{
    "numbers": [23, 47, 12, 89, 56],
    "timestamp": 1740693045,
    "hash": "8f7d6a5e4c3b2a1098765432109876543210abcdef1234567890abcdef123456"
}

{
    "verified": true,
    "calculatedHash": "8f7d6a5e4c3b2a1098765432109876543210abcdef1234567890abcdef123456"
}

Code Examples

// Generate random numbers
async function generateRandomNumbers(min, max, count, allowDuplicates = true) {
    try {
        const response = await fetch('https://randomnumber.net/api/generate.php', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-CSRF-Token': CSRF_TOKEN
            },
            body: JSON.stringify({
                min: min,
                max: max,
                count: count,
                allowDuplicates: allowDuplicates
            })
        });
        
        if (!response.ok) {
            throw new Error('Network response was not ok');
        }
        
        return await response.json();
    } catch (error) {
        console.error('Error generating random numbers:', error);
        throw error;
    }
}

// Example usage
generateRandomNumbers(1, 100, 5, false)
    .then(result => {
        console.log('Random numbers:', result.numbers);
        console.log('Timestamp:', result.timestamp);
        console.log('Verification hash:', result.hash);
    })
    .catch(error => {
        console.error('Error:', error);
    });

<?php
// Generate random numbers
function generateRandomNumbers($min, $max, $count, $allowDuplicates = true) {
    $url = 'https://randomnumber.net/api/generate.php';
    $data = [
        'min' => $min,
        'max' => $max,
        'count' => $count,
        'allowDuplicates' => $allowDuplicates
    ];
    
    // Get CSRF token from session
    session_start();
    $csrf_token = $_SESSION['csrf_token'];
    
    $options = [
        'http' => [
            'header'  => "Content-type: application/json\r\nX-CSRF-Token: $csrf_token\r\n",
            'method'  => 'POST',
            'content' => json_encode($data)
        ]
    ];
    
    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        throw new Exception('Error generating random numbers');
    }
    
    return json_decode($result, true);
}

// Example usage
try {
    $result = generateRandomNumbers(1, 100, 5, false);
    echo "Random numbers: " . implode(', ', $result['numbers']) . "\n";
    echo "Timestamp: " . $result['timestamp'] . "\n";
    echo "Verification hash: " . $result['hash'] . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

import requests
import json

# Generate random numbers
def generate_random_numbers(min_val, max_val, count, allow_duplicates=True):
    url = 'https://randomnumber.net/api/generate.php'
    data = {
        'min': min_val,
        'max': max_val,
        'count': count,
        'allowDuplicates': allow_duplicates
    }
    
    # You need to get the CSRF token from a browser session
    csrf_token = 'your_csrf_token'
    
    headers = {
        'Content-Type': 'application/json',
        'X-CSRF-Token': csrf_token
    }
    
    response = requests.post(url, headers=headers, data=json.dumps(data))
    
    if response.status_code != 200:
        raise Exception(f'Error generating random numbers: {response.text}')
    
    return response.json()

# Example usage
try:
    result = generate_random_numbers(1, 100, 5, False)
    print(f"Random numbers: {result['numbers']}")
    print(f"Timestamp: {result['timestamp']}")
    print(f"Verification hash: {result['hash']}")
except Exception as e:
    print(f"Error: {e}")

Support

If you have any questions or need help with the API, please contact us.

For bug reports or feature requests, please email support@randomnumber.net.