# sunucu.com API Reference (v1.6, 2026-06-03)

- **Base URL:** `https://api.sunucu.com/v1`
- **Auth:** `Authorization: Bearer snc_…` (or `X-API-Key`). Mint keys in the dashboard → Account → API Keys.
- **Format:** JSON. Destructive server operations require the opt-in `servers:destroy` scope.
- **Idempotency:** snapshot-create, reinstall and ticket-create accept an `Idempotency-Key` header (deduped 24h).
- **Rate limit:** 120 requests/minute per API key. Responses carry `X-RateLimit-Limit/-Remaining/-Reset`; a 429 carries `Retry-After`.

## Scopes

| Scope | Description |
|---|---|
| `account:read` | Read your account profile. |
| `servers:read` | List servers and read details, stats, and snapshots. |
| `servers:write` | Power actions, password reset, create/delete snapshots. |
| `servers:destroy` | Reinstall, revert a snapshot, or terminate (destructive; not in defaults). |
| `hosting:read` | List hosting accounts and read details. |
| `hosting:write` | Attach, verify, and remove a custom domain. |
| `domains:read` | List domains and read details. |
| `domains:write` | Update auto-renew, transfer lock, WHOIS privacy, nameservers. |
| `billing:read` | Read invoices, transactions, and wallet balance. |
| `tickets:read` | List tickets and read messages. |
| `tickets:write` | Open tickets, post replies, and close them. |
| `webhooks:read` | List webhook subscriptions and delivery history. |
| `webhooks:write` | Create, edit, delete webhooks; rotate secrets; redeliver. |

## Endpoints

### Account

#### `GET /v1/account` — Get account

Returns the authenticated account profile.

_Scope:_ `account:read`

_Response:_

```json
{
  "id": "ee0d1f04-…",
  "email": "you@example.com",
  "name": "Jane Doe",
  "country": "TR",
  "email_verified": true,
  "created_at": "2026-01-01T00:00:00.000Z"
}
```

### Servers

#### `GET /v1/servers` — List servers

List every server on the account.

_Scope:_ `servers:read`

#### `GET /v1/servers/:id` — Get server

Server detail (backbone-scrubbed — no upstream provider, no provisioning logs).

_Scope:_ `servers:read`

#### `GET /v1/servers/:id/stats` — Live stats

Live CPU / memory / network / disk usage.

_Scope:_ `servers:read`

#### `GET /v1/servers/:id/snapshots` — List snapshots

Disk snapshots (restore points) for the server.

_Scope:_ `servers:read`

#### `POST /v1/servers/:id/power/:action` — Power action

Power the server start, stop, or reboot. `:action` ∈ {start,stop,reboot}.

_Scope:_ `servers:write`

#### `POST /v1/servers/:id/snapshots` — Create snapshot

Take a disk snapshot. Honours an optional Idempotency-Key header.

_Scope:_ `servers:write`

_Request body:_

```json
{ "name": "pre-upgrade", "description": "before kernel bump" }
```

#### `DELETE /v1/servers/:id/snapshots/:snapshotId` — Delete snapshot

Remove a snapshot (non-destructive to the live disk).

_Scope:_ `servers:write`

#### `POST /v1/servers/:id/reinstall` — Reinstall OS

DESTRUCTIVE — wipe the disk and rebuild from an OS template. Honours Idempotency-Key.

_Scope:_ `servers:destroy`

_Request body:_

```json
{ "osTemplate": "ubuntu-22.04", "os": "ubuntu" }
```

#### `POST /v1/servers/:id/snapshots/:snapshotId/revert` — Revert snapshot

DESTRUCTIVE — roll the live disk back to a snapshot.

_Scope:_ `servers:destroy`

#### `DELETE /v1/servers/:id` — Terminate server

DESTRUCTIVE — permanently terminate the server.

_Scope:_ `servers:destroy`

### Hosting

#### `GET /v1/hosting` — List hosting

List web-hosting accounts.

_Scope:_ `hosting:read`

#### `GET /v1/hosting/:id` — Get hosting

Hosting account detail (connection info, backbone-scrubbed).

_Scope:_ `hosting:read`

#### `PUT /v1/hosting/:id/custom-domain` — Set custom domain

Attach a custom domain to a hosting account.

_Scope:_ `hosting:write`

_Request body:_

```json
{ "domain": "example.com" }
```

