S3

API Methods¶

Method	Action	Description
`create_account`	create free S3 account	Creates a free S3 account and bucket for the user.
`create_bucket`	create bucket	Creates a new bucket in an existing S3 account.
`create_order`	create order for paid S3 account	Creates an order for a paid S3 account, initiates billing, and creates the user.
`delete_account`	delete S3 account	Completely deletes the user's S3 account.
`delete_bucket`	delete bucket	Deletes the specified bucket from the S3 account.
`delete_file`	delete file	Deletes the specified file from the bucket.
`get_buckets`	get list of buckets (AWS API)	Returns a list of buckets and traffic information via the AWS API.
`get_buckets_rmq`	get list of buckets (RMQ)	Returns a list of buckets with detailed usage information and access keys via the message queue.
`get_files`	get list of files	Returns a list of files and folders in the specified bucket with pagination and search support.
`get_users`	get list of S3 users	Returns a list of S3 accounts with traffic and storage usage information.
`history`	get plan change history	Returns the change history for the specified pricing plan.
`list_plans`	get list of pricing plans	Returns a list of available S3 pricing plans.
`show_key`	get access key	Returns the decrypted access key (access_key or secret_key) for the S3 account.

s3/create_account¶

Creates a free S3 account and bucket for the user.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_account`
token	✅	string	Authorization token
plan_id	✅	int	Pricing plan ID
bucket_name	✅	string	Name of the bucket to create
location	❌	string	Location (region code, e.g., NL). Default is NL

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=create_account" \
--data "token=HOSTKEY_TOKEN" \
--data "plan_id=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "create_account",
"s3uid": "s3_user_12345"
}

Failure response

{
"code": -1,
"message": "S3 account was created, but had an error: ..."
}

s3/create_bucket¶

Creates a new bucket in an existing S3 account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_bucket`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier
bucket_name	✅	string	Name of the bucket to create

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=create_bucket" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "create_bucket",
"message": {
"status": 200,
"body": "",
"headers": {}
}
}

Failure response

{
"code": -1,
"message": "Create bucket error: Bucket already exists"
}

s3/create_order¶

Creates an order for a paid S3 account, initiates billing, and creates the user.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_order`
token	✅	string	Authorization token
plan_id	✅	int	Pricing plan ID
bucket_name	✅	string	Name of the bucket to create
location	✅	string	Location (region code)

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=create_order" \
--data "token=HOSTKEY_TOKEN" \
--data "plan_id=VALUE" \
--data "bucket_name=VALUE" \
--data "location=VALUE"

Example of a successful response

{
"result": "OK",
"action": "create_order",
"s3uid": "s3_user_67890"
}

Failure response

{
"code": -1,
"message": "issue service paid"
}

s3/delete_account¶

Completely deletes the user's S3 account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_account`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=delete_account" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_account",
"message": null
}

Failure response

{
"code": -1,
"message": "Delete S3 account error: ..."
}

s3/delete_bucket¶

Deletes the specified bucket from the S3 account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_bucket`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier
bucket_name	✅	string	Name of the bucket to delete

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=delete_bucket" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_bucket",
"message": "Bucket deleted successfully"
}

Failure response

{
"code": -1,
"message": "Delete S3 bucket error: Bucket not empty"
}

s3/delete_file¶

Deletes the specified file from the bucket.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_file`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier
bucket_name	✅	string	Bucket name
filename	✅	string	File path

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=delete_file" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE" \
--data "filename=VALUE"

Example of a successful response

{
"result": "OK",
"action": "delete_file",
"message": "File deleted successfully"
}

Failure response

{
"code": -1,
"message": "Delete S3 file error: File not found"
}

s3/get_buckets¶

Returns a list of buckets and traffic information via the AWS API.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_buckets`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=get_buckets" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "get_buckets",
"message": [
{
"name": "bucket-1",
"creation_date": "2023-10-01T12:00:00Z"
}
],
"bandwidth": 102400,
"snapshot": {
"bandwidth_usage": 102400,
"storage_usage": 5000000000,
"created_at": "2023-10-27T10:00:00Z"
}
}

Failure response

{
"code": -1,
"message": "s3/get_buckets: Load bucket error: ..."
}

s3/get_buckets_rmq¶

Returns a list of buckets with detailed usage information and access keys via the message queue.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_buckets_rmq`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=get_buckets_rmq" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE"

