Skip to content
Raidboxes

Boxes

Introduction

The Box API provides endpoints for managing WordPress boxes. This includes listing, creating, retrieving box details, and deleting boxes. All endpoints require JWT authentication.

List boxes

Retrieve a paginated list of boxes for the authenticated user.

Endpoint

GET /v1/boxes

Request Parameters

Parameter Location Type Required Default Description
Authorization Header string Yes - Bearer token (JWT)
page Query integer No 1 Page number for pagination
per_page Query integer No 10 Number of items per page
sort Query string No - Sort field (prefix with - for descending, e.g., -created_at)
search Query string No - Search term to filter boxes by name or title
filter[staging] Query boolean No - Filter by staging status
filter[type] Query array No - Filter by box type(s)
filter[planId] Query array No - Filter by plan ID(s)
filter[ownership] Query boolean No - Filter by ownership

Example Query

GET /v1/boxes?page=1&per_page=10&sort=-created_at&search=wordpress

Responses

Success Response

  • Status Code: 200 OK
  • Description: List of boxes retrieved successfully
  • Body:
{
  "boxes": [
    {
      "id": "XK7BM2QP",
      "name": "wp4x7kz",
      "title": "Acme Corp Website",
      "domain": "acme-corp.com",
      "ip_v4": "185.175.196.42",
      "ip_v6": "2a00:1c98:60:1011::a1b2:3c4d",
      "status": [ ...
        {
          "type": "staging",
          "state": "inactive"
        },
        {
          "type": "backup",
          "state": "inactive"
        }
      ], 
      "created_at": "2024-03-15T09:30:00+00:00",
      "screenshots": { ...
        "xsmall": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/xsmall",
        "small": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/small",
        "medium": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/medium",
        "large": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/large"
      } 
    }
  ],
  "meta": { ...
    "current_page": 1,
    "per_page": 10,
    "total": 25,
    "last_page": 3
  } 
}
Field Type Description
boxes array Array of box objects
meta.current_page integer Current page number
meta.per_page integer Items per page
meta.total integer Total number of boxes
meta.last_page integer Last page number

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/boxes",
    "request_id": "request-id",
    "message": "Unauthenticated."
}

Get a specific Box

Get the specific box with details by ID.

Endpoint

GET /v1/boxes/{id}

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the box
Authorization Header string Yes Bearer token (JWT)

Responses

Success Response

  • Status Code: 200 OK
  • Description: Response contains the details of the specified box
  • Body:
{
  "id": "XK7BM2QP",
  "name": "wp4x7kz",
  "title": "Acme Corp Website",
  "domain": "acme-corp.com",
  "ip_v4": "185.175.196.42",
  "ip_v6": "2a00:1c98:60:1011::a1b2:3c4d",
  "status": [ ...
    {
      "type": "staging",
      "state": "inactive"
    },
    {
      "type": "backup",
      "state": "inactive"
    },
    {
      "type": "migration",
      "state": "inactive"
    }
  ], 
  "created_at": "2024-03-15T09:30:00+00:00",
  "screenshots": { ...
    "xsmall": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/xsmall",
    "small": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/small",
    "medium": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/medium",
    "large": "https://api-gateway.raidboxes.io/api/v1/boxes/XK7BM2QP/screenshot/large"
  } 
}

Error Responses

401 Unauthorized

Invalid credentials provided.

{
    "timestamp": "timestamp",
    "path": "/v1/boxes/{id}",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
400 Bad Request

Validation errors.

{
  "timestamp": "timestamp",
  "message": "Request could not be processed.",
  "path": "/v1/boxes/{id}",
  "request_id": "3d4379f2-7ceb-4e1e-aa36-cb45f82dd85f"
}

Create

Create a new box for a specific process.

Endpoint

POST /v1/boxes

Request Parameters

Parameter Location Type Required Description
Authorization Header string Yes Bearer token (JWT)

Request Body

Field Type Required Validation Description
title string Yes Min: 3, Max: 150 Title of the box
subscription_id string No Valid UUID Subscription ID
performance_level string Yes Max: 255 Performance level
callback_url string No Valid URL Callback URL for async notifications
ai_assistant boolean No - Enable AI assistant
wordpress object Yes - WordPress configuration
wordpress.version string Yes - WordPress version
wordpress.admin_username string Yes Letters, numbers, dashes, underscores WordPress admin username
wordpress.admin_password string Yes Min: 8, one letter, symbol and number WordPress admin password

Example Request Body

{
  "title": "My WordPress Box",
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
  "performance_level": "basic",
  "callback_url": "https://example.com/webhook/box-created",
  "ai_assistant": false,
  "wordpress": {
    "version": "6.4.2",
    "admin_username": "admin_user",
    "admin_password": "MySecur€Pass123!"
  }
}

Responses

Success Response

  • Status Code: 202 Accepted
  • Description: Your request has been accepted and is being processed asynchronously
  • Body:
{
  "data": {
    "process_id": "58fb017a-0636-3176-90a3-7a9cc14c56bc",
    "user_id": "12345",
    "org_id": "AJ6EJQCF",
    "operation": "POST v1/boxes",
    "status": "accepted",
    "process": 0,
    "created_at": "2025-12-01T16:14:54+00:00",
    "updated_at": "2025-12-01T16:14:54+00:00",
    "callback_url": null,
    "result_data": [],
    "error_data": null
  }
}

Note: Use the returned process_id to track the box creation progress via the Processes API.

Error Responses

401 Unauthorized

Invalid credentials provided.

{
    "timestamp": "timestamp",
    "path": "/v1/boxes",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
400 Bad Request

Validation errors.

{
  "timestamp": "timestamp",
  "message": "The title field is required. (and 5 more errors)",
  "path": "/v1/boxes",
  "request_id": "3d4379f2-7ceb-4e1e-aa36-cb45f82dd85f",
  "details": { ...
    "title": [
      {
        "message": "The title field is required."
      }
    ],
    "performance_level": [
      {
        "message": "The performance level field is required."
      }
    ],
    "wordpress": [
      {
        "message": "The wordpress field is required."
      }
    ],
    "wordpress.version": [
      {
        "message": "The wordpress.version field is required."
      }
    ],
    "wordpress.admin_username": [
      {
        "message": "The wordpress.admin username field is required."
      }
    ],
    "wordpress.admin_password": [
      {
        "message": "The wordpress.admin password field is required."
      }
    ]
  } 
}

Delete

Delete a specified box.

Endpoint

DELETE /v1/boxes/{id}

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the box to delete
Authorization Header string Yes Bearer token (JWT)

Responses

Success Response

  • Status Code: 204 No Content
  • Description: Box deleted successfully
  • Body: Empty

Error Responses

401 Unauthorized

Invalid credentials provided.

{
    "timestamp": "timestamp",
    "path": "/v1/boxes/{id}",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
400 Bad Request

Validation errors.

{
  "timestamp": "timestamp",
  "message": "Request could not be processed.",
  "path": "/v1/boxes/{id}",
  "request_id": "3d4379f2-7ceb-4e1e-aa36-cb45f82dd85f"
}