Developer Docs

    API Documentation

    Integrate UPVOTEMAX into your application with our simple REST API

    Base URL: https://yourdomain.com/api/public/v1

    Table of Contents

    Quick navigation

    Important: IP Whitelisting Required

    For production use, your server IP must be whitelisted with our provider. Please contact us on Telegram @upvotemax to get your IP approved, otherwise orders will fail.

    Authentication

    All requests require an API key

    Include your API key in the x-api-key header with every request:

    Header Example

    bash
    x-api-key: YOUR_API_KEY

    Get your API key from Settings

    Generate and manage your keys securely

    Available Services

    Service keys and IDs for creating orders

    💡 Tip: Use either serviceKey or serviceId

    You can use the friendly service key (e.g., "post_upvote") or the numeric serviceId (e.g., "2") when creating orders.

    post_upvote|ID: 2

    Post Upvote

    $1.00/100

    Min: 5 • Max: 1000

    post_downvote|ID: 1

    Post Downvote

    $1.00/100

    Min: 5 • Max: 1000

    comment_upvote|ID: 4

    Comment Upvote

    $2.00/100

    Min: 5 • Max: 1000

    comment_downvote|ID: 8

    Comment Downvote

    $2.00/100

    Min: 5 • Max: 1000

    custom_comments|ID: 5

    Custom Comments

    $0.10/comment

    Min: 1 • Max: 100

    Rate Limits & Restrictions

    Important limits to keep in mind

    Concurrent Orders

    Maximum 3 pending/running orders per link + service combination. Wait for existing orders to complete before placing new ones.

    Batch Status Check

    Maximum 100 orders per status check request.

    Pagination Limits

    Maximum 100 results per page when listing orders.

    Speed Parameter

    Delivery speed range: 10 - 5000 per hour. Only for upvote/downvote services.

    Order Status Values

    Possible status values returned by the API

    🔄 Real-Time Status Refresh

    When you fetch order details via GET endpoints, the status is automatically refreshed from our provider in real-time. This ensures you always get the most up-to-date status.

    pending

    Order has been received and is queued for processing

    running

    Order is currently being processed (upvotes/comments being delivered)

    completed

    Order has been successfully completed

    failed

    Order failed or was cancelled (balance may be refunded)

    Quick Start

    Get started with these common examples

    1

    Create Order (Upvotes/Downvotes)

    201 Created

    Parameters:

    • service: Service key (post_upvote, post_downvote, comment_upvote, comment_downvote)
    • link: Reddit post or comment URL
    • quantity: Number of upvotes/downvotes (5-1000)
    • speed: (optional) Delivery speed per hour (10-5000, default: auto)

    Request

    bash
    curl -X POST https://yourdomain.com/api/public/v1/orders \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "service": "post_upvote",
        "link": "https://www.reddit.com/r/example/comments/abc123/...",
        "quantity": 50,
        "speed": 100
      }'

    Response

    json
    {
      "status": "success",
      "orderId": 4292567,
      "cost": 0.5,
      "balanceAfter": 24.50
    }
    2

    Create Order (Custom Comments)

    201 Created

    Parameters:

    • comments: Separate each comment with \n (newline)
    • delay1: Delay before starting (in minutes)
    • delay2: Delay between each comment (in minutes)

    Request

    bash
    curl -X POST https://yourdomain.com/api/public/v1/orders \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "service": "custom_comments",
        "link": "https://www.reddit.com/r/example/comments/abc123/...",
        "comments": "Great post!\nThanks for sharing\nVery helpful",
        "delay1": 2,
        "delay2": 5
      }'

    Response

    json
    {
      "status": "success",
      "orderId": 4293000,
      "cost": 0.3,
      "balanceAfter": 24.20
    }
    3

    Check Order Status

    200 OK

    Request

    bash
    curl -X POST https://yourdomain.com/api/public/v1/status \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "orders": ["4292567", "4293000"]
      }'

    Response

    json
    {
      "results": [
        { "orderId": 4292567, "status": "pending" },
        { "orderId": 4293000, "status": "completed" }
      ]
    }

    All Endpoints

    Complete API reference with HTTP status codes

    POST
    /api/public/v1/orders

    Create a new order

    201 Created

    Body Parameters:

    • service (string, required) — Service key from available services
    • serviceId (string, alternative) — Numeric service ID (can use instead of service)
    • link (string, required) — Reddit post/comment URL
    • quantity (number, required*) — Number of upvotes/downvotes (*not for custom_comments)
    • speed (number, optional) — Delivery speed per hour (10-5000). Controls how fast upvotes/downvotes are delivered. Only for upvote/downvote services, not custom_comments.
    • comments (string, optional) — Required for custom_comments, separated by \n
    • delay1 (number, optional) — Initial delay in minutes (for custom_comments)
    • delay2 (number, optional) — Delay between comments in minutes
    GET
    /api/public/v1/orders?id=ORDER_ID

    Get details of a specific order (status refreshed in real-time)

    200 OK

    Example Request

    bash
    curl -X GET "https://yourdomain.com/api/public/v1/orders?id=4292567" \
      -H "x-api-key: YOUR_API_KEY"

    Example Response

    json
    {
      "order": {
        "id": 4292567,
        "created_at": "2025-11-02T19:06:23Z",
        "service": "Post Upvote",
        "reddit_link": "https://www.reddit.com/...",
        "quantity": 50,
        "cost": 0.5,
        "status": "completed"
      }
    }
    GET
    /api/public/v1/orders?page=1&limit=20

    List all your orders with pagination (statuses refreshed in real-time)

    200 OK

    Query Parameters:

    • page (number, optional) — Page number (default: 1)
    • limit (number, optional) — Results per page (default: 20, max: 100)
    • status (string, optional) — Filter by status (pending, running, completed, failed)
    • service (string, optional) — Filter by service name
    • link (string, optional) — Search by Reddit link (partial match)
    POST
    /api/public/v1/status

    Check status of multiple orders (max 100)

    200 OK

    Body Parameters:

    • orders (array, required) — Array of order IDs (strings or numbers)
    GET
    /api/public/v1/services

    Get list of all available services with pricing

    200 OK

    Example Response

    json
    {
      "services": [
        {
          "serviceId": "2",
          "serviceKey": "post_upvote",
          "name": "Post Upvote",
          "min": 5,
          "max": 1000,
          "ratePerHundred": 1.0,
          "category": "Reddit"
        }
      ]
    }
    GET
    /api/public/v1/balance

    Get your current account balance

    200 OK

    Example Response

    json
    {
      "balance": 25.50
    }

    Reddit Posting Service

    Create and manage Reddit posts programmatically

    $15/post

    📝 How it works:

    1. Submit your post via API with subreddit, title, and body (markdown supported)
    2. Your balance is charged $15 immediately
    3. Our team reviews your post within 24 hours
    4. Once approved, we publish it to Reddit and provide the URL
    5. If rejected, you receive a full refund

    Post Status Values:

    pending_approval

    Awaiting review

    approved

    Ready to publish

    published

    Live on Reddit

    rejected

    Refunded

    POST
    /api/public/v1/posts

    Create a new Reddit post ($15)

    201 Created

    Body Parameters:

    • subreddit (string, required) — Subreddit name without r/ prefix (2-21 chars)
    • title (string, required) — Post title (3-300 chars)
    • body (string, required) — Post body in markdown format (10-40,000 chars)

    Example Request

    bash
    curl -X POST https://yourdomain.com/api/public/v1/posts \
      -H "Content-Type: application/json" \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{
        "subreddit": "technology",
        "title": "The Future of AI in 2025",
        "body": "# Introduction\n\nArtificial Intelligence has come a long way...\n\n## Key Points\n\n- Point 1\n- Point 2\n\n**Conclusion**: AI is revolutionizing everything."
      }'

    Example Response

    json
    {
      "status": "success",
      "post": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2025-12-13T10:00:00Z",
        "subreddit": "technology",
        "title": "The Future of AI in 2025",
        "body": "# Introduction\n\nArtificial Intelligence...",
        "status": "pending_approval",
        "cost": 15.0,
        "rejection_reason": null,
        "reddit_url": null,
        "published_at": null
      },
      "cost": 15.0,
      "balanceAfter": 35.0,
      "message": "Post submitted successfully. It will be reviewed by our team within 24 hours."
    }
    GET
    /api/public/v1/posts?id=POST_ID

    Get status and details of a specific post

    200 OK

    Example Response (Published)

    json
    {
      "post": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2025-12-13T10:00:00Z",
        "subreddit": "technology",
        "title": "The Future of AI in 2025",
        "body": "# Introduction\n\n...",
        "status": "published",
        "cost": 15.0,
        "rejection_reason": null,
        "reddit_url": "https://www.reddit.com/r/technology/comments/abc123/the_future_of_ai_in_2025",
        "published_at": "2025-12-13T14:30:00Z"
      }
    }
    GET
    /api/public/v1/posts?page=1&limit=20

    List all your posts with pagination

    200 OK

    Query Parameters:

    • page (number, optional) — Page number (default: 1)
    • limit (number, optional) — Results per page (default: 20, max: 100)
    • status (string, optional) — Filter by status

    SDK Examples

    Code examples in popular languages

    PythonUsing requests library

    Python - Create Order

    python
    import requests
    
    API_KEY = "YOUR_API_KEY"
    BASE_URL = "https://yourdomain.com/api/public/v1"
    
    headers = {
        "Content-Type": "application/json",
        "x-api-key": API_KEY
    }
    
    # Create upvote order
    def create_upvote_order(link: str, quantity: int, speed: int = None):
        payload = {
            "service": "post_upvote",
            "link": link,
            "quantity": quantity
        }
        if speed:
            payload["speed"] = speed
        
        response = requests.post(
            f"{BASE_URL}/orders",
            json=payload,
            headers=headers
        )
        return response.json()
    
    # Check order status
    def check_status(order_ids: list):
        response = requests.post(
            f"{BASE_URL}/status",
            json={"orders": order_ids},
            headers=headers
        )
        return response.json()
    
    # Example usage
    result = create_upvote_order(
        "https://reddit.com/r/example/comments/abc123/...",
        quantity=50,
        speed=100
    )
    print(f"Order ID: {result['orderId']}")
    JavaScriptUsing fetch API (Node.js / Browser)

    JavaScript - Create Order

    javascript
    const API_KEY = 'YOUR_API_KEY';
    const BASE_URL = 'https://yourdomain.com/api/public/v1';
    
    const headers = {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY
    };
    
    // Create upvote order
    async function createUpvoteOrder(link, quantity, speed = null) {
      const payload = {
        service: 'post_upvote',
        link,
        quantity
      };
      if (speed) payload.speed = speed;
    
      const response = await fetch(`${BASE_URL}/orders`, {
        method: 'POST',
        headers,
        body: JSON.stringify(payload)
      });
      return response.json();
    }
    
    // Check order status
    async function checkStatus(orderIds) {
      const response = await fetch(`${BASE_URL}/status`, {
        method: 'POST',
        headers,
        body: JSON.stringify({ orders: orderIds })
      });
      return response.json();
    }
    
    // Get balance
    async function getBalance() {
      const response = await fetch(`${BASE_URL}/balance`, { headers });
      return response.json();
    }
    
    // Example usage
    const result = await createUpvoteOrder(
      'https://reddit.com/r/example/comments/abc123/...',
      50,
      100
    );
    console.log('Order ID:', result.orderId);
    PHPUsing cURL

    PHP - Create Order

    php
    <?php
    $API_KEY = 'YOUR_API_KEY';
    $BASE_URL = 'https://yourdomain.com/api/public/v1';
    
    function createOrder($service, $link, $quantity, $speed = null) {
        global $API_KEY, $BASE_URL;
        
        $payload = [
            'service' => $service,
            'link' => $link,
            'quantity' => $quantity
        ];
        if ($speed) $payload['speed'] = $speed;
    
        $ch = curl_init("$BASE_URL/orders");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                "x-api-key: $API_KEY"
            ],
            CURLOPT_POSTFIELDS => json_encode($payload)
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    // Example usage
    $result = createOrder(
        'post_upvote',
        'https://reddit.com/r/example/comments/abc123/...',
        50,
        100
    );
    echo "Order ID: " . $result['orderId'];
    ?>

    Error Handling

    HTTP status codes and error responses

    200OK

    Request successful

    201Created

    Order created successfully

    400Bad Request

    Invalid parameters or validation error

    401Unauthorized

    Invalid or missing API key

    402Payment Required

    Insufficient balance

    404Not Found

    Order or resource not found

    429Too Many Requests

    Rate limit exceeded (concurrent orders)

    500/502Server Error

    Internal error, please retry or contact support

    Invalid API Key (401)

    json
    {
      "error": "Invalid or missing API key"
    }

    Insufficient Balance (402)

    json
    {
      "error": "Insufficient balance"
    }

    Validation Error (400)

    json
    {
      "error": "Quantity must be between 5 and 1000"
    }

    Rate Limit (429)

    json
    {
      "error": "You already have 3 pending/running orders for this link and service. Please wait for them to complete."
    }

    For any issues, contact us on Telegram @upvotemax