Example of a successful response

{
"result": "OK",
"action": "get_buckets_rmq",
"message": [
{
"name": "bucket-1",
"usage": 1024000000
}
],
"bandwidth": 102400,
"usage_storage": 1024000000,
"quota": 5368709120,
"snapshots": [
{
"bandwidth_usage": 102400,
"storage_usage": 1024000000,
"created_at": "2023-10-27T10:00:00Z"
}
],
"access_key": "AKIAIOSFODNN7EXAMPLE",
"secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

Failure response

{
"code": -1,
"message": "S3 account not found for this customer"
}

s3/get_files¶

Returns a list of files and folders in the specified bucket with pagination and search support.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_files`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier
bucket_name	✅	string	Bucket name
continuation_token	❌	string	Token for pagination
max_keys	❌	int	Maximum number of files (up to 100)
search	❌	string	Search string

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=get_files" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "bucket_name=VALUE"

Example of a successful response

{
"result": "OK",
"action": "get_files",
"files": [
{
"key": "folder/file.txt",
"original_key": "folder/file.txt",
"size": 1024,
"last_modified": "2023-10-27T10:00:00Z"
}
],
"folders": [
{
"key": "folder/"
}
],
"next_token": "eyJDb250aW51YXRpb25Ub2tlbiI6IkFCQzEyMyJ9"
}

Failure response

{
"code": -1,
"message": "s3/get_files: Load S3 files error: ..."
}

s3/get_users¶

Returns a list of S3 accounts with traffic and storage usage information.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_users`
token	✅	string	Authorization token
id	❌	int	Client ID (for admin)
plan_id	❌	int	Filter by plan ID
s3uid	❌	string	Filter by S3UID
email	❌	string	Filter by email
billing	❌	string	Filter by billing
bucket_name	❌	string	Filter by bucket name
limit	❌	int	Record limit
order	❌	string	Sort field
order_by	❌	string	Sort direction (ASC/DESC)
period_from	❌	string	Period start date (YYYY-MM-DD)
period_to	❌	string	Period end date (YYYY-MM-DD)

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=get_users" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"action": "get_users",
"s3_users": [
{
"id": 123,
"s3uid": "s3_user_123",
"email": "[email protected]",
"plan_id": 5,
"location": "NL",
"quota": 5368709120,
"traffic": 102400,
"storage_usage": 1024000000
}
]
}

Failure response

{
"code": -1,
"message": "customer not found"
}

s3/history¶

Returns the change history for the specified pricing plan.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `history`
token	✅	string	Authorization token
id	✅	int	Pricing plan ID

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=history" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Example of a successful response

{
"result": "OK",
"action": "history",
"data": [
{
"id": 1,
"action": "update",
"date": "2023-10-27T10:00:00Z",
"details": "Price updated"
}
]
}

Failure response

{
"code": -1,
"message": "Plan not found"
}

s3/list_plans¶

Returns a list of available S3 pricing plans.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list_plans`
token	✅	string	Authorization token
id	❌	int	Specific plan ID (for admin)

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=list_plans" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"action": "list_plans",
"plans": [
{
"id": 1,
"name": "Free Plan",
"quota": 5368709120,
"active": 1,
"locations": [
"NL",
"DE"
],
"monthly_rub": 0,
"monthly_eur": 0,
"monthly_usd": 0,
"storage_type": "standard",
"bandwidth_limit": 0,
"price": {
"monthly_rub": 0,
"monthly_eur": 0,
"monthly_usd": 0
}
}
]
}

Failure response

{
"code": -1,
"message": "s3/list_plans: invalid request"
}

s3/show_key¶

Returns the decrypted access key (access_key or secret_key) for the S3 account.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_key`
token	✅	string	Authorization token
s3uid	✅	string	S3 user identifier
s3_key	✅	string	Key type: 'access_key' or 'secret_key'

Example Request

curl -s "https://api.hostkey.com/s3.php" -X POST \
--data "action=show_key" \
--data "token=HOSTKEY_TOKEN" \
--data "s3uid=VALUE" \
--data "s3_key=VALUE"

Example of a successful response

{
"result": "OK",
"action": "show_key",
"key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

Failure response

{
"code": -1,
"message": "invalid key"
}