Skip to content
Raidboxes

API Overview

Introduction

The Raidboxes Public API provides a unified interface for managing WordPress hosting resources including boxes, subscriptions, SSL certificates, and SSH keys. The API is designed following RESTful principles and uses JWT (JSON Web Tokens) for authentication.

Base URL

All API requests should be made to:

https://api.raidboxes.io

Authentication

The API uses JWT (JSON Web Tokens) for authentication. After successful login, you'll receive an access token that must be included in the Authorization header for all subsequent requests.

Authentication Flow

  1. Login: Send credentials to /v1/login to receive a JWT token
  2. Include Token: Add the token to the Authorization header as Bearer {token}
  3. Refresh: Use /v1/refresh-token to get a new token before expiration

Example:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

For detailed authentication documentation, see Authentication.

API Versioning

The API uses path-based versioning. The current version is v1.

All endpoints are prefixed with /v1/:

POST /v1/login
GET /v1/subscriptions
POST /v1/boxes

Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per authenticated user.

Current Limits:

  • Authentication endpoints: 10 requests per minute
  • General endpoints: 100 requests per minute
  • Resource creation: 20 requests per minute

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum number of requests allowed
  • X-RateLimit-Remaining: Number of requests remaining in the current window
  • X-RateLimit-Reset: Time when the rate limit window resets

Request/Response Format

Content Type

All requests and responses use JSON format:

Content-Type: application/json

Request Structure

{
  "field": "value",
  "nested_object": {
    "nested_field": "value"
  }
}

Response Structure

Successful responses return the requested data directly or wrapped in a logical structure:

{
  "id": "resource_id",
  "attribute": "value",
  "created_at": "2025-01-01T00:00:00+00:00"
}

Error Handling

Standard Error Response Format

All errors follow a consistent structure:

{
  "timestamp": "2025-01-01T10:30:00+00:00",
  "path": "/v1/endpoint",
  "request_id": "unique-request-identifier",
  "message": "Human-readable error message"
}

Validation Errors

Validation errors include detailed field-level information:

{
  "timestamp": "2025-01-01T10:30:00+00:00",
  "path": "/v1/endpoint",
  "request_id": "unique-request-identifier",
  "message": "The field is required. (and 2 more errors)",
  "details": {
    "field_name": [
      {
        "message": "The field is required."
      }
    ]
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 202 Accepted: Request accepted for processing
  • 204 No Content: Successful request with no response body
  • 400 Bad Request: Invalid request data
  • 401 Unauthorized: Authentication required or failed
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server error

Available Endpoints

The Public API provides the following endpoint categories:

Authentication

  • POST /v1/login - User authentication
  • POST /v1/refresh-token - Token refresh

Subscription Management

  • GET /v1/subscriptions - List user subscriptions
  • POST /v1/subscriptions/{id}/cancel - Cancel subscription
  • POST /v1/subscriptions/{id}/items/cancel - Cancel subscription items
  • DELETE /v1/subscriptions/{id}/cancel - Revoke subscription cancellation
  • DELETE /v1/subscriptions/{id}/items/revoke - Revoke item cancellation

Box Management

  • GET /v1/boxes - List all boxes
  • GET /v1/boxes/{id} - Get box details
  • POST /v1/boxes - Create new WordPress box
  • DELETE /v1/boxes/{id} - Delete box

Metrics

  • GET /v1/boxes/{id}/metrics/cpu - Get CPU metrics
  • GET /v1/boxes/{id}/metrics/memory - Get memory metrics
  • GET /v1/boxes/{id}/metrics/storage - Get storage metrics

Cache Management

  • DELETE /v1/boxes/{id}/cache - Clear all caches
  • DELETE /v1/boxes/{id}/cache/opcache - Clear OPcache
  • DELETE /v1/boxes/{id}/cache/varnish - Clear Varnish cache

PHP Settings

  • GET /v1/boxes/php/settings - Get PHP settings
  • PATCH /v1/boxes/{id}/php/settings - Update PHP settings

Process Tracking

  • GET /v1/processes/{id} - Retrieve process status

SSH Key Management

  • GET /v1/ssh-keys - List SSH keys
  • POST /v1/ssh-keys - Create SSH key
  • DELETE /v1/ssh-keys/{id} - Delete SSH key

SSL Certificate Management

  • GET /v1/boxes/{id}/ssl - Get SSL certificate
  • POST /v1/boxes/{id}/ssl - Create SSL certificate
  • DELETE /v1/boxes/{id}/ssl - Delete SSL certificate

For detailed documentation of each endpoint, refer to their respective documentation pages: