API Name: Create Partition External API
This API onboards an existing, unmanaged partition (mount point) onto an instance that is currently under Lucidity management.
API support for GCP instances is currently undergoing maintenance. We expect full functionality to be restored shortly.
Overview
The partition being onboarded must already exist on the instance and must not be currently managed by Lucidity. The backend automatically resolves the tenant from the provided cloud identifiers, so clients do not need to send a tenantId in the payload.
What does this API do?
It initiates an asynchronous process to bring an existing disk partition under Lucidity's automated management system. By supplying cloud-provider-specific identifiers and partition details (such as the mount point and disk type), the API validates the request and begins the onboarding workflow. If the instance already has a managed partition (meaning a disk pool already exists), the new partition's settings must strictly match the existing configuration.
Common Use Cases
Bringing existing data under management: Onboarding an already-attached, unmanaged data disk so it can utilize Lucidity's automated scaling and monitoring capabilities.
Expanding managed footprints: Adding additional specific mount points to an instance that is already partially managed by the Lucidity agent.
Multi-Cloud Support
The Lucidity API provides a unified interface across AWS, Azure, and GCP.
AWS: cloudProviderAccountId must be the AWS Account ID.
Azure: cloudProviderAccountId must be the Subscription ID, and resourceGroup is mandatory.
GCP: cloudProviderAccountId must be the GCP Project ID.
1. Create Partition
Purpose: Initiates the onboarding process for an unmanaged partition.
ENDPOINT: POST /external/client/api/v1/partition/create
Required Headers
Header | Value | Description |
|---|---|---|
X-Authtype | lucidity_access_token | Specifies the type of authentication being used. |
Authorization | {{access-token}} | Replace with your short-lived access token. |
Content-Type | application/json | Indicates that the request body is in JSON format. |
Request Body Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
instanceIdentifier.cloudProviderAccountId | string | Yes | Cloud account identifier (AWS ID, Azure Sub ID, or GCP Project ID). |
instanceIdentifier.cloudProvider | string | Yes | Cloud service provider (AWS, AZURE, or GCP). |
instanceIdentifier.instanceId | string | Yes | Instance ID (AWS/GCP) or VM name (Azure). |
instanceIdentifier.resourceGroup | string | Conditional | Azure resource group where the instance resides (Mandatory for Azure only). |
partition | string | Yes | Mount point to onboard (e.g., /dev/sdf, D, /mnt/data). |
diskType | string | No | Disk type (e.g., gp3, pd-balanced, Premium_LRS). Must match existing disk pool if one exists. |
diskCache | string | No | Disk cache config. Must match existing disk pool if one exists. |
awsKmsKeyId | string | No | AWS KMS encryption key ARN. |
azureCmkDiskEncryptionSetId | string | No | Azure CMK disk encryption set ID. |
azureCmkPmkDiskEncryptionSetId | string | No | Azure CMK PMK disk encryption set ID. |
gcpKmsKeyName | string | No | GCP KMS key name. |
gcpKmsKeyServiceAccount | string | No | GCP KMS key service account. |
Responses
Success Response (202 Accepted)
{
"status": 1,
"message": "Done Successfully",
"data": {
"isSuccess": true,
"message": "Partition Onboarding Started"
}
}Error Responses
Status Code | Error Type | Description |
|---|---|---|
400 | Bad Request | Validation error (missing/invalid identifier, partition, or Azure resourceGroup). |
401 | Unauthorized | Invalid or expired access token. |
403 | Forbidden | Tenant or instance not authorized for the account. |
412 | Precondition Failed | Disk validation failed, unsupported partition, or config mismatch with existing pool. |
500 | Internal Server Error | Partition onboarding failed. |
503 | Service Unavailable | Unable to contact internal server. |
Best Practices
Security
Never log or commit API tokens to version control.
Use secure credential storage (vaults, secret managers).
Rotate access tokens regularly, as they are short-lived.
Use HTTPS only for all API communications.
Operational Excellence
Encryption Matching: Encryption fields are optional—provide them only if the existing disk pool uses encryption. Providing encryption when none exists (or vice versa) will result in a 412 Precondition Failed error.
Configuration Consistency: Always ensure diskType and diskCache match the instance's existing disk pool to prevent onboarding failures.
Pre-Check Constraints: Verify that the partition actually exists on the target machine and is entirely unmanaged before firing this request to avoid unnecessary 400 or 412 errors.