API v1

Installer API
Documentation.

PUTRAOFFICIAL Installer API menyediakan endpoint untuk instalasi Windows/RDP pada VPS existing, deployment cloud tertentu, manajemen cloud account, server actions, monitoring status, result, log, dan cancel job.

Base URL
https://installer.tokoputra.id/v1

Authentication

Semua endpoint kecuali /health membutuhkan API key aktif. Kirim key pada header Authorization.

Authorization: Bearer PUTRAOFFICIALXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

API key otomatis dinonaktifkan saat masa subscription berakhir. Jangan menaruh API key di frontend browser, query string, repository publik, atau log.

Quick Start

1. Check service

GET/health

curl https://installer.tokoputra.id/v1/health

2. Read catalog

curl https://installer.tokoputra.id/v1/catalog \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY"

3. Create a job

curl --fail-with-body \ -X POST "https://installer.tokoputra.id/v1/installations" \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ORDER-INV-001" \ --data '{ "client_reference": "INV-001", "cloud": "digitalocean", "mode": "existing", "targets": [{"ip":"203.0.113.10","ssh_port":22}], "source_credential": {"username":"root","password":"LINUX_PASSWORD"}, "windows": {"version_key":"KEY_FROM_CATALOG","edition_key":"standard"}, "rdp": {"password":"RdpPassword123","port":7777} }'

Subscription status

GET/balance

Endpoint ini menampilkan status subscription, plan, tanggal expired, dan sisa hari akses. Riwayat akses subscription juga tersedia di GET /ledger. Semua plan menyediakan unlimited total installation selama subscription aktif; concurrency dan batas per-request tetap mengikuti limit sistem/provider.

{ "ok": true, "mode": "subscription", "plan": "medium", "unlimited_installations": true, "status": "active", "expires_at": "2026-10-27T12:00:00.000Z", "remaining_days": 61 }

Catalog

GET/catalog

Ambil catalog sebelum membuat instalasi. Gunakan version_key, region, plan, dan port rules dari respons. Jangan hard-code pilihan yang dapat berubah.

curl https://installer.tokoputra.id/v1/catalog \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY"

Cloud Accounts

Cloud account disimpan terisolasi per API key. Customer hanya melihat credential_id lokal miliknya sendiri.

Add Linode account

POST/cloud-accounts/linode

curl -X POST https://installer.tokoputra.id/v1/cloud-accounts/linode \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -H "Content-Type: application/json" \ --data '{"token":"LINODE_TOKEN"}'

Add UpCloud account

curl -X POST https://installer.tokoputra.id/v1/cloud-accounts/upcloud \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -H "Content-Type: application/json" \ --data '{"token":"UPCLOUD_API_TOKEN"}'

Add OVHcloud account

curl -X POST https://installer.tokoputra.id/v1/cloud-accounts/ovh \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "endpoint":"ovh-eu", "application_key":"APP_KEY", "application_secret":"APP_SECRET", "consumer_key":"CONSUMER_KEY" }'

List / delete accounts

GET /cloud-accounts GET /cloud-accounts?provider=linode DELETE /cloud-accounts/linode/CRED_LINODE_XXXXXXXX

Server Actions

GET/cloud-accounts/:provider/:credentialId/servers

Lihat server dari cloud credential yang dimiliki API key tersebut.

curl https://installer.tokoputra.id/v1/cloud-accounts/linode/CRED_LINODE_ABC123/servers \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY"

Start, stop, reboot

curl -X POST \ https://installer.tokoputra.id/v1/cloud-accounts/linode/CRED_LINODE_ABC123/servers/123456/actions \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -H "Content-Type: application/json" \ --data '{"action":"reboot"}'

Ganti reboot menjadi start atau stop. Untuk delete, kirim {"action":"delete","confirm":true}.

Create Installation

POST/installations

Gunakan mode existing untuk VPS yang sudah ada. Mode deploy tersedia pada provider yang menyediakan deployment melalui cloud credential.

