Processes API

Introduction
How Processes Work
Retrieve Process
- Request Parameters
- Responses

Introduction

The Processes API provides endpoints for tracking and retrieving the status of asynchronous operations across the Raidboxes platform. Many API operations, such as creating boxes or installing SSL certificates, are processed asynchronously and return a process ID that can be used to monitor progress.

How Processes Work

When you perform certain operations (like creating a box), the API will:

Accept the request and return a 202 Accepted status
Return a process object containing a process_id
Process the operation asynchronously in the background
Update the process status as the operation progresses

You can then use the process ID to check the current status and retrieve results when the operation completes.

Process Statuses

Status	Description
`in_progress`	The operation is currently being processed
`completed`	The operation finished successfully
`failed`	The operation encountered an error

Operations That Use Processes

Operation	Description
Box Creation	Creating new WordPress installations
SSL Installation	Installing SSL certificates
Subscription Changes	Updating subscription details

Example Workflow

# 1. Create a box (returns immediately with process_id)
curl -X POST https://api.raidboxes.io/v1/boxes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"title": "My Site", ...}'
 
# Response: {"process_id": "proc_123", "status": "in_progress", ...}
 
# 2. Check process status
curl -X GET https://api.raidboxes.io/v1/processes/proc_123 \
  -H "Authorization: Bearer YOUR_TOKEN"
 
# 3. Repeat until status is "completed" or "failed"

Retrieve process

Retrieve details of a specific process by its ID.

Endpoint

GET /v1/processes/{id}

Request Parameters

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

Responses

Success Response

Status Code: 200 OK
Description: Process details retrieved successfully
Body:

{
  "data": {
    "process_id": "b116baae-1b84-3497-906f-2a4c3abfe064",
    "user_id": "0991b939-c681-370a-a084-f1986f188651",
    "org_id": "AJ6EJQCF",
    "operation": "POST /v1/boxes",
    "status": "in_progress",
    "process": 10,
    "created_at": "2025-12-01T16:09:59+00:00",
    "updated_at": "2025-12-01T16:14:59+00:00",
    "callback_url": null,
    "result_data": null,
    "error_data": null
  }
}

Field	Type	Description
`process_id`	string	Unique identifier for the process
`user_id`	string	ID of the user who initiated the operation
`org_id`	string	Organization ID
`operation`	string	The API operation being processed
`status`	string	Current status (`in_progress`, `completed`, `failed`)
`process`	integer	Progress percentage (0-100)
`created_at`	string	When the process was created
`updated_at`	string	When the process was last updated
`callback_url`	string	URL for webhook notifications (if configured)
`result_data`	object	Result data when completed
`error_data`	object	Error details when failed

Error Responses

401 Unauthorized

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

404 Not Found

{
    "timestamp": "timestamp",
    "path": "/v1/processes/{id}",
    "request_id": "request-id",
    "message": "Request not found."
}

403 Forbidden

{
    "timestamp": "timestamp",
    "path": "/v1/processes/{id}",
    "request_id": "request-id",
    "message": "No permissions."
}