Joy REST API v1

Overview

The API mirrors the console: what you can click, you can call. All endpoints live under https://joy.services/api/v1, accept and return application/json, and are authenticated with a Bearer token that you create in the console. Deployments are asynchronous — you receive a job id and poll it — everything else answers immediately.

Unknown paths under /api/ return 404 {"ok":false,"error":"Unknown endpoint — see /api-integration"}.

Authentication & scopes

Send the token in the Authorization header. Tokens are 20–200 characters, start with joy_ and are stored hashed — if you lose one, revoke it and create another. Each token carries a comma-separated list of scopes; a token with the * scope can do everything. Any token with at least one scope satisfies read.

A token can also be limited to an IP allow-list (CIDR list) and given an expiry date. Requests from other addresses get 403 IP not allowed for this token; expired tokens get 401 Token expired. API access can be disabled for a whole account from the console (403 API disabled for this account).

Errors, limits & conventions

• Every response has ok: true|false. Failures also carry error (human-readable) and status (the HTTP code).
• Rate limit: 600 requests per minute per token → 429 with Retry-After. Deployments are limited to 10 per hour per account, ticket creation to 5 per hour, power actions to 10 per minute per instance and password resets to 3 per 10 minutes.
• Validation errors return 422. Missing resources return 404. An order that could not be paid from the wallet returns 402 with a pay_url.
• Money is always USD as a float (total_usd); where a local amount is included it is labelled (total_local, currency). Timestamps are UTC YYYY-MM-DD HH:MM:SS.
• Instance ids are opaque 32-character hashes (ihash), never the hypervisor VM id.
• Every call is logged (method, path, status, IP, duration) and visible under Console → Account → API tokens.

Account

GET/me — who am I, and what can this token do?

Catalogue & quotes

GET/locations returns regions with available (true when a node is online, a template is verified and IPv4 is in stock), ipv4_stock, price_multiplier and the OS codes installable there.

GET/plans returns three arrays: plans (code, name, family, cores, ram_mb, disk_gb, bandwidth_tb, price_usd_month, price_usd_hour, windows_addon_usd), components keyed by component (unit_price_usd, unit, min, max, step — for custom builds) and cycles (code, months, discount_pct). GET/os lists operating systems.

POST/quote prices a spec without ordering. Send either plan or custom:

Instances

GET/instances lists your servers. Each instance object has the shape below; live is null when the hypervisor has not reported yet, and stale is true when the last report is older than a minute.

POST/instances takes the same body as /quote plus hostname (required, DNS label), optional ssh_key (public key, Linux only) and pay (wallet — default — pays the invoice immediately from your balance; anything else leaves it unpaid with a pay_url). Deployment starts the moment the invoice is paid. Rate limit: 10 deployments per hour.

GET/instances/{id} adds ips[] (ip, gateway, netmask, rdns), credentials (user = root or Administrator, password) and last_job. Treat this response as secret. GET/instances/{id}/stats returns the live snapshot plus series[] of {ts, cpu_pct, net_in_bps, net_out_bps, mem_bytes} points collected every few seconds for the last ~15 minutes.

Power, reinstall, snapshots

POST/instances/{id}/{action} — all actions except rename are asynchronous and answer 202 with a job id and a poll URL.

DELETE/instances/{id} terminates the server and releases its IPs. To prevent accidents the body must repeat the hostname: {"confirm":"api-01"}; otherwise 422 Send {"confirm": "<hostname>"} to destroy. Hourly billing stops immediately; prepaid terms are not refunded.

Jobs

Every asynchronous action returns a job id. GET/jobs/{id} returns status (queued → running → done | failed), step, progress (0–100), type, instance, created_at and finished_at. Deployment steps are clone → configure → boot → agent → network → ready. Poll every 2–5 seconds; a typical deployment finishes in 60–120 seconds.

Billing & invoices

GET/billing (scope billing.read) returns wallet_usd, currency, unpaid[] (id, no, total, currency, total_usd, due, pay_url) and monthly_run_rate_usd — the sum of all active services' monthly prices. GET/invoices returns the last 100 invoices with kind, status, totals, dates and a console URL. Invoices cannot be paid through the API; use the pay_url or top up the wallet.

Tickets

GET/tickets lists your tickets (id, ref, subject, status, priority, department, url). POST/tickets (scope tickets.write, 5 per hour) opens one:

Status

GET https://joy.services/status.json is public, needs no token and is cached for 30 seconds — use it for dashboards and monitors. GET/status on the API returns the same components and incidents plus my_instances[] with each server's status and live hypervisor state.

