# Cyberhatak Provider API v1

The contract a server provider implements so Cyberhatak staff can create and run a customer VPS with one click.
If your platform speaks this API, you are plugged in: no custom integration, no per-provider code on our side.

- Transport: HTTPS, JSON (`Content-Type: application/json`), UTF-8.
- Base URL: chosen by you, e.g. `https://api.your-cloud.com`. All paths below are relative to it and start with `/v1`.
- Auth: a long-lived token you issue to Cyberhatak, sent as `Authorization: Bearer <token>`. One token per partner account.
- Times: RFC 3339 in UTC (`2026-09-23T02:14:00Z`).

## 1. Shared identifiers

Cyberhatak sells a fixed catalog. You accept **our** ids and map them to your own products internally.

### Plans (minimum resources you must deliver)

| id   | vCPU | RAM   | Disk (SSD) | Monthly transfer |
| ---- | ---- | ----- | ---------- | ---------------- |
| `xs` | 1    | 1 GB  | 25 GB      | 1 TB             |
| `s`  | 1    | 2 GB  | 40 GB      | 1 TB             |
| `m`  | 2    | 4 GB  | 80 GB      | 2 TB             |
| `l`  | 4    | 8 GB  | 160 GB     | 4 TB             |
| `xl` | 8    | 16 GB | 320 GB     | 6 TB             |

Every server gets one public IPv4. IPv6 is optional.

### Regions

| id     | Location                |
| ------ | ----------------------- |
| `sg`   | Singapore               |
| `jkt`  | Jakarta, Indonesia      |
| `dili` | Dili, Timor-Leste       |

### Images

| id             | Operating system        |
| -------------- | ----------------------- |
| `ubuntu-24.04` | Ubuntu Server 24.04 LTS |
| `ubuntu-22.04` | Ubuntu Server 22.04 LTS |
| `debian-12`    | Debian 12               |
| `rocky-9`      | Rocky Linux 9           |

You only need to support the plans, regions and images you actually offer; report the rest as unavailable in the catalog.

## 2. The Server object

```json
{
  "id": "srv_8f2c1a",
  "reference": "10e5114a-7e20-42a3-9233-352dc88966fe",
  "name": "bot-whatsapp",
  "plan": "m",
  "region": "sg",
  "image": "ubuntu-24.04",
  "status": "running",
  "ipv4": "103.181.42.17",
  "ipv6": null,
  "username": "root",
  "error": null,
  "created_at": "2026-09-23T02:14:00Z",
  "updated_at": "2026-09-23T02:16:41Z"
}
```

| field       | notes |
| ----------- | ----- |
| `id`        | Your id for the server. Opaque to us, stable forever. |
| `reference` | Our VPS id, echoed back. Use it in your own support tools. |
| `status`    | One of `provisioning`, `running`, `stopped`, `suspended`, `deleted`, `error`. |
| `ipv4`      | Required once `status` is `running`. |
| `username`  | The login user for the password we sent (normally `root`). |
| `ssh_port`  | Optional. SSH port when it is not 22 (e.g. NAT or one IP shared by several servers). |
| `error`     | Human-readable reason when `status` is `error`, otherwise `null`. |

Lifecycle: `provisioning` → `running` ⇄ `stopped`, `running`/`stopped` ⇄ `suspended`, any → `deleted`. A failed build goes `provisioning` → `error`.

## 3. Endpoints

### `GET /v1/catalog`
What you can deliver right now. We call it when staff add or test your connection, and before every create.

```json
{
  "plans":   [{ "id": "xs", "available": true }, { "id": "xl", "available": false }],
  "regions": [{ "id": "sg", "available": true }, { "id": "jkt", "available": true }],
  "images":  [{ "id": "ubuntu-24.04", "available": true }]
}
```

### `POST /v1/servers`
Create a server. Must return within 10 seconds; the build itself continues in the background.

Headers: `Idempotency-Key: <reference>` (our VPS id). Repeating the same key must return the **same** server, never a second one.

```json
{
  "reference": "10e5114a-7e20-42a3-9233-352dc88966fe",
  "name": "bot-whatsapp",
  "plan": "m",
  "region": "sg",
  "image": "ubuntu-24.04",
  "root_password": "generated-by-cyberhatak-24-chars"
}
```

`root_password` is generated by Cyberhatak. Set it as the login password and never return it in any response.
Response: `202 Accepted` with the Server object (`status: "provisioning"`).

### `GET /v1/servers/{id}`
Current state. We poll every minute while a server is `provisioning`, and on demand from the staff console.
Response: `200` with the Server object.

### `POST /v1/servers/{id}/actions`
```json
{ "action": "reboot" }
```
`action` is one of `start`, `stop`, `reboot`, `suspend`, `unsuspend`. Response: `202` with the Server object.
We send `suspend` when a customer's monthly payment fails and `unsuspend` when they pay. A suspended server keeps its disk and IP.

### `DELETE /v1/servers/{id}`
Destroy the server and release the IP. Response: `202` with the Server object (`status: "deleted"`). Deleting twice returns the same response.

## 4. Errors

Any non-2xx response carries:

```json
{ "error": { "code": "unavailable", "message": "Plan xl is out of stock in sg" } }
```

| HTTP | code               | when |
| ---- | ------------------ | ---- |
| 400  | `invalid_request`  | Missing or malformed field |
| 401  | `unauthorized`     | Bad or missing token |
| 404  | `not_found`        | Unknown server id |
| 409  | `conflict`         | Same `Idempotency-Key` with a different body |
| 422  | `unavailable`      | Plan, region or image not offered right now |
| 429  | `rate_limited`     | Slow down; include `Retry-After` |
| 5xx  | `internal`         | Your side failed; we retry with backoff |

## 5. Service levels

- `provisioning` → `running` in **15 minutes** or less.
- API p95 response under **2 seconds**.
- Actions take effect within **2 minutes**.
- Planned maintenance announced 48 hours ahead.

Billing between you and Cyberhatak is agreed separately, per server per month.

## 6. Conformance checklist

Before going live, staff run these from the Cyberhatak console against your sandbox:

- [ ] `GET /v1/catalog` answers with our ids
- [ ] Create returns `202` and the server reaches `running` with an `ipv4`
- [ ] Login works with the `root_password` we sent
- [ ] Repeating the create with the same `Idempotency-Key` returns the same `id`
- [ ] `suspend` / `unsuspend` / `reboot` / `stop` / `start` change `status` as described
- [ ] `DELETE` returns `deleted` and the IP stops answering
- [ ] Errors use the format in section 4

A reference implementation (about 90 lines of Node.js) is available on request; ours is used in every Cyberhatak test run.