Field	Required	Description
cloud	Yes	digitalocean, linode, vultr, upcloud, ovh, other
mode	Yes	existing atau deploy
targets	Existing	IP dan ssh_port VPS Linux
source_credential	Depends	credential_id lokal atau username/password SSH
windows.version_key	Yes	Ambil dari catalog
rdp.password	Yes	Minimal 8 karakter
rdp.port	Recommended	Ikuti port rules dari catalog

Deploy example

curl -X POST https://installer.tokoputra.id/v1/installations \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: DEPLOY-INV-002" \ --data '{ "client_reference":"INV-002", "cloud":"linode", "mode":"deploy", "source_credential":{"credential_id":"CRED_LINODE_ABC123"}, "deploy":{"region":"REGION_FROM_CATALOG","plan":"PLAN_FROM_CATALOG","count":1,"label":"RDP-CUSTOMER"}, "windows":{"version_key":"KEY_FROM_CATALOG","edition_key":"standard"}, "rdp":{"password":"RdpPassword123","port":7777} }'

Job Status

GET/installations/:jobId/status

Poll setiap sekitar 3 detik atau ikuti next_poll_after_seconds. Berhenti saat terminal=true.

{ "ok": true, "job_id": "JOB_7D91A4C2F82A", "status": "installing", "progress": 65, "phase": { "code": "windows_installing", "label": "Windows sedang dipasang", "message": "Menyalin file Windows" }, "terminal": false, "successful": false, "next_poll_after_seconds": 3 }

Status	Meaning
accepted / validating	Request diterima dan divalidasi
queued	Menunggu antrean
preparing	Server/launcher disiapkan
installing	Windows sedang dipasang
finishing	Finalisasi Windows
completed	Berhasil
failed	Gagal
cancelled	Dibatalkan

Installation Result

GET/installations/:jobId/result

curl https://installer.tokoputra.id/v1/installations/JOB_ID/result \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY"

Ketika job selesai, result berisi endpoint RDP, username, password yang kamu request, versi Windows, durasi, dan data target yang tersedia.

Logs

GET/installations/:jobId/logs

curl -L "https://installer.tokoputra.id/v1/installations/JOB_ID/logs?download=true" \ -H "Authorization: Bearer $PUTRAOFFICIAL_API_KEY" \ -o JOB_ID.log.txt

Cancel Job

POST/installations/:jobId/cancel

Job hanya dapat dibatalkan saat state engine masih memungkinkan.

SSH & RDP Ports

targets[].ssh_port adalah port SSH Linux sebelum instalasi. rdp.port adalah port Remote Desktop setelah Windows selesai. Keduanya berbeda dan harus mengikuti aturan terbaru dari catalog.

Idempotency

Setiap POST installation wajib membawa header Idempotency-Key unik 8-128 karakter. Jika network timeout, ulangi payload dengan key yang sama. Payload berbeda dengan key yang sama akan ditolak.

Idempotency-Key: ORDER-INV-2026-0001

Error Reference

HTTP	Code	Action
400	invalid_idempotency_key	Periksa header Idempotency-Key
401	invalid_api_key	Periksa API key
403	api_key_expired	Perpanjang subscription
404	job_not_found	Periksa job ID dan key owner
404	cloud_account_not_found	Ambil ulang daftar cloud accounts
409	idempotency_conflict	Gunakan payload lama atau key baru
409	confirm_required	Delete server membutuhkan confirm=true
422	validation_error	Perbaiki payload sesuai catalog/docs
429	active_job_limit	Tunggu job aktif berkurang
502/503	installer_error	Retry bertahap

Production Security

Simpan API key sebagai environment variable atau secret manager.
Jangan panggil endpoint ber-key dari browser milik customer bila secret akan terekspos.
Jangan log password SSH, RDP, cloud token, atau API key.
Gunakan HTTPS dan buat Idempotency-Key unik per order.
Rotasi API key jika dicurigai bocor.

Installer APIDocumentation.