DNS

Zones on our name servers, the same ones the console manages. GET/dns/zones lists yours (with nameservers[] to set at your registrar and price_usd_month for one more zone). POST/dns/zones (scope dns.write) adds one — a domain or a reverse zone such as 16.7.201.in-addr.arpa; it exists on both name servers when the call returns. GET/dns/zones/{zone} returns the zone with its records[] (id, type, name — @ is the root —, fqdn, content, ttl, priority, disabled). Records: POST/dns/zones/{zone}/records, PUT and DELETE on /dns/zones/{zone}/records/{record}. Types: every type our name servers serve — A, AAAA, CNAME, ALIAS, MX, TXT, SPF, SRV, CAA, NS, PTR, DNAME, TLSA, SMIMEA, SSHFP, OPENPGPKEY, IPSECKEY, CERT, DHCID, HTTPS, SVCB, URI, NAPTR, HINFO, RP, LOC, KX, AFSDB, MINFO, MR, the DNSSEC set (DS, CDS, DNSKEY, CDNSKEY, KEY, RKEY, DLV, CSYNC, ZONEMD, NSEC, NSEC3, NSEC3PARAM, RRSIG, SIG, TKEY, TSIG), A6, APL, WKS, EUI48, EUI64, L32, L64, LP, NID, MAILA, MAILB and LUA; GET/dns/types lists them with the content each expects. Host names in content may be given with or without the final dot; MX/SRV take priority (SRV content is weight port target); TTL 60–604800. A validation problem is a 422 with the reason (the name server's own reason when it refuses a rare type); a name-server problem is a 502 and nothing was changed.

Every zone carries state: pending until the domain is delegated to our name servers, then active (suspended for an unpaid renewal). We ask the registry every 30 minutes and flip the state ourselves; POST/dns/zones/{zone}/check asks at once and returns found[] (the delegation at the parent — source "parent" —, or the public resolvers' view when the parent did not answer), missing[] (ours not yet set), extra[] (foreign name servers still listed) and exact.

Examples — curl · PHP · JavaScript

A complete flow: check the region, quote, deploy on hourly billing, poll the job, print the IP and password, and destroy the server at the end.

Legacy Instances API (/api/connect)

The legacy API is a single JSON POST endpoint at https://joy.services/api/connect/. Every request selects an operation with the type field and is authenticated with two headers. Treat both values as secrets: do not expose them in public repositories, client-side apps or browser code.

Body fields: type (required — dashboardinfo, account_info, machine_list, machine_info, change_machine_state), init_ip and init_browser (recommended — the client IP and browser/app identifier captured by your app).

type = dashboardinfo

Fetches dashboard totals: amount (wallet, string), instances, iram (total RAM), icore (total vCPU), hostings, databases, dns_domains, cdn_domains, total. Note that success is returned as the string "true"/"false" in this format; treat numeric fields as integers.

type = account_info

Returns the account profile: email, verify (1 = verified), twofa (1 = enabled), username, full_name, gender, profile_pic, ip, time, and an api_token object (api_token, api_key, api_reg_ip, status enabled/disabled).

type = machine_list

Lists active compute instances in value[]: id, machine (short id), machine_node (node label), ip, platform (ubuntu / windows), ram, core, storage, expire, extime, price and ihash. Use the ihash as instance_token for the calls below.

type = machine_info

Real-time VM details for one instance (instance_token required). Current holds runtime metrics — status, vmid, cpu (fractional; multiply by 100 for %), mem / maxmem / freemem (bytes), uptime (s), netin / netout, diskread / diskwrite, maxdisk (bytes), nics per interface — and qemuConfig holds the VM configuration (cores, memory, net0, scsi0, …). osinfo may be null. Some values arrive as strings depending on serialization; coerce types in your client.

type = change_machine_state

Changes the power state with machine_state; unsupported values return {"success": false, "error": "invalid_state"}.

Errors. Typical failure causes are missing or invalid headers, an invalid JSON body, an unsupported type, or a request blocked by server-side rules. Check the HTTP status code and parse JSON safely; your backend may return JSON as an encoded string in some layers, so if the first parse returns a string, parse again.

Security notes. If you are building a public website or a client-side SPA, route requests through your backend and keep tokens server-side. Use HTTPS, rotate keys if compromised, restrict allowed IPs where supported, and log request IDs for support.

FAQ & changelog

Need something the API does not expose yet? Open a ticket to the Developers department — we read every one.