#### `POST /v1/hosting/:id/custom-domain/verify` — Verify custom domain

Re-check DNS and attach the custom domain once it points to us.

_Scope:_ `hosting:write`

#### `DELETE /v1/hosting/:id/custom-domain` — Remove custom domain

Detach the custom domain from the hosting account.

_Scope:_ `hosting:write`

### Domains

#### `GET /v1/domains` — List domains

List registered domains.

_Scope:_ `domains:read`

#### `GET /v1/domains/:id` — Get domain

Domain detail.

_Scope:_ `domains:read`

#### `PATCH /v1/domains/:id` — Update domain

Update auto-renew, transfer lock, WHOIS privacy, or nameservers.

_Scope:_ `domains:write`

_Request body:_

```json
{ "auto_renew": true, "transfer_lock": true, "nameservers": ["ns1.example.com","ns2.example.com"] }
```

### Billing

#### `GET /v1/billing/invoices` — List invoices

Paginated invoice list. Query: page, limit.

_Scope:_ `billing:read`

#### `GET /v1/billing/invoices/:id` — Get invoice

Single invoice with line items.

_Scope:_ `billing:read`

#### `GET /v1/billing/wallet` — Get wallet

Prepaid wallet balance and state.

_Scope:_ `billing:read`

#### `GET /v1/billing/wallet/transactions` — Wallet transactions

Recent wallet transactions. Query: limit.

_Scope:_ `billing:read`

### Support tickets

#### `GET /v1/tickets` — List tickets

List support tickets.

_Scope:_ `tickets:read`

#### `GET /v1/tickets/:id` — Get ticket

Ticket detail with the message thread.

_Scope:_ `tickets:read`

#### `POST /v1/tickets` — Open ticket

Open a support ticket. Honours Idempotency-Key.

_Scope:_ `tickets:write`

_Request body:_

```json
{ "subject": "Need help", "message": "…", "department": "technical", "priority": "medium" }
```

#### `POST /v1/tickets/:id/reply` — Reply to ticket

Post a customer reply on a ticket.

_Scope:_ `tickets:write`

_Request body:_

```json
{ "body": "Thanks, that worked." }
```

#### `POST /v1/tickets/:id/close` — Close ticket

Close the ticket.

_Scope:_ `tickets:write`

### Webhooks

#### `GET /v1/webhooks` — List webhooks

List webhook subscriptions.

_Scope:_ `webhooks:read`

#### `POST /v1/webhooks` — Create webhook

Subscribe a URL to events. Secret returned ONCE.

_Scope:_ `webhooks:write`

_Request body:_

```json
{ "url": "https://example.com/hooks", "events": ["*"], "description": "prod" }
```

#### `GET /v1/webhooks/:id` — Get webhook

Webhook subscription detail (secret masked).

_Scope:_ `webhooks:read`

#### `PATCH /v1/webhooks/:id` — Update webhook

Change url, events, description, or pause/resume (isActive).

_Scope:_ `webhooks:write`

#### `DELETE /v1/webhooks/:id` — Delete webhook

Delete a subscription.

_Scope:_ `webhooks:write`

#### `POST /v1/webhooks/:id/rotate-secret` — Rotate secret

Issue a fresh signing secret (returned ONCE). Old secret stops immediately.

_Scope:_ `webhooks:write`

#### `GET /v1/webhooks/:id/deliveries` — Delivery log

Recent delivery attempts. Query: limit.

_Scope:_ `webhooks:read`

#### `POST /v1/webhooks/:id/deliveries/:deliveryId/redeliver` — Redeliver

Re-queue a past delivery for another attempt.

_Scope:_ `webhooks:write`

## Webhooks

Each delivery is a POST with an HMAC-SHA256 signature header `X-Sunucu-Signature: t=<ts>,v1=<hex>`, computed over `"<ts>." + raw_body` with your subscription secret. Other headers: `X-Sunucu-Event`, `X-Sunucu-Delivery`. Failed deliveries retry with exponential backoff (1m, 5m, 15m, 1h, 6h).

