API Reference

Complete API documentation for the HostingCo management system with interactive examples and testing tools.

⏱️ 15 min read
Page Last updated: 2026-05-08

Table of Contents

Overview

The HostingCo API provides a comprehensive RESTful interface for managing hosting services, billing, support tickets, and system operations. All endpoints return JSON responses and follow consistent patterns.

Base URL: http://localhost:3003/api (Development)
Production URL: https://yourdomain.com/api

Base URL

Development

URL: http://localhost:3003/api

Description: Local development server

Status: Active

Production

URL: https://yourdomain.com/api

Description: Production environment

Status: Configured

Authentication

Most API endpoints require authentication using JWT tokens. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Authentication Flow

  1. Login to obtain JWT token
  2. Include token in subsequent requests
  3. Token expires after 24 hours (configurable)
Security Note: Always use HTTPS in production to protect your JWT tokens.

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful",
  "timestamp": "2026-05-08T03:14:24.942Z"
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": {
      // Additional error details
    }
  },
  "timestamp": "2026-05-08T03:14:24.942Z"
}

Health Check

GET
/health
Check API server health and status.
Request
curl http://localhost:3003/api/health
Response
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2026-05-08T03:52:58.868Z",
    "uptime": 571.586811102,
    "environment": "development",
    "version": "1.0.0"
  }
}

Authentication Endpoints

POST
/auth/login
Authenticate user and return JWT token.
Request Body
{
  "email": "user@example.com",
  "password": "password123"
}
Response
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "user"
    }
  }
}
POST
/auth/register
Register a new user account.
Request Body
{
  "email": "newuser@example.com",
  "password": "password123",
  "name": "New User",
  "company": "Example Corp"
}
Response
{
  "success": true,
  "data": {
    "user": {
      "id": "user_456",
      "email": "newuser@example.com",
      "name": "New User",
      "role": "user"
    }
  },
  "message": "User registered successfully"
}
POST
/auth/logout
Logout user and invalidate token.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "message": "Logged out successfully"
}

Dashboard Endpoints

GET
/dashboard/stats
Get dashboard statistics and overview data.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "data": {
    "overview": {
      "totalUsers": 150,
      "activeUsers": 120,
      "totalServers": 45,
      "activeServers": 42,
      "totalRevenue": 12500.00,
      "monthlyRevenue": 2500.00
    },
    "servers": {
      "byStatus": {
        "active": 42,
        "inactive": 3
      },
      "averageUptime": 99.8
    },
    "billing": {
      "pendingInvoices": 8,
      "totalRevenue": 45678.90
    }
  }
}
POST
/dashboard/refresh
Refresh dashboard data and statistics.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "data": {
    "refreshed": true,
    "timestamp": "2026-05-08T03:14:24.942Z"
  },
  "message": "Dashboard data refreshed successfully"
}

Hosting Endpoints

GET
/hosting/plans
Get available hosting plans.
Response
{
  "success": true,
  "data": [
    {
      "id": "basic",
      "name": "Basic Plan",
      "type": "shared",
      "price": 9.99,
      "specs": {
        "cpu": 2,
        "ram": "4GB",
        "storage": "50GB",
        "bandwidth": "1TB"
      },
      "features": [
        "Free SSL",
        "Daily Backups",
        "Email Support"
      ]
    },
    {
      "id": "pro",
      "name": "Pro Plan",
      "type": "vps",
      "price": 29.99,
      "specs": {
        "cpu": 4,
        "ram": "8GB",
        "storage": "100GB",
        "bandwidth": "2TB"
      },
      "features": [
        "Free SSL",
        "Daily Backups",
        "Priority Support",
        "Root Access"
      ]
    }
  ]
}
GET
/hosting/servers
Get user's servers.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "data": [
    {
      "id": "server_001",
      "name": "web-server-01",
      "plan": "pro",
      "status": "active",
      "ip": "192.168.1.101",
      "hostname": "web-server-01.acme.com",
      "uptime": 99.9,
      "statistics": {
        "cpuUsage": 25.5,
        "memoryUsage": 60.2,
        "diskUsage": 45.8
      }
    }
  ]
}
POST
/hosting/servers/:id/power
Perform server power actions (start, stop, restart).
Headers
Authorization: Bearer <token>
Request Body
{
  "action": "restart"
}
Available Actions
  • start - Start server
  • stop - Stop server
  • restart - Restart server
Response
{
  "success": true,
  "message": "Server restart command initiated successfully",
  "data": {
    "id": "server_001",
    "action": "restart",
    "status": "active"
  }
}

Billing Endpoints

GET
/billing/invoices
Get user's invoices.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "data": [
    {
      "id": "inv_001",
      "number": "INV-2026-001",
      "amount": 29.99,
      "status": "paid",
      "dueDate": "2026-06-01T00:00:00.000Z",
      "description": "Pro Plan - June 2026"
    }
  ]
}
GET
/billing/summary
Get billing summary and statistics.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "data": {
    "totalRevenue": 45678.90,
    "thisMonthRevenue": 3456.78,
    "pendingInvoices": 3,
    "overdueInvoices": 2,
    "totalInvoices": 94,
    "paidInvoices": 89,
    "nextBillingDate": "2026-06-01T00:00:00.000Z"
  }
}

Support Endpoints

GET
/support/tickets
Get user's support tickets.
Headers
Authorization: Bearer <token>
Response
{
  "success": true,
  "data": [
    {
      "id": "ticket_001",
      "subject": "Server downtime issue",
      "status": "in_progress",
      "priority": "high",
      "category": "Technical",
      "createdAt": "2026-05-07T10:00:00.000Z",
      "messages": [
        {
          "sender": "user",
          "content": "My VPS server has been down...",
          "timestamp": "2026-05-07T10:00:00.000Z"
        }
      ]
    }
  ]
}
POST
/support/tickets
Create new support ticket.
Headers
Authorization: Bearer <token>
Request Body
{
  "subject": "Server configuration help",
  "description": "I need help configuring my server settings",
  "priority": "medium",
  "category": "Technical"
}
Response
{
  "success": true,
  "message": "Support ticket created successfully",
  "data": {
    "id": "ticket_002",
    "subject": "Server configuration help",
    "status": "open",
    "priority": "medium",
    "createdAt": "2026-05-08T10:00:00.000Z"
  }
}

Quick Test Commands

These are verified commands to test the API endpoints:

Health Check (No auth required)

curl http://localhost:3003/api/health

Hosting Plans (No auth required)

curl http://localhost:3003/api/hosting/plans

Login (Get token)

curl -X POST http://localhost:3003/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@hostingco.com","password":"admin123"}'

Dashboard Stats (Auth required)

curl http://localhost:3003/api/dashboard/stats \
  -H "Authorization: Bearer <token>"

Server Actions (Auth required)

curl -X POST http://localhost:3003/api/hosting/servers/server_id/power \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action":"restart"}'

Endpoint Status

Current status of all API endpoints:

Health Check Working

/api/health

Auth Login Working

/api/auth/login

Hosting Plans Working

/api/hosting/plans

Dashboard Stats Working

/api/dashboard/stats (requires auth)

Server Management Working

/api/hosting/servers/*

Billing Working

/api/billing/*

Support Working

/api/support/*

Authentication Notes:
  • Default admin credentials: admin@hostingco.com / admin123
  • JWT tokens expire after 24 hours
  • Include token in Authorization: Bearer <token> header
  • Protected endpoints return 401 without valid token
Back Quick Start Guide Installation Guide Next