Instances ApiCustomer Integration Reference (JOY - INTERNAL DOCS)
This document describes the /api/connect endpoint used by
customer dashboards to fetch account and resource information (dashboard totals, account
profile, machine list).
All requests are JSON and authenticated via x-api-token and
x-api-key.
Use the Joy Services API host provided to you. Examples below show an IP-based host.
https://api.joy.services
/api/connect/
POST
Authentication is performed using two HTTP headers: x-api-token and x-api-key.
Important
Treat your x-api-token and x-api-key as secrets. Do not expose them in public repositories, client-side apps, or browser code for public websites.
Primary token identifier
Example: JOY-API-TOKEN#API
API key associated with token
Example: joy-xxx...(long key)...xxx
Recommended: application/json
Ensures JSON response.
Required: application/json
Requests must be JSON.
Recommended: joyconnect
Used for logging/telemetry.
Required:
Provided by Joy Services.
Required:
Provided by Joy Services.
The /api/connect endpoint supports multiple operations using the type field in the JSON body.
string (Required)
Operation selector: dashboardinfo, account_info, machine_list
string (Recommended)
Client IP captured by your app (optional if server auto-detects).
string (Recommended)
Client browser/app identifier (example: Chrome).
Fetch dashboard totals (wallet, instances, resources).
{
"type": "dashboardinfo",
"init_ip": "127.0.0.1",
"init_browser": "Chrome"
}{
"success": "true",
"amount": "932.91",
"instances": 18,
"iram": 115,
"icore": 78,
"hostings": 33,
"databases": 14,
"dns_domains": 15,
"cdn_domains": 1,
"total": 81
}float
Total wallet/billing amount shown on dashboard.
number
Total compute instances.
number
Total allocated RAM (units as per dashboard).
number
Total allocated vCPU cores.
number
Total hosting services.
number
Total database services.
number
Total DNS domains.
number
Total CDN domains.
number
Total items (summary count).
Fetch account profile details.
{
"type": "account_info",
"init_ip": "127.0.0.1",
"init_browser": "Chrome"
}{
"success": "true",
"amount": "$ 932.91",
"email": "email@example.com",
"verify": 1,
"ip": "10.10.125.14",
"time": "2023-08-17 16:26:11",
"twofa": 0,
"username": "joyuser1",
"full_name": "First Last",
"gender": 1,
"profile_pic": "https://www.icegif.com/wp-content/uploads/2023/03/icegif-1393.gif",
"api_token": {
"id": 1,
"api_token": "JOY-API-TOKEN#API",
"api_key": "joy-...(long key)...",
"timestamp": null,
"api_date": null,
"api_reg_ip": "10.10.152.16",
"status": "enabled"
}
}string
Customer email address.
number
Email/identity verification status (1 = verified).
number
2FA status (1 = enabled).
string
Account username.
string
Account full name.
number
Profile gender code (implementation-specific).
string
Profile image URL.
object
Issued token and key metadata.
string
Token value (matches request header format).
string
Key value (matches request header format).
string
Token status: enabled / disabled.
List all active compute instances.
{
"type": "machine_list",
"init_ip": "127.0.0.1",
"init_browser": "Chrome"
}{
"success": "true",
"value": [
{
"id": 342,
"machine": "6001",
"machine_node": "c15-node-joy-london",
"ip": "10.10.112.65",
"platform": "ubuntu",
"price": null,
"extime": "33285031929",
"expire": null,
"ram": 4,
"core": 2,
"storage": 48,
"ihash": "498b5959b4257a8671edd51f2b5cebf7"
},
{
"id": 681,
"machine": "256",
"machine_node": "node4-512gb-mumbai",
"ip": "192.168.155.23",
"platform": "ubuntu",
"price": null,
"extime": "1859621398",
"expire": null,
"ram": 8,
"core": 4,
"storage": 48,
"ihash": "09960a1b793ef22bd7c01b5501f6a1b7"
}
]
}number
Internal machine record ID.
string
Machine/instance short identifier.
string
Host/node label (location / compute node).
string
Primary IP address of the machine.
string
OS/platform (example: ubuntu, windows).
number
Allocated RAM (GB as per dashboard).
number
Allocated vCPU cores.
number
Allocated storage (GB as per dashboard).
string|null
Expiry date/time if applicable, else null.
string
Internal expiry epoch/time format used by system.
string
Internal hash identifier.
number|null
Price field if configured, else null.
Returns real-time VM details (runtime metrics + VM configuration) for a specific instance using instance_token (value typically comes from machine_list as ihash).
ihash from machine_list as
the instance_token.{
"type": "machine_info",
"init_ip": "127.0.0.1",
"init_browser": "Chrome",
"instance_token": "498b5959b4257a8671edd51f2b5cebf7"
}{
"success": true,
"value": "498b5959b4257a8671edd51f2b5cebf7",
"Current": {
"name": "user-x-25nov",
"netout": 18566030361,
"uptime": 29461293,
"agent": 1,
"running-machine": "pc-i440fx-9.0+pve0",
"diskread": 173319141376,
"diskwrite": 788248155136,
"disk": 0,
"maxdisk": 12884901888,
"running-qemu": "9.0.2",
"clipboard": null,
"cpu": 0.015003142419008,
"vmid": 6001,
"maxmem": 4294967296,
"cpus": 2,
"nics": {
"tap6001i0": {
"netin": 2476753613887,
"netout": 18566030361
}
},
"tags": "10.10.240.21",
"pid": 1000980,
"netin": 2476753613887,
"ha": {
"managed": 0
},
"status": "running",
"mem": 3405574144,
"freemem": 696369152,
"qmpstatus": "running",
"balloon": 4294967296
},
"qemuConfig": {
"tags": "10.10.240.21",
"digest": "b2a96ea22cf1c6f7831cd8fcfbf6e2c129ea098f",
"numa": 0,
"cpu": "host",
"sockets": 2,
"ostype": "126",
"cores": 1,
"memory": "4096",
"smbios1": "uuid=3e4f04a2-3e8e-4a89-b621-aaaea962101e",
"scsi0": "ssd-raid:6001/vm-6001-disk-0.raw,aio=threads,cache=unsafe,format=raw,iothread=1,size=12G,ssd=1",
"name": "user-x-25nov",
"onboot": 1,
"scsihw": "virtio-scsi-single",
"agent": "1",
"meta": "creation-qemu=8.1.5,ctime=1712772985",
"boot": "order=scsi0;ide2;net0",
"net0": "virtio=BC:24:11:E1:C1:54,bridge=vmbr0,firewall=1",
"vga": "std"
},
"osinfo": null,
"ip": "10.10.240.21",
"extime": "33285031929",
"os": "ubuntu"
}boolean
Request status.
string
Echo of instance_token.
string
Primary IP of instance.
string
Operating system label (example: ubuntu).
string
Internal expiry/time value used by system.
object
Runtime metrics and current VM status.
string
VM state (example: running).
number
VMID / instance ID.
number
CPU usage value (fractional). Convert to % if needed.
number
Used memory (bytes).
number
Max memory allocated (bytes).
number
Free memory (bytes).
number
Uptime (seconds; platform-dependent).
number
Total inbound network (bytes).
number
Total outbound network (bytes).
number
Total disk read (bytes).
number
Total disk write (bytes).
number
Max disk size (bytes).
object
Per-interface counters (keyed by NIC name).
object
VM configuration parameters returned by platform.
string|number
Configured cores (as returned by platform).
string|number
Configured memory (as returned by platform).
string
Network adapter config string.
string
Disk config string.
null|object
Reserved for OS detection details (may be null).
Data types note
Some values may arrive as strings depending on your backend serialization. Your client should be tolerant and coerce types when required (example: memory, cores, extime).
Changes the power/runtime state of an instance using instance_token and machine_state. If an unsupported state is provided, the API returns invalid_state.
{
"type": "change_machine_state",
"init_ip": "127.0.0.1",
"init_browser": "Chrome",
"machine_state": "start",
"instance_token": "cf25998c59fdbf37f0fada2517242f47"
}{
"success": true,
"value": "machine_already_started"
}string (Required)
Instance token (typically the ihash from machine_list).
string (Required)
Requested action/state change (must be one of the allowed values).
Power On
machine_already_started
Graceful Shutdown
shutdown_success
Hard Stop
stopped_successfully
Graceful Reboot
reboot_success
Hard Reset
power_reset_success
Suspend
machine_paused
Hibernate
machine_hibernated
Resume
machine_already_resumed
{
"success": false,
"error": "invalid_state"
}Client implementation note
Your backend may return JSON as an encoded string in some layers. Client code should parse JSON once; if the first parse returns a string, parse again.
Typical failure causes
Missing/invalid headers (x-api-token, x-api-key), invalid JSON body, unsupported type, or request blocked by server-side rules.
Implement robust error handling: check HTTP status code and parse JSON safely.
{
"success": "false",
"error": "invalid_api_credentials",
"message": "Token or key is invalid or disabled."
}curl -X POST "https://api.joy.services/api/connect/" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: joyconnect" \
-H "x-api-token: JOY-API-xxxxxxxxxxxx" \
-H "x-api-key: joy-xxxxxxxxxxxxxxxx" \
--data-raw '{
"type": "machine_list",
"init_ip": "127.0.0.1",
"init_browser": "Chrome"
}'async function joyConnect(type) {
const res = await fetch("https://api.joy.services/api/connect/", {
method: "POST",
headers: {
"Accept": "application/json",
"Content-Type": "application/json",
"User-Agent": "joyconnect",
"x-api-token": "JOY-API-xxxxxxxxxxxx",
"x-api-key": "joy-xxxxxxxxxxxxxxxx"
},
body: JSON.stringify({
type,
init_ip: "127.0.0.1",
init_browser: "Chrome"
})
});
const data = await res.json().catch(() => ({}));
if (!res.ok || data.success !== "true") {
throw new Error(data.message || "Joy API request failed");
}
return data;
}
$url = "https://api.joy.services/api/connect/";
$payload = json_encode([
"type" => "account_info",
"init_ip" => "127.0.0.1",
"init_browser" => "Chrome"
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Accept: application/json",
"Content-Type: application/json",
"User-Agent: joyconnect",
"x-api-token: JOY-API-xxxxxxxxxxxx",
"x-api-key: joy-xxxxxxxxxxxxxxxx"
],
]);
$out = curl_exec($ch);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($out, true);
if ($http !== 200 || !is_array($data) || ($data["success"] ?? "false") !== "true") {
$msg = $data["message"] ?? "Joy API request failed";
throw new Exception($msg);
}
print_r($data);
Do not expose API keys in browser apps
If you are building a public website or a client-side SPA, route requests through your backend and keep tokens server-side.
Recommended best practices
Use HTTPS, rotate keys if compromised, restrict allowed IPs where supported, and log request IDs for support.