| Event | Description |
|---|---|
| `server.created` | A server finished provisioning. Payload: serverId, status, label. |
| `server.power.changed` | A power action ran. Payload: serverId, action (start/stop/reboot). |
| `server.reinstalled` | A reinstall ran. Payload: serverId, os, osTemplate. |
| `server.terminated` | A server was terminated. Payload: serverId. |
| `server.suspended` | A server was suspended (e.g. expiry). Payload: serverId, reason. |
| `hosting.created` | A web-hosting account finished provisioning. Payload: hostingId, domain, status. |
| `invoice.created` | A new invoice was issued (any source — order, renewal, admin). Payload: invoiceId, invoiceNumber, status, totalUsdCents, currency. |
| `invoice.paid` | An invoice transitioned to paid (card, PayPal, crypto, or wallet). Payload: invoiceId, invoiceNumber, totalUsdCents, currency. |
| `wallet.deposit.received` | A wallet top-up was credited. Payload: amountUsdCents, gateway, transactionId. |
| `domain.registered` | A domain registration completed (post-payment). Payload: domainId, domain, periodYears, expiresAt. |
| `ticket.created` | A support ticket was opened. Payload: ticketId, ticketNumber, subject, status, priority. |
| `ticket.replied` | Support staff replied to your ticket. Payload: ticketId, ticketNumber, subject, status. |

## Errors

| Code | Meaning |
|---|---|
| 400 Bad Request | Missing or invalid request body parameters. |
| 401 Unauthorized | Missing, invalid, or expired API key. |
| 403 Forbidden | API key lacks the required scope for this action. |
| 404 Not Found | The resource does not exist or belongs to another account. |
| 429 Too Many Requests | Per-key rate limit exceeded (120 req/min). See the X-RateLimit-Limit / -Remaining / -Reset and Retry-After response headers. |
| 500 Internal Server Error | Unexpected server error. If persistent, contact support. |

## Changelog

### v1.6 — 2026-06-03 (latest)

- **new:** Two more webhook events: `invoice.created` (fires for any new invoice — order, renewal, or admin) and `domain.registered` (a registration completed after payment). The catalogue is now 13 events.
- **improved:** Connect-AI (MCP) wizard on the API Keys page — pick your client (Claude Code / Desktop / Cursor / VS Code) and copy a ready-made config.

### v1.5 — 2026-06-03

- **new:** OAuth 2.0 device-code flow (RFC 8628). Connect AI tools by browser-approval instead of pasting a key: the client opens sunucu.com/oauth/device, you approve the requested scopes, and it receives a scoped `snc_at_` access token (+ single-use `snc_rt_` refresh, 90-day). Endpoints under `/oauth/*` with AS metadata at `/.well-known/oauth-authorization-server`. Revoke connected apps anytime from the API Keys page.

### v1.4 — 2026-06-03

- **new:** Model Context Protocol (MCP) server — connect Claude and other AI tools directly to your account at `https://api.sunucu.com/mcp` (Streamable HTTP) using your `snc_` API key as a Bearer token. 37 tools across servers, hosting, domains, billing, tickets and webhooks, scope-gated by the key.

### v1.3 — 2026-06-03

- **new:** Per-key rate limiting — 120 requests/minute per API key, with `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` headers on every response and `Retry-After` on a 429.
- **new:** Four more webhook events: `server.suspended`, `hosting.created`, `invoice.paid` (fires for card / PayPal / crypto / wallet payments alike), and `wallet.deposit.received`.

### v1.2 — 2026-06-03

- **new:** Webhooks — subscribe a URL to account events and receive signed (HMAC-SHA256) POSTs. Eight endpoints under `/v1/webhooks` behind the new `webhooks:read` / `webhooks:write` scopes: list, create, get, update (incl. pause/resume), delete, rotate-secret, delivery log, and redeliver. Failed deliveries retry with exponential backoff (1m→6h).
- **new:** Webhook events: server.created, server.power.changed, server.reinstalled, server.terminated, ticket.created, ticket.replied.

### v1.1 — 2026-06-03

- **new:** Write endpoints. servers:write — power start/stop/reboot, password reset, create/delete snapshots. servers:destroy (opt-in, not in defaults) — reinstall, snapshot revert, terminate. hosting:write — set/verify/remove custom domain. domains:write — update auto-renew / lock / WHOIS / nameservers. tickets:write — open, reply, close.
- **improved:** Idempotency-Key header on snapshot-create, reinstall, and ticket-create dedups retried requests for 24h.

### v1.0 — 2026-06-03

- **new:** Public API launch — read-only endpoints for account, servers (incl. live stats & snapshots), hosting, domains, billing (invoices & wallet) and support tickets. Authenticate with an `snc_…` API key minted from the dashboard.