ADMIN_API_ENDPOINTS.md

# LNVPS Admin API Endpoints

Admin API request/response format reference for LLM consumption.

## Enums

**DiskType**: `"hdd"`, `"ssd"`
**DiskInterface**: `"sata"`, `"scsi"`, `"pcie"`
**VmRunningStates**: `"unknown"`, `"running"`, `"stopped"`, `"creating"`
**AdminVmHistoryActionType**: `"created"`, `"started"`, `"stopped"`, `"restarted"`, `"deleted"`, `"expired"`,
`"renewed"`, `"reinstalled"`, `"state_changed"`, `"payment_received"`, `"configuration_changed"`
**AdminPaymentMethod**: `"lightning"`, `"revolut"`, `"paypal"`, `"stripe"`
**VmHostKind**: `"proxmox"`, `"libvirt"`
**CostPlanIntervalType**: `"day"`, `"month"`, `"year"`
**ApiOsDistribution**: `"ubuntu"`, `"debian"`, `"centos"`, `"fedora"`, `"freebsd"`, `"opensuse"`, `"archlinux"`,
`"redhatenterprise"`
**IpRangeAllocationMode**: `"random"`, `"sequential"`, `"slaac_eui64"`
**NetworkAccessPolicyKind**: `"static_arp"`
**RouterKind**: `"mikrotik"`, `"ovh_additional_ip"`, `"linux_ssh"`
**AdminUserRole**: `"super_admin"`, `"admin"`, `"read_only"`
**AdminUserStatus**: `"active"`, `"suspended"`, `"deleted"`
**SubscriptionPaymentType**: `"purchase"`, `"renewal"`, `"upgrade"`
**SubscriptionType**: `"ip_range"`, `"asn_sponsoring"`, `"dns_hosting"`, `"vps"`
**InternetRegistry**: `"arin"`, `"ripe"`, `"apnic"`, `"lacnic"`, `"afrinic"`
**CpuMfg**: `"unknown"`, `"intel"`, `"amd"`, `"apple"`, `"nvidia"`, `"arm"`
**CpuArch**: `"unknown"`, `"x86_64"`, `"arm64"`
**CpuFeature**: `"SSE"`, `"SSE2"`, `"SSE3"`, `"SSSE3"`, `"SSE4_1"`, `"SSE4_2"`, `"AVX"`, `"AVX2"`, `"FMA"`, `"F16C"`,
`"AVX512F"`, `"AVX512VNNI"`, `"AVX512BF16"`, `"AVXVNNI"`, `"NEON"`, `"SVE"`, `"SVE2"`, `"AES"`, `"SHA"`, `"SHA512"`,
`"PCLMULQDQ"`, `"RNG"`, `"GFNI"`, `"VAES"`, `"VPCLMULQDQ"`, `"VMX"`, `"NestedVirt"`, `"AMX"`, `"SME"`, `"SGX"`, `"SEV"`,
`"TDX"`, `"EncodeH264"`, `"EncodeHEVC"`, `"EncodeAV1"`, `"EncodeVP9"`, `"EncodeJPEG"`, `"DecodeH264"`, `"DecodeHEVC"`,
`"DecodeAV1"`, `"DecodeVP9"`, `"DecodeJPEG"`, `"DecodeMPEG2"`, `"DecodeVC1"`, `"VideoScaling"`, `"VideoDeinterlace"`,
`"VideoCSC"`, `"VideoComposition"`
**GpuMfg**: `"none"`, `"nvidia"`, `"amd"`

## Authentication

```
Authorization: Nostr <base64-encoded-event>
```

## Response Formats

**Single item**: `{"data": T}`
**Paginated list**: `{"data": T[], "total": number, "limit": number, "offset": number}`

## Endpoints

### User Management

#### List Users

```
GET /api/admin/v1/users
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `search`: string (optional) - user pubkey (hex format)

Required Permission: `users::view`

#### Find User by Email

```
GET /api/admin/v1/users/by-email?email={email}
```

Query Parameters:

- `email`: string (required) - the user's email address (case-insensitive; matched via an indexed SHA-256 hash)

Required Permission: `users::view`

Returns the matching `AdminUserInfo`, or a `"User not found"` error if no user has that email.

#### Get User Details

```
GET /api/admin/v1/users/{id}
```

Required Permission: `users::view`

Returns complete user information including VM count and admin status.

#### Update User

```
PATCH /api/admin/v1/users/{id}
```

Required Permission: `users::update`

#### Bulk Message Active Customers

```
POST /api/admin/v1/users/bulk-message
```

Dispatch a bulk message job to send messages to all active customers based on their contact preferences. The job is
processed asynchronously by the worker system.

Request body:

```json
{
  "subject": "Message subject",
  "message": "Message content"
}
```

Response:

```json
{
  "data": {
    "job_dispatched": true,
    "job_id": "1234567890-bulk-message"
  }
}
```

**Note:** The endpoint dispatches a work job and returns immediately with the job ID. The admin user will receive a
completion notification via their contact preferences when the job finishes with full delivery statistics.

**Active customers** are defined as users who:

- Have at least one non-deleted VM (`vm.deleted = false`)
- Have at least one contact method enabled (`contact_email = true` OR `contact_nip17 = true`)
- Have the necessary contact information (email address for email, pubkey for NIP-17)

**Message delivery priority:**

1. Email (if `contact_email = true` and email address exists and SMTP configured)
2. NIP-17 DM (if `contact_nip17 = true` and email failed/unavailable and Nostr configured)

Required Permission: `users::update`

Body (all optional):

```json
{
  "email": "string",
  "contact_nip17": boolean,
  "contact_email": boolean,
  "country_code": "string",
  "billing_name": "string",
  "billing_address_1": "string",
  "billing_address_2": "string",
  "billing_city": "string",
  "billing_state": "string",
  "billing_postcode": "string",
  "billing_tax_id": "string",
  "geo_country_code": "string",
  // ISO 3166-1 alpha-3; empty string clears. Editing geo bumps geo_updated
  "geo_ip": "string",
  // empty string clears
  "admin_role": "super_admin"
  // AdminUserRole enum or null
}
```

### VM Management

#### List VMs

```
GET /api/admin/v1/vms
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `user_id`: number (optional)
- `host_id`: number (optional)
- `pubkey`: string (optional) - hex format
- `region_id`: number (optional)
- `include_deleted`: boolean (optional) - default false

Required Permission: `virtual_machines::view`

Returns paginated list of VMs with complete host and region information. All VMs are guaranteed to have valid host and
region associations - missing references will result in an error.

#### Get VM Details

```
GET /api/admin/v1/vms/{id}
```

Required Permission: `virtual_machines::view`

Returns detailed VM information with complete host and region data. The VM must have valid host and region associations.

The response includes a `subscription` field (type: `AdminSubscriptionInfo`) when the VM is linked to a subscription. This object contains:
- `id` — subscription ID
- `user_id` / `user_pubkey` — owning user's ID and hex-encoded Nostr pubkey
- `is_active` — whether the subscription is currently active
- `interval_amount` / `interval_type` — billing interval
- `currency` — billing currency
- `payment_count` — total number of payments made
- `line_items` — array of `AdminSubscriptionLineItemInfo` objects (see [Subscription Line Item response shape](#subscription-line-item-response-shape))

Example (abbreviated):
```json
{
  "data": {
    "id": 42,
    "subscription": {
      "id": 7,
      "is_active": true,
      "interval_amount": 1,
      "interval_type": "month",
      "currency": "USD",
      "payment_count": 3,
      "line_items": [{
        "id": 12,
        "subscription_type": "vps",
        "amount": 999,
        "setup_amount": 0,
        "configuration": null,
        "resource": { "type": "vps", "vm_id": 42 }
      }]
    }
  }
}
```

`subscription` is `null`/omitted if no subscription is linked to the VM.

#### Create VM for User

```
POST /api/admin/v1/vms
```

Required Permission: `virtual_machines::create`

Creates a VM for a specific user (admin action). The VM creation is processed asynchronously via the work job system.

Body:

```json
{
  "user_id": number,
  // Required - Target user ID
  "template_id": number,
  // Required - VM template ID
  "image_id": number,
  // Required - OS image ID
  "ssh_key_id": number,
  // Required - SSH key ID (must belong to user)
  "ref_code": "string",
  // Optional - Referral code
  "reason": "string"
  // Optional - Admin reason for audit trail
}
```

Response:

```json
{
  "data": {
    "job_id": "stream-id-12345"
  }
}
```

**Validation:**

- User must exist
- Template must exist
- Image must exist
- SSH key must exist and belong to the specified user

**Asynchronous Processing:** This endpoint dispatches a `CreateVm` work job for distributed processing. The operation
returns immediately with a job ID. The VM creation is handled by the provisioner and includes full audit logging with
admin action metadata.

#### Start VM

```
POST /api/admin/v1/vms/{id}/start
```

Required Permission: `virtual_machines::update`

Response:

```json
{
  "data": {
    "job_id": "stream-id-12345"
  }
}
```

#### Stop VM

```
POST /api/admin/v1/vms/{id}/stop
```

Required Permission: `virtual_machines::update`

Response:

```json
{
  "data": {
    "job_id": "stream-id-12345"
  }
}
```

#### Update VM

```
PATCH /api/admin/v1/vms/{id}
```

Required Permission: `virtual_machines::update`

Body (all optional):

```json
{
  "disabled": boolean  // Enable/disable the VM
}
```

Response:

```json
{
  "data": {
    "job_id": "stream-id-12345"
  }
}
```

**Note:** The `disabled` field allows admins to disable a VM without deleting it. When the disabled state changes, a reconfigure job is dispatched to update the VM on the host (e.g., setting `link_down=1` on the network interface). The `job_id` will be empty if no changes were made.

#### Delete VM

```
DELETE /api/admin/v1/vms/{id}
```

Required Permission: `virtual_machines::delete`

Body (optional):

```json
{
  "reason": "string"
}
```

Response:

```json
{
  "data": {
    "job_id": "stream-id-12345"
  }
}
```

#### Calculate VM Refund

```
GET /api/admin/v1/vms/{vm_id}/refund?method={payment_method}&from_date={unix_timestamp}
```

Required Permission: `virtual_machines::view`

Query Parameters:

- `method`: string (required) - Payment method: "lightning", "revolut", "paypal"
- `from_date`: number (optional) - Unix timestamp to calculate refund from (defaults to current time)

Returns calculated pro-rated refund amount for the VM based on remaining time from the specified date and payment
method.

Response:

```json
{
  "data": {
    "amount": number,
    // Refund amount in the currency
    "currency": "string",
    // Currency code (USD, EUR, etc.)
    "rate": number
    // Exchange rate used for calculation
  }
}
```

#### Process VM Refund

```
POST /api/admin/v1/vms/{vm_id}/refund
```

Required Permission: `virtual_machines::delete`

Initiates an automated refund process for a VM. This creates a work job that will be processed asynchronously by the
worker system.

Body:

```json
{
  "payment_method": "lightning",
  // Required - "lightning", "revolut", "paypal"
  "refund_from_date": 1705312200,
  // Optional - Unix timestamp to calculate refund from (defaults to current time)
  "reason": "Customer requested cancellation",
  // Optional - Reason for the refund
  "lightning_invoice": "lnbc..."
  // Required when payment_method is "lightning"
}
```

Response:

```json
{
  "data": {
    "job_dispatched": true,
    "job_id": "stream-id-12345"
  }
}
```

**Note:** The refund is processed asynchronously via work jobs. The admin will receive notifications about the refund
status through their configured contact preferences.

#### Extend VM

```
PUT /api/admin/v1/vms/{id}/extend
```

Required Permission: `virtual_machines::update`

Body:

```json
{
  "days": 30,
  // Required: 1-365
  "reason": "string"
  // Optional
}
```

#### List VM History

```
GET /api/admin/v1/vms/{vm_id}/history
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0

Required Permission: `virtual_machines::view`

#### Get VM History Entry

```
GET /api/admin/v1/vms/{vm_id}/history/{history_id}
```

Required Permission: `virtual_machines::view`

#### List VM Payments

```
GET /api/admin/v1/vms/{vm_id}/payments
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0

Required Permission: `payments::view`

#### Get VM Payment

```
GET /api/admin/v1/vms/{vm_id}/payments/{payment_id}
```

Required Permission: `payments::view`

#### Complete VM Payment

```
POST /api/admin/v1/vms/{vm_id}/payments/{payment_id}/complete
```

Required Permission: `payments::update`

Manually marks a VM payment as paid. Atomically sets `is_paid=true`, records `paid_at`, and extends the VM expiry by the payment's `time_value`. For upgrade payments, dispatches a `ProcessVmUpgrade` work job; otherwise dispatches `CheckVm`.

**No request body required.**

Returns the updated `AdminVmPaymentInfo`.

Errors:
- `400` if the payment is already completed
- `400` if the payment does not belong to the specified VM
- `400` if the payment ID format is invalid

### Subscription Management

#### List Subscriptions

```
GET /api/admin/v1/subscriptions
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `user_id`: number (optional) - filter by user ID
- `search`: string (optional) - case-insensitive substring match against subscription name and description
- `status`: string (optional) - filter by active state; one of `active` or `inactive`. Omit for all
- `auto_renewal`: boolean (optional) - filter by auto-renewal flag. Omit for all

All filters are optional and combine with AND. Filtering is applied before pagination, so `total` reflects the filtered count.

Required Permission: `subscriptions::view`

Returns paginated list of subscriptions with embedded line items and payment count. Each `AdminSubscriptionInfo` includes a `user_pubkey` field (hex-encoded Nostr pubkey of the owning user) alongside `user_id`. Embedded line items use the [Subscription Line Item response shape](#subscription-line-item-response-shape).

#### Get Subscription Details

```
GET /api/admin/v1/subscriptions/{id}
```

Required Permission: `subscriptions::view`

Returns complete subscription information including all line items and payment count. Line items use the [Subscription Line Item response shape](#subscription-line-item-response-shape).

#### Create Subscription

```
POST /api/admin/v1/subscriptions
```

Required Permission: `subscriptions::create`

Request body:

```json
{
  "user_id": number,
  "name": string,
  "description": string
  (optional),
  "expires": string
  (optional,
  ISO
  8601
  datetime),
  "is_active": boolean,
  "currency": string,
  // "USD", "EUR", "BTC", etc.
  "interval_amount": number,
  "interval_type": "day"
  |
  "month"
  |
  "year",
  "setup_fee": number,
  // in cents/millisats
  "auto_renewal_enabled": boolean,
  "external_id": string
  (optional)
}
```

Response: Subscription with line items

#### Update Subscription

```
PATCH /api/admin/v1/subscriptions/{id}
```

Required Permission: `subscriptions::update`

Request body (all fields optional):

```json
{
  "name": string,
  "description": string,
  "expires": string
  (ISO
  8601
  datetime)
  or
  null,
  "is_active": boolean,
  "currency": string,
  "interval_amount": number,
  "interval_type": "day"
  |
  "month"
  |
  "year",
  "setup_fee": number,
  "auto_renewal_enabled": boolean,
  "external_id": string
}
```

Response: Updated subscription with line items

#### Delete Subscription

```
DELETE /api/admin/v1/subscriptions/{id}
```

Required Permission: `subscriptions::delete`

**Note:** Cannot delete subscriptions with paid payments. Returns error if paid payments exist.

Response:

```json
{
  "data": {
    "deleted": true
  }
}
```

#### Subscription Line Item response shape

`AdminSubscriptionLineItemInfo` objects (returned by the line-item endpoints below and embedded in subscription/VM responses) have the form:

```json
{
  "id": number,
  "subscription_id": number,
  "subscription_type": "ip_range" | "asn_sponsoring" | "dns_hosting" | "vps",
  "name": string,
  "description": string | null,
  "amount": number,        // recurring cost in cents/millisats
  "setup_amount": number,  // one-time setup fee in cents/millisats
  "configuration": object | null,
  "resource": object | null
}
```

`subscription_type` is the **SubscriptionType** discriminant identifying the kind of service this line item bills for.

`resource` is a typed, tagged reference to the linked resource, **resolved from `subscription_type`** by looking up the back-reference tables (e.g. `vm.subscription_line_item_id`, `ip_range_subscription.subscription_line_item_id`). Use it to resolve the linked resource directly. Current shapes:

- `{ "type": "vps", "vm_id": number }` — links to a VM
- `{ "type": "ip_range", "ip_range_subscription_id": number }` — links to an IP range subscription

`resource` is `null` when the type has no linkable resource (`asn_sponsoring`, `dns_hosting`) or the back-reference row cannot be found.

`configuration` is raw JSON used for **upgrade bookkeeping only** (e.g. `{ "new_cpu": 4, "new_memory": 8589934592, "new_disk": null }`) — it is recorded when a VM's specs are changed and is **not** a resource link. Do not use it to resolve the linked resource; use `resource` instead. It is `null` for line items that have never been upgraded.

#### List Subscription Line Items

```
GET /api/admin/v1/subscriptions/{subscription_id}/line_items
```

Required Permission: `subscription_line_items::view`

Returns all line items for a specific subscription (see [response shape](#subscription-line-item-response-shape)). Note that line items are also included in subscription responses.

#### Get Subscription Line Item

```
GET /api/admin/v1/subscription_line_items/{id}
```

Required Permission: `subscription_line_items::view`

Returns a single line item (see [response shape](#subscription-line-item-response-shape)).

#### Create Subscription Line Item

```
POST /api/admin/v1/subscription_line_items
```

Required Permission: `subscription_line_items::create`

Request body:

```json
{
  "subscription_id": number,
  "subscription_type": "ip_range" | "asn_sponsoring" | "dns_hosting" | "vps",
  "name": string,
  "description": string
  (optional),
  "amount": number,
  // recurring cost in cents/millisats
  "setup_amount": number,
  // one-time setup fee in cents/millisats
  "configuration": object
  (optional)
  // raw upgrade bookkeeping JSON only (e.g. new_cpu/new_memory/new_disk);
  // NOT a resource link. The linked resource is resolved from
  // subscription_type and returned as `resource` in responses.
}
```

Response: Created line item (see [response shape](#subscription-line-item-response-shape)). The `resource` field is resolved from `subscription_type`; `configuration` is echoed back as stored.

#### Update Subscription Line Item

```
PATCH /api/admin/v1/subscription_line_items/{id}
```

Required Permission: `subscription_line_items::update`

Request body (all fields optional):

```json
{
  "subscription_type": "ip_range" | "asn_sponsoring" | "dns_hosting" | "vps",
  "name": string,
  "description": string,
  "amount": number,
  "setup_amount": number,
  "configuration": object
  // raw upgrade bookkeeping JSON only; NOT a resource link
}
```

Response: Updated line item (see [response shape](#subscription-line-item-response-shape)). Changing `subscription_type` changes which resource the `resource` field resolves against.

#### Delete Subscription Line Item

```
DELETE /api/admin/v1/subscription_line_items/{id}
```

Required Permission: `subscription_line_items::delete`

Response:

```json
{
  "data": {
    "deleted": true
  }
}
```

#### List Subscription Payments

```
GET /api/admin/v1/subscriptions/{subscription_id}/payments
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0

Required Permission: `subscription_payments::view`

Returns paginated list of payments for a specific subscription.

#### Get Subscription Payment

```
GET /api/admin/v1/subscription_payments/{hex_id}
```

Required Permission: `subscription_payments::view`

Returns detailed payment information including company details if available.

#### Complete Subscription Payment

```
POST /api/admin/v1/subscription_payments/{hex_id}/complete
```

Required Permission: `subscription_payments::update`

Manually marks a subscription payment as paid. Sets `is_paid=true`, records `paid_at`, extends the subscription by 30 days, and activates it.

**No request body required.**

Returns the updated `AdminSubscriptionPaymentInfo`.

Errors:
- `400` if the payment is already completed
- `400` if the payment ID format is invalid

### Role Management

#### List Roles

```
GET /api/admin/v1/roles
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0

Required Permission: `roles::view`

#### Get Role Details

```
GET /api/admin/v1/roles/{id}
```

Required Permission: `roles::view`

#### Create Role

```
POST /api/admin/v1/roles
```

Required Permission: `roles::create`

Body:

```json
{
  "name": "string",
  "description": "string (optional)",
  "permissions": [
    "string"
  ]
}
```

#### Update Role

```
PATCH /api/admin/v1/roles/{id}
```

Required Permission: `roles::update`

Body (all optional):

```json
{
  "name": "string",
  "description": "string",
  "permissions": [
    "string"
  ]
}
```

#### Delete Role

```
DELETE /api/admin/v1/roles/{id}
```

Required Permission: `roles::delete`

### User Role Assignments

#### Get User Roles

```
GET /api/admin/v1/users/{user_id}/roles
```

Required Permission: `users::view`

#### Assign Role to User

```
POST /api/admin/v1/users/{user_id}/roles
```

Required Permission: `users::update`

Body:

```json
{
  "role_id": number
}
```

#### Revoke Role from User

```
DELETE /api/admin/v1/users/{user_id}/roles/{role_id}
```

Required Permission: `users::update`

#### Get Current User's Admin Roles

```
GET /api/admin/v1/me/roles
```

Required Permission: None

### Host Management

#### List Hosts

```
GET /api/admin/v1/hosts
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0

Required Permission: `hosts::view`

#### Get Host Details

```
GET /api/admin/v1/hosts/{id}
```

Required Permission: `hosts::view`

#### Update Host Configuration

```
PATCH /api/admin/v1/hosts/{id}
```

Required Permission: `hosts::update`

Body (all optional):

```json
{
  "name": "string",
  "ip": "string",
  "api_token": "string",
  "region_id": number,
  "kind": "libvirt",
  // VmHostKind enum
  "vlan_id": number
  |
  null,
  "mtu": number
  |
  null,
  // MTU setting for network configuration - use null to clear
  "enabled": boolean,
  "cpu_mfg": "string",
  // CPU manufacturer (e.g. "intel", "amd", "apple")
  "cpu_arch": "string",
  // CPU architecture (e.g. "x86_64", "arm64")
  "cpu_features": ["string"],
  // CPU features (e.g. ["AVX2", "AES", "VMX"])
  "load_cpu": number,
  "load_memory": number,
  "load_disk": number,
  "ssh_user": "string",
  // SSH username for host utilities (default: root)
  "ssh_key": "string"
  |
  null
  // SSH private key (PEM format) - use null to clear
}
```

#### Create Host

```
POST /api/admin/v1/hosts
```

Required Permission: `hosts::create`

Body:

```json
{
  "name": "string",
  // Required
  "ip": "string",
  // Required
  "api_token": "string",
  // Required
  "region_id": number,
  // Required
  "kind": "proxmox",
  // Required - VmHostKind enum
  "vlan_id": number
  |
  null,
  "mtu": number,
  // Optional - MTU setting for network configuration
  "cpu": number,
  // Required
  "cpu_mfg": "string",
  // Optional - CPU manufacturer (e.g. "intel", "amd", "apple")
  "cpu_arch": "string",
  // Optional - CPU architecture (e.g. "x86_64", "arm64")
  "cpu_features": ["string"],
  // Optional - CPU features (e.g. ["AVX2", "AES", "VMX"])
  "memory": number,
  // Required
  "enabled": boolean,
  // Optional - default true
  "load_cpu": number,
  // Optional - default 1.0
  "load_memory": number,
  // Optional - default 1.0
  "load_disk": number,
  // Optional - default 1.0
  "ssh_user": "string",
  // Optional - SSH username for host utilities (default: root)
  "ssh_key": "string"
  // Optional - SSH private key (PEM format)
}
```

#### List Host Disks

```
GET /api/admin/v1/hosts/{id}/disks
```

Required Permission: `hosts::view`

#### Get Host Disk Details

```
GET /api/admin/v1/hosts/{host_id}/disks/{disk_id}
```

Required Permission: `hosts::view`

#### Create Host Disk

```
POST /api/admin/v1/hosts/{host_id}/disks
```

Required Permission: `hosts::update`

Body:

```json
{
  "name": "string",
  // Required - Disk name (e.g., "main-storage")
  "size": number,
  // Required - Size in bytes
  "kind": "ssd",
  // Required - DiskType enum: "hdd" or "ssd"
  "interface": "pcie",
  // Required - DiskInterface enum: "sata", "scsi", or "pcie"
  "enabled": boolean
  // Optional - Default: true
}
```

#### Update Host Disk Configuration

```
PATCH /api/admin/v1/hosts/{host_id}/disks/{disk_id}
```

Required Permission: `hosts::update`

Body (all optional):

```json
{
  "name": "string",
  // Disk name
  "size": number,
  // Size in bytes
  "kind": "ssd",
  // DiskType enum: "hdd" or "ssd"
  "interface": "pcie",
  // DiskInterface enum: "sata", "scsi", or "pcie"
  "enabled": boolean
  // Enable/disable disk
}
```

#### List Unmanaged VMs

```
GET /api/admin/v1/hosts/{id}/vms/unmanaged
```

Required Permission: `hosts::view`

Discovers VMs that exist on the host but are **not** tracked in the database
(candidates for import). The admin service has no direct connection to the host,
so it dispatches a discovery job to the worker and waits for the reply over a
temporary Redis pub/sub channel; this endpoint therefore requires a running
worker and Redis (returns an error otherwise) and may take up to ~30s. Currently
supported on Proxmox hosts only. VMs outside the managed id range (Proxmox
`vmid < 100`) are omitted since they can't be imported.

Returns an array:

```json
[
  {
    "host_vm_id": number,
    // Raw host VM id (e.g. Proxmox vmid)
    "mapped_vm_id": number | null,
    // Database id this VM would map to on import (vmid - 100)
    "name": "string" | null,
    "cpu": number,
    // Allocated CPU cores
    "memory": number,
    // Allocated memory in bytes
    "disk_size": number,
    // Primary disk size in bytes
    "disk_storage": "string" | null,
    // Storage pool backing the primary disk
    "mac_address": "string" | null,
    "running": boolean
  }
]
```

#### Import VM

```
POST /api/admin/v1/hosts/{id}/vms/import
```

Required Permission: `virtual_machines::create`

Imports an existing host VM into the database, assigning it to a user. Billing
always uses the region's **custom pricing** (required) — if the region has no
enabled custom pricing the import fails. The VM's current specs (CPU/memory/disk,
read live from the host) are captured into a custom template. The database VM id
is fixed by the host id mapping (Proxmox `vmid = db_id + 100`) so all subsequent
lifecycle operations target the correct host VM. No changes are made on the host.
Currently supported on Proxmox hosts only.

The work is performed asynchronously by the worker; the response returns a
`job_id` whose progress can be followed on the job feedback WebSocket.

Body:

```json
{
  "host_vm_id": number,
  // Required - Raw host VM id (e.g. Proxmox vmid)
  "user_id": number,
  // Required - User the imported VM is assigned to
  "reason": "string"
  // Optional - Recorded in VM history metadata
}
```

Response:

```json
{
  "job_id": "string"
}
```

### Region Management

#### List Regions

```
GET /api/admin/v1/regions
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `hosts::view`

Returns paginated list of VM host regions with configuration details, host counts, and statistics (only active VMs are
counted).

#### Get Region Details

```
GET /api/admin/v1/regions/{id}
```

Required Permission: `hosts::view`

Returns detailed information about a specific region including host count and statistics (only active VMs are counted).

#### Create Region

```
POST /api/admin/v1/regions
```

Required Permission: `hosts::create`

Body:

```json
{
  "name": "string",
  "company_id": "number | null"
}
```

#### Update Region Configuration

```
PATCH /api/admin/v1/regions/{id}
```

Required Permission: `hosts::update`

Body parameters (all optional):

```json
{
  "name": "string",
  "enabled": boolean,
  "company_id": "number | null"
}
```

#### Delete Region

```
DELETE /api/admin/v1/regions/{id}
```

Required Permission: `hosts::delete`

Note: Regions with assigned hosts cannot be deleted and will be disabled instead to preserve referential integrity.

### VM OS Image Management

#### List VM OS Images

```
GET /api/admin/v1/vm_os_images
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `vm_os_image::view`

Returns paginated list of VM OS images with distribution, version, and configuration details.

#### Get VM OS Image Details

```
GET /api/admin/v1/vm_os_images/{id}
```

Required Permission: `vm_os_image::view`

Returns detailed information about a specific VM OS image.

#### Create VM OS Image

```
POST /api/admin/v1/vm_os_images
```

Required Permission: `vm_os_image::create`

Body:

```json
{
  "distribution": "ubuntu",
  // ApiOsDistribution enum: "ubuntu", "debian", "centos", "fedora", "freebsd", "opensuse", "archlinux", "redhatenterprise"
  "flavour": "string",
  // e.g., "server", "desktop"
  "version": "string",
  // e.g., "22.04", "11", "8"
  "enabled": boolean,
  "release_date": "string (ISO 8601)",
  "url": "string",
  // URL to the cloud image
   "default_username": "string (optional)",
   // Default SSH username
   "sha2": "string (optional)",
   // SHA-2 checksum (SHA-256, SHA-384, or SHA-512) for image verification
   "sha2_url": "string (optional)"
   // URL to the SHA-2 checksums file (e.g., https://cloud.debian.org/images/cloud/trixie/latest/SHA512SUMS)
}
```

#### Update VM OS Image

```
PATCH /api/admin/v1/vm_os_images/{id}
```

Required Permission: `vm_os_image::update`

Body (all optional):

```json
{
  "distribution": "debian",
  // ApiOsDistribution enum: "ubuntu", "debian", "centos", "fedora", "freebsd", "opensuse", "archlinux", "redhatenterprise"
  "flavour": "string",
  "version": "string",
  "enabled": boolean,
  "release_date": "string (ISO 8601)",
  "url": "string",
   "default_username": "string",
   "sha2": "string (optional)",
   // SHA-2 checksum (SHA-256, SHA-384, or SHA-512) for image verification
   "sha2_url": "string (optional)"
   // URL to the SHA-2 checksums file (e.g., https://cloud.debian.org/images/cloud/trixie/latest/SHA512SUMS)
}
```

#### Trigger Image Download

```
POST /api/admin/v1/vm_os_images/{id}/download
```

Required Permission: `vm_os_image::update`

Enqueues a `DownloadOsImages` work job for the specified image. The worker will download the image to all configured hosts, verifying the checksum against `sha2_url` (or `sha2`) and re-downloading if the file is stale or missing.

Returns:

```json
"Download job enqueued"
```

#### Delete VM OS Image

```
DELETE /api/admin/v1/vm_os_images/{id}
```

Required Permission: `vm_os_image::delete`

Note: VM OS images that are referenced by existing VMs cannot be deleted.

### VM Template Management

#### List VM Templates

```
GET /api/admin/v1/vm_templates
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `vm_template::view`

Returns paginated list of VM templates with configuration details, cost plan names, and region names.

#### Get VM Template Details

```
GET /api/admin/v1/vm_templates/{id}
```

Required Permission: `vm_template::view`

Returns detailed information about a specific VM template including cost plan and region information.

#### Create VM Template

```
POST /api/admin/v1/vm_templates
```

Required Permission: `vm_template::create`

Body:

```json
{
  "name": "string",
  "enabled": boolean,
  // optional, default true
  "expires": "string (ISO 8601) | null",
  // optional
  "cpu": number,
  // CPU cores
  "cpu_mfg": "string",
  // optional - CpuMfg enum, default "unknown" (matches any host)
  "cpu_arch": "string",
  // optional - CpuArch enum, default "unknown" (matches any host)
  "cpu_features": ["string"],
  // optional - array of CpuFeature enum values, default [] (matches any host)
  "memory": number,
  // Memory in bytes
  "disk_size": number,
  // Disk size in bytes
  "disk_type": "hdd",
  // DiskType enum: "hdd" or "ssd"
  "disk_interface": "sata",
  // DiskInterface enum: "sata", "scsi", or "pcie"
  "cost_plan_id": number,
  // optional - if not provided, cost plan will be auto-created
  "region_id": number,
  // Cost plan auto-creation fields (used when cost_plan_id not provided)
  "cost_plan_name": "string",
  // optional, defaults to "{template_name} Cost Plan"
  "cost_plan_amount": number,
  // required if cost_plan_id not provided, in smallest currency units (cents/millisats)
  "cost_plan_currency": "string",
  // optional, defaults to "USD"
  "cost_plan_interval_amount": number,
  // optional, defaults to 1
  "cost_plan_interval_type": "day"
  |
  "month"
  |
  "year",
  // optional, defaults to "month"
  "disk_iops_read": number,
  // optional - max disk read IOPS (default uncapped)
  "disk_iops_write": number,
  // optional - max disk write IOPS (default uncapped)
  "disk_mbps_read": number,
  // optional - max disk read throughput in MB/s (default uncapped)
  "disk_mbps_write": number,
  // optional - max disk write throughput in MB/s (default uncapped)
  "network_mbps": number,
  // optional - max network bandwidth in Mbit/s (default uncapped)
  "cpu_limit": number
  // optional - max CPU usage as fraction of allocated cores, e.g. 0.5 (default uncapped)
}
```

#### Update VM Template

```
PATCH /api/admin/v1/vm_templates/{id}
```

Required Permission: `vm_template::update`

Body (all optional):

```json
{
  "name": "string",
  "enabled": boolean,
  "expires": "string (ISO 8601) | null",
  "cpu": number,
  "cpu_mfg": "string | null",
  // CpuMfg enum - set null to clear (reset to unknown)
  "cpu_arch": "string | null",
  // CpuArch enum - set null to clear (reset to unknown)
  "cpu_features": ["string"] | null,
  // array of CpuFeature enum values - set null to clear
  "memory": number,
  "disk_size": number,
  "disk_type": "string",
  "disk_interface": "string",
  "cost_plan_id": number,
  "region_id": number,
  "cost_plan_name": "string",
  // Update associated cost plan name
  "cost_plan_amount": number,
  // Update associated cost plan amount in smallest currency units (cents/millisats)
  "cost_plan_currency": "string",
  // Update associated cost plan currency
  "cost_plan_interval_amount": number,
  // Update associated cost plan interval amount
  "cost_plan_interval_type": "day"
  |
  "month"
  |
  "year",
  // Update associated cost plan interval type
  "disk_iops_read": number | null,
  // Max disk read IOPS — set null to remove limit
  "disk_iops_write": number | null,
  // Max disk write IOPS — set null to remove limit
  "disk_mbps_read": number | null,
  // Max disk read throughput in MB/s — set null to remove limit
  "disk_mbps_write": number | null,
  // Max disk write throughput in MB/s — set null to remove limit
  "network_mbps": number | null,
  // Max network bandwidth in Mbit/s — set null to remove limit
  "cpu_limit": number | null
  // Max CPU usage as fraction of allocated cores — set null to remove limit
}
```

#### Delete VM Template

```
DELETE /api/admin/v1/vm_templates/{id}
```

Required Permission: `vm_template::delete`

Note: VM templates that are referenced by existing VMs cannot be deleted. When a template is deleted, its associated
cost plan will also be deleted if no other templates are using it.

### Cost Plan Management

Cost plans define the billing structure for VM templates. When creating VM templates, you can either specify an existing
cost plan or let the system automatically create a new one.

#### List Cost Plans

```
GET /api/admin/v1/cost_plans
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `vm_template::view`

Returns paginated list of cost plans with template usage counts.

#### Get Cost Plan Details

```
GET /api/admin/v1/cost_plans/{id}
```

Required Permission: `vm_template::view`

Returns detailed information about a specific cost plan including the number of templates using it.

#### Create Cost Plan

```
POST /api/admin/v1/cost_plans
```

Required Permission: `vm_template::create`

Body:

```json
{
  "name": "string",
  "amount": number,
  // Cost amount in smallest currency units (cents for fiat, millisats for BTC)
  "currency": "string",
  // Currency code (e.g., "USD", "EUR", "BTC")
  "interval_amount": number,
  // Billing interval count (must be > 0)
  "interval_type": "day"
  |
  "month"
  |
  "year"
  // Billing interval type
}
```

#### Update Cost Plan

```
PATCH /api/admin/v1/cost_plans/{id}
```

Required Permission: `vm_template::update`

Body (all optional):

```json
{
  "name": "string",
  "amount": number,
  // Cost amount in smallest currency units (cents for fiat, millisats for BTC)
  "currency": "string",
  "interval_amount": number,
  "interval_type": "day"
  |
  "month"
  |
  "year"
}
```

#### Delete Cost Plan

```
DELETE /api/admin/v1/cost_plans/{id}
```

Required Permission: `vm_template::delete`

Note: Cost plans that are referenced by existing VM templates cannot be deleted.

### Custom Pricing Models Management

#### List Custom Pricing Models

```
GET /api/admin/v1/custom_pricing
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset
- `region_id`: number (optional) - Filter by region ID
- `enabled`: boolean (optional) - Filter by enabled status

Required Permission: `vm_custom_pricing::view`

Returns paginated list of custom pricing models with configuration details, region names, and disk pricing information.

#### Get Custom Pricing Model Details

```
GET /api/admin/v1/custom_pricing/{id}
```

Required Permission: `vm_custom_pricing::view`

Returns detailed information about a specific custom pricing model including associated disk pricing configurations.

#### Create Custom Pricing Model

```
POST /api/admin/v1/custom_pricing
```

Required Permission: `vm_custom_pricing::create`

Body:

```json
{
  "name": "string",
  "enabled": boolean,
  // optional, default true
  "expires": "string (ISO 8601) | null",
  // optional, null for no expiration
  "region_id": number,
  "currency": "string",
  // e.g., "USD", "EUR", "BTC"
  "cpu_mfg": "string",
  // optional - CpuMfg enum, default "unknown" (matches any host)
  "cpu_arch": "string",
  // optional - CpuArch enum, default "unknown" (matches any host)
  "cpu_features": ["string"],
  // optional - array of CpuFeature enum values, default [] (matches any host)
  "cpu_cost": number,
  // Cost per CPU core per month in smallest currency units (cents/millisats)
  "memory_cost": number,
  // Cost per GB RAM per month in smallest currency units (cents/millisats)
  "ip4_cost": number,
  // Cost per IPv4 address per month in smallest currency units (cents/millisats)
  "ip6_cost": number,
  // Cost per IPv6 address per month in smallest currency units (cents/millisats)
  "min_cpu": number,
  // Minimum CPU cores allowed
  "max_cpu": number,
  // Maximum CPU cores allowed
  "min_memory": number,
  // Minimum memory in bytes
  "max_memory": number,
  // Maximum memory in bytes
  "disk_iops_read": number,
  // optional - Maximum disk read IOPS (omit or null = uncapped)
  "disk_iops_write": number,
  // optional - Maximum disk write IOPS (omit or null = uncapped)
  "disk_mbps_read": number,
  // optional - Maximum disk read throughput in MB/s (omit or null = uncapped)
  "disk_mbps_write": number,
  // optional - Maximum disk write throughput in MB/s (omit or null = uncapped)
  "network_mbps": number,
  // optional - Maximum network bandwidth in Mbit/s (omit or null = uncapped)
  "cpu_limit": number,
  // optional - Maximum CPU usage as a fraction of allocated cores e.g. 0.5 = 50% (omit or null = uncapped)
  "disk_pricing": [
    // Array of disk pricing configurations
    {
      "kind": "ssd",
      // DiskType enum: "hdd" or "ssd"
      "interface": "pcie",
      // DiskInterface enum: "sata", "scsi", or "pcie"
      "cost": number,
      // Cost per GB per month in smallest currency units (cents/millisats)
      "min_disk_size": number,
      // Minimum disk size in bytes for this type/interface
      "max_disk_size": number
      // Maximum disk size in bytes for this type/interface
    }
  ]
}
```

#### Update Custom Pricing Model

```
PATCH /api/admin/v1/custom_pricing/{id}
```

Required Permission: `vm_custom_pricing::update`

Body (all optional):

```json
{
  "name": "string",
  "enabled": boolean,
  "expires": "string (ISO 8601) | null",
  "region_id": number,
  "currency": "string",
  "cpu_mfg": "string",
  // CpuMfg enum - filter hosts by CPU manufacturer
  "cpu_arch": "string",
  // CpuArch enum - filter hosts by CPU architecture
  "cpu_features": ["string"],
  // array of CpuFeature enum values - filter hosts by required CPU features
  "cpu_cost": number,
  // Cost per CPU core in smallest currency units (cents/millisats)
  "memory_cost": number,
  // Cost per GB RAM in smallest currency units (cents/millisats)
  "ip4_cost": number,
  // Cost per IPv4 address in smallest currency units (cents/millisats)
  "ip6_cost": number,
  // Cost per IPv6 address in smallest currency units (cents/millisats)
  "min_cpu": number,
  // Minimum CPU cores allowed
  "max_cpu": number,
  // Maximum CPU cores allowed
  "min_memory": number,
  // Minimum memory in bytes
  "max_memory": number,
  // Maximum memory in bytes
  "disk_iops_read": "number | null",
  // Maximum disk read IOPS - send null to clear
  "disk_iops_write": "number | null",
  // Maximum disk write IOPS - send null to clear
  "disk_mbps_read": "number | null",
  // Maximum disk read throughput in MB/s - send null to clear
  "disk_mbps_write": "number | null",
  // Maximum disk write throughput in MB/s - send null to clear
  "network_mbps": "number | null",
  // Maximum network bandwidth in Mbit/s - send null to clear
  "cpu_limit": "number | null",
  // Maximum CPU usage as fraction of allocated cores e.g. 0.5 = 50% - send null to clear
  "disk_pricing": [
    {
      "kind": "ssd",
      // DiskType enum: "hdd", "ssd"
      "interface": "pcie",
      // DiskInterface enum: "sata", "scsi", "pcie"
      "cost": number,
      // Cost per GB in smallest currency units (cents/millisats)
      "min_disk_size": number,
      // Minimum disk size in bytes for this type/interface
      "max_disk_size": number
      // Maximum disk size in bytes for this type/interface
    }
  ]
}
```

#### Delete Custom Pricing Model

```
DELETE /api/admin/v1/custom_pricing/{id}
```

Required Permission: `vm_custom_pricing::delete`

Note: Custom pricing models that are referenced by existing VMs cannot be deleted and will be disabled instead to
preserve billing consistency.

#### List Custom Templates for Pricing Model

```
GET /api/admin/v1/custom_pricing/{pricing_id}/templates
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `vm_custom_pricing::view`

Returns paginated list of custom VM templates that use this pricing model.

#### Create Custom VM Template

```
POST /api/admin/v1/custom_pricing/{pricing_id}/templates
```

Required Permission: `vm_custom_pricing::create`

Body:

```json
{
  "cpu": number,
  // Number of CPU cores
  "memory": number,
  // Memory in bytes
  "disk_size": number,
  // Disk size in bytes
  "disk_type": "string",
  // "hdd" or "ssd"
  "disk_interface": "string"
  // "sata", "scsi", or "pcie"
}
```

#### Get Custom VM Template Details

```
GET /api/admin/v1/custom_templates/{id}
```

Required Permission: `vm_custom_pricing::view`

Returns detailed information about a specific custom VM template including calculated pricing breakdown.

#### Update Custom VM Template

```
PATCH /api/admin/v1/custom_templates/{id}
```

Required Permission: `vm_custom_pricing::update`

Body (all optional):

```json
{
  "cpu": number,
  "memory": number,
  "disk_size": number,
  "disk_type": "string",
  "disk_interface": "string",
  "pricing_id": number
  // Change pricing model
}
```

#### Delete Custom VM Template

```
DELETE /api/admin/v1/custom_templates/{id}
```

Required Permission: `vm_custom_pricing::delete`

Note: Custom templates that are referenced by existing VMs cannot be deleted.

#### Calculate Custom Pricing

```
POST /api/admin/v1/custom_pricing/{pricing_id}/calculate
```

Required Permission: `vm_custom_pricing::view`

Body:

```json
{
  "cpu": number,
  // Number of CPU cores
  "memory": number,
  // Memory in bytes
  "disk_size": number,
  // Disk size in bytes
  "disk_type": "ssd",
  // Enum: "hdd" or "ssd"
  "disk_interface": "pcie",
  // Enum: "sata", "scsi", or "pcie"
  "ip4_count": number,
  // Number of IPv4 addresses (optional, default 1)
  "ip6_count": number
  // Number of IPv6 addresses (optional, default 1)
}
```

Returns calculated pricing breakdown for the specified configuration without creating a template (all costs in smallest
currency units - cents/millisats):

```json
{
  "currency": "string",
  "cpu_cost": number,
  // Cost for CPU cores in smallest currency units
  "memory_cost": number,
  // Cost for RAM in smallest currency units
  "disk_cost": number,
  // Cost for disk in smallest currency units
  "ip4_cost": number,
  // Cost for IPv4 addresses in smallest currency units
  "ip6_cost": number,
  // Cost for IPv6 addresses in smallest currency units
  "total_monthly_cost": number
  // Total monthly cost in smallest currency units
}
```

#### Get Region Pricing Models

```
GET /api/admin/v1/regions/{region_id}/custom_pricing
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset
- `enabled`: boolean (optional) - Filter by enabled status

Required Permission: `vm_custom_pricing::view`

Returns all custom pricing models available for a specific region.

#### Copy Custom Pricing Model

```
POST /api/admin/v1/custom_pricing/{id}/copy
```

Required Permission: `vm_custom_pricing::create`

Body:

```json
{
  "name": "string",
  // Name for the new pricing model
  "region_id": number,
  // Target region ID (optional, defaults to source region)
  "enabled": boolean
  // Enable the new pricing model (optional, default true)
}
```

Creates a copy of an existing custom pricing model with all disk pricing configurations.

### Company Management

#### List Companies

```
GET /api/admin/v1/companies
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `company::view`

Returns paginated list of companies with basic information and region count.

#### Get Company Details

```
GET /api/admin/v1/companies/{id}
```

Required Permission: `company::view`

Returns detailed information about a specific company including the number of regions assigned to it.

#### Create Company

```
POST /api/admin/v1/companies
```

Required Permission: `company::create`

Body:

```json
{
  "name": "string",
  // Required - Company name
  "address_1": "string | null",
  // Optional - Primary address line
  "address_2": "string | null",
  // Optional - Secondary address line
  "city": "string | null",
  // Optional - City
  "state": "string | null",
  // Optional - State/province
  "country_code": "string | null",
  // Optional - Country code
  "tax_id": "string | null",
  // Optional - Tax identification number
  "base_currency": "string",
  // Required - Base currency code (EUR, USD, GBP, CAD, CHF, AUD, JPY, BTC)
  "postcode": "string | null",
  // Optional - Postal/ZIP code
  "phone": "string | null",
  // Optional - Phone number
  "email": "string | null",
  // Optional - Contact email
  "referral_rate": 0.0
  // Optional - Default referral commission (whole %, default 0) applied to a
  // referred VM's first payment when the referrer has no per-referrer override
}
```

The `base_currency` field is validated against the supported Currency enum values. Invalid currency codes will be
rejected with an error message listing valid currencies. `referral_rate` must be >= 0.

#### Update Company

```
PATCH /api/admin/v1/companies/{id}
```

Required Permission: `company::update`

Body (all optional):

```json
{
  "name": "string",
  // Company name (cannot be empty if provided)
  "address_1": "string | null",
  // Primary address line
  "address_2": "string | null",
  // Secondary address line
  "city": "string | null",
  // City
  "state": "string | null",
  // State/province
  "country_code": "string | null",
  // Country code
  "tax_id": "string | null",
  // Tax identification number
  "base_currency": "string",
  // Base currency code (EUR, USD, GBP, CAD, CHF, AUD, JPY, BTC)
  "postcode": "string | null",
  // Postal/ZIP code
  "phone": "string | null",
  // Phone number
  "email": "string | null",
  // Contact email
  "referral_rate": 0.0
  // Default referral commission (whole %); must be >= 0
}
```

The `base_currency` field is validated against the supported Currency enum values. `referral_rate` (when provided) must be >= 0.

GET/list company responses include `referral_rate` (the company's default referral commission %).

Note: Empty strings are treated as null values (clearing the field).

#### Delete Company

```
DELETE /api/admin/v1/companies/{id}
```

Required Permission: `company::delete`

Note: Companies with assigned regions cannot be deleted. You must first reassign or remove all regions before deleting a
company.

### IP Range Management

#### List IP Ranges

```
GET /api/admin/v1/ip_ranges
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset
- `region_id`: number (optional) - Filter by region ID

Required Permission: `ip_range::view`

Returns paginated list of IP ranges with region names, access policy names, and assignment counts.

Each IP range also includes a `routers` array — the routers that route the range, resolved via the range's access
policy. Each entry is `{ "id": number, "name": string }`. The array is empty when the range has no access policy or
the policy has no router configured.

#### Get IP Range Details

```
GET /api/admin/v1/ip_ranges/{id}
```

Required Permission: `ip_range::view`

Returns detailed information about a specific IP range including region name, access policy name, and number of active
IP assignments.

#### Create IP Range

```
POST /api/admin/v1/ip_ranges
```

Required Permission: `ip_range::create`

Body:

```json
{
  "cidr": "string",
  // Required - CIDR notation (e.g., "192.168.1.0/24")
  "gateway": "string",
  // Required - Gateway IP address
  "enabled": boolean,
  // Optional - Default: true
  "region_id": number,
  // Required - Region ID
  "reverse_zone_id": "string | null",
  // Optional - Reverse DNS zone ID (provider specific, e.g. Cloudflare reverse zone id)
  "access_policy_id": "number | null",
  // Optional - Access policy ID
  "allocation_mode": "sequential",
  // IpRangeAllocationMode enum: "random", "sequential", or "slaac_eui64", default: "sequential"
  "use_full_range": boolean,
  // Optional - Use first and last IPs in range, default: false
  "forward_dns_server_id": "number | null",
  // Optional - dns_server id used for forward (A/AAAA) records
  "reverse_dns_server_id": "number | null",
  // Optional - dns_server id used for reverse (PTR) records
  "forward_zone_id": "string | null"
  // Optional - Forward DNS zone id (provider specific, e.g. Cloudflare forward zone id)
}
```

#### Update IP Range

```
PATCH /api/admin/v1/ip_ranges/{id}
```

Required Permission: `ip_range::update`

Body (all optional):

```json
{
  "cidr": "string",
  // CIDR notation (e.g., "192.168.1.0/24")
  "gateway": "string",
  // Gateway IP address
  "enabled": boolean,
  // Enable/disable range
  "region_id": number,
  // Region ID
  "reverse_zone_id": "string | null",
  // Reverse DNS zone ID (null to clear)
  "access_policy_id": "number | null",
  // Access policy ID (null to clear)
  "allocation_mode": "sequential",
  // IpRangeAllocationMode enum: "random", "sequential", or "slaac_eui64"
  "use_full_range": boolean,
  // Use first and last IPs in range
  "forward_dns_server_id": "number | null",
  // dns_server id for forward (A/AAAA) records (null to clear)
  "reverse_dns_server_id": "number | null",
  // dns_server id for reverse (PTR) records (null to clear)
  "forward_zone_id": "string | null"
  // Forward DNS zone id (null to clear)
}
```

#### Delete IP Range

```
DELETE /api/admin/v1/ip_ranges/{id}
```

Required Permission: `ip_range::delete`

Note: IP ranges with active IP assignments cannot be deleted. You must first remove all IP assignments before deleting
an IP range.

#### List Free IPs in Range

```
GET /api/admin/v1/ip_ranges/{id}/free_ips
```

Required Permission: `ip_range::view`

Returns a list of all unassigned (free) IP addresses in the specified IPv4 range.

**Limitations:**
- Only available for IPv4 ranges. IPv6 ranges are too large to enumerate and will return an error.
- Reserved IPs (gateway, network address, broadcast address) are excluded from the list.

Response:

```json
{
  "data": [
    "192.168.1.2",
    "192.168.1.3",
    "192.168.1.5",
    "..."
  ]
}
```

#### Patch DNS for Range

```
POST /api/admin/v1/ip_ranges/{id}/patch_dns
```

Required Permission: `ip_range::update`

Queues a background job (`PatchIpRangeDns`) that re-applies forward + reverse DNS records for every
(non-deleted) IP assignment in the range, reconciling them to the range's current DNS server
configuration. Useful after changing a range's `forward_dns_server_id` / `reverse_dns_server_id`
(e.g. switching reverse DNS to OVH). Per-assignment DNS failures are logged and skipped so one bad
record can't abort the batch. Returns a `JobResponse` (`{ "job_id": string }`).

### Access Policy Management

#### List Access Policies

```
GET /api/admin/v1/access_policies
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `access_policy::view`

Returns paginated list of access policies with router names and IP range usage counts.

#### Get Access Policy Details

```
GET /api/admin/v1/access_policies/{id}
```

Required Permission: `access_policy::view`

Returns detailed information about a specific access policy including router name and number of IP ranges using this
policy.

#### Create Access Policy

```
POST /api/admin/v1/access_policies
```

Required Permission: `access_policy::create`

Body:

```json
{
  "name": "string",
  // Required - Policy name
  "kind": "static_arp",
  // NetworkAccessPolicyKind enum: "static_arp", default: "static_arp"
  "router_id": "number | null",
  // Optional - Router ID for policy application
  "interface": "string | null"
  // Optional - Interface name for policy application
}
```

#### Update Access Policy

```
PATCH /api/admin/v1/access_policies/{id}
```

Required Permission: `access_policy::update`

Body (all optional):

```json
{
  "name": "string",
  // Policy name
  "kind": "static_arp",
  // NetworkAccessPolicyKind enum: "static_arp"
  "router_id": "number | null",
  // Router ID (null to clear)
  "interface": "string | null"
  // Interface name (null to clear)
}
```

#### Delete Access Policy

```
DELETE /api/admin/v1/access_policies/{id}
```

Required Permission: `access_policy::delete`

Note: Access policies that are used by IP ranges cannot be deleted. You must first remove the policy from all IP ranges
before deleting it.

### Router Management

#### List Routers

```
GET /api/admin/v1/routers
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `router::view`

Returns paginated list of routers with configuration details and access policy usage counts.

#### Get Router Details

```
GET /api/admin/v1/routers/{router_id}
```

Required Permission: `router::view`

Returns detailed information about a specific router including the number of access policies using this router.

#### Create Router

```
POST /api/admin/v1/routers
```

Required Permission: `router::create`

Body:

```json
{
  "name": "string",
  // Required - Router name
  "enabled": boolean,
  // Optional - Default: true
  "kind": "mikrotik",
  // RouterKind enum: "mikrotik" or "ovh_additional_ip"
  "url": "string",
  // Required - Router API URL
  "token": "string"
  // Required - Authentication token
}
```

#### Update Router

```
PATCH /api/admin/v1/routers/{router_id}
```

Required Permission: `router::update`

Body (all optional):

```json
{
  "name": "string",
  // Router name
  "enabled": boolean,
  // Enable/disable router
  "kind": "mikrotik",
  // RouterKind enum: "mikrotik" or "ovh_additional_ip"
  "url": "string",
  // Router API URL
  "token": "string"
  // Authentication token
}
```

#### Delete Router

```
DELETE /api/admin/v1/routers/{router_id}
```

Required Permission: `router::delete`

Note: Routers that are used by access policies cannot be deleted. You must first remove the router from all access
policies before deleting it.

#### List Router Tunnels

```
GET /api/admin/v1/routers/{router_id}/tunnels
```

Required Permission: `router::view`

Returns the cached tunnel inventory discovered on the router (GRE/VXLAN/WireGuard). Each entry: `id`, `router_id`,
`name`, `kind` (`"gre"` | `"vxlan"` | `"wireguard"`), `local_addr`, `remote_addr`, `enabled`, `last_seen`. Refreshed
by a background sampler (~60s).

Field meanings:

- `enabled` — **administrative** state. `true` = the interface is configured and not shut down. This is independent of
  whether the tunnel is actually passing traffic.
- `local_addr` / `remote_addr` — tunnel endpoints. A value of `"any"` (e.g. the catch-all `gre0`/`gretap0` template
  interfaces) means no specific endpoint is bound; these are usually unused template devices.
- `last_seen` — when the background sampler last observed this interface in the router's inventory (not a traffic
  timestamp).

#### Get Tunnel Traffic History

```
GET /api/admin/v1/routers/{router_id}/tunnels/{tunnel_name}/traffic
```

Required Permission: `router::view`

Query parameters (optional): `from`, `to` (RFC3339 timestamps; default: last 24 hours).

Returns per-tunnel traffic samples: `tunnel_name`, `rx_bytes`, `tx_bytes`, `sampled_at`. Tunnel interface counters
are the canonical per-session traffic source — BGP sessions expose no byte counters.

#### Toggle Tunnel

```
POST /api/admin/v1/routers/{router_id}/tunnels/{tunnel_name}/toggle
```

Required Permission: `router::update`

Enable or disable a tunnel interface.

Body:

```json
{
  "enabled": boolean
}
```

Returns a `JobResponse` (`{ "job_id": "string" }`). The change is applied asynchronously by the worker (Linux
`ip link set <iface> up|down`, RouterOS `disabled` flag) and the tunnel cache is refreshed afterwards. The cached
`enabled` flag reflects the interface's live up/down state.

#### List BGP Sessions

```
GET /api/admin/v1/routers/{router_id}/bgp/sessions
```

Required Permission: `router::view`

Returns cached BGP sessions: `id`, `router_id`, `name`, `peer_ip`, `peer_asn`, `local_asn`, `state`,
`prefixes_received`, `prefixes_sent`, `enabled`, `direction` (`"upstream"` | `"downstream"` | `"peer"` |
`"unknown"`), `last_seen`.

Field meanings (note that `enabled` and `state` are **independent** — `enabled` is admin config, `state` is the live
protocol status):

- `enabled` — **administrative** state. `true` = the session is configured and not administratively shut down
  (the operator wants it up). This is *not* the same as the session being up. Toggled via the endpoint below.
- `state` — **operational** BGP FSM state, reported live by the routing daemon and copied verbatim. It is **not**
  a boolean and does **not** mean "disabled". Standard progression is
  `Idle` → `Connect` → `Active` → `OpenSent` → `OpenConfirm` → `Established`, plus `Down` (BIRD: protocol not started
  or not up). Only `Established` means the session is up and exchanging routes.
  - `"Established"` — session is up; `prefixes_received`/`prefixes_sent` are populated.
  - `"Active"` — the local router is actively trying to reach the peer (TCP not yet established) — typically the
    peer is unreachable or not answering.
  - `"Down"` / `"Idle"` — session is enabled but not up (transport down, neighbor mis-config, AFI not enabled on the
    remote side, ACL/next-hop reachability, etc.).
- `prefixes_received` / `prefixes_sent` — route counts; `null` until the session reaches `Established`.
- `direction` — peer classification relative to us: `"upstream"` (transit provider), `"downstream"` (customer),
  `"peer"` (settlement-free peer), or `"unknown"` (not yet classified — common for sessions that are not
  `Established`).
- `last_seen` — when the background sampler last refreshed this session's cached state.

> **Common confusion:** a session showing `"enabled": true` with `"state": "Down"` is *not* a contradiction — it is
> administratively on but the BGP protocol has not come up. A frequent real-world pattern is an IPv6 session being
> `Established` while the IPv4 session to the same peer is `Down`/`Active`, which points to an IPv4-transport or
> IPv4-AFI problem rather than a disabled session.

#### Toggle BGP Session

```
POST /api/admin/v1/routers/{router_id}/bgp/sessions/toggle
```

Required Permission: `router::update`

Body:

```json
{
  "session_id": "string",
  // Backend session id from the sessions listing (protocol name on BIRD, .id on Mikrotik)
  "enabled": boolean
}
```

Returns a `JobResponse` (`{ "job_id": "string" }`). The enable/disable is applied asynchronously by the worker and
the session cache is refreshed afterwards.

#### List BGP Routes

```
GET /api/admin/v1/routers/{router_id}/bgp/routes
```

Required Permission: `router::view`

Returns the router's cached BGP route table — the prefixes the router originates/announces, plus a detected default
route. Each `AdminRouterBgpRoute`:

- `router_id` — owning router id.
- `prefix` — destination prefix in CIDR notation.
- `next_hop` — next hop / gateway, or `null`.
- `is_default` — `true` when this entry is the router's default route (`0.0.0.0/0` / `::/0`).
- `last_seen` — when the background sampler last refreshed this route's cached state.

Routes are refreshed (~60s) alongside tunnels and BGP sessions by replacing the whole per-router snapshot each cycle,
so prefixes the router no longer originates disappear. Multiple routes to the same prefix (ECMP / differing
next-hops) are preserved — prefix is not a unique key. The originated-route query is scoped to locally-originated
prefixes, so it stays bounded even on routers carrying a full DFZ table.

#### Set Default Route

```
POST /api/admin/v1/routers/{router_id}/routes/default
```

Required Permission: `router::update`

Install or replace the router's **static** default route.

Body:

```json
{
  "next_hop": "string"
  // Next-hop / gateway IP address. The address family of the default route
  // (0.0.0.0/0 vs ::/0) is inferred from this value.
}
```

Returns a `JobResponse` (`{ "job_id": "string" }`). The change is applied asynchronously by the worker and the route
cache is refreshed afterwards. An invalid `next_hop` (not an IP address) is rejected. Only available on routers that
support BGP/routing.

#### Clear Default Route

```
DELETE /api/admin/v1/routers/{router_id}/routes/default
```

Required Permission: `router::update`

Remove the router's static default route(s). Idempotent — succeeds even when no default route is configured. Returns a
`JobResponse`.

### DNS Server Management

DNS providers are configured in the database (`dns_server` table) and referenced per IP range via
`forward_dns_server_id` / `reverse_dns_server_id` (see IP Range Management). This replaces the old static
`dns` block in `config.yaml`.

#### List DNS Servers

```
GET /api/admin/v1/dns_servers
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset

Required Permission: `dns_server::view`

Returns a paginated list of DNS servers. Each entry includes `id`, `name`, `enabled`, `kind`, `url`, and
`ip_range_count` (number of IP ranges referencing it for forward or reverse DNS). The `token` is never returned.

#### Get DNS Server Details

```
GET /api/admin/v1/dns_servers/{dns_server_id}
```

Required Permission: `dns_server::view`

#### List DNS Server Zones

```
GET /api/admin/v1/dns_servers/{dns_server_id}/zones
```

Required Permission: `dns_server::view`

Lists the DNS zones available on the given DNS server, for use when selecting a
forward/reverse zone id on an IP range. Providers without a zone concept return
an empty list (OVH reverse DNS is keyed per-IP block and exposes no zones).

Response:

```json
{
  "data": [
    {
      "id": "string",
      // Provider specific zone id (e.g. Cloudflare zone id)
      "name": "string"
      // Human readable zone name (e.g. example.com)
    }
  ]
}
```

#### Create DNS Server

```
POST /api/admin/v1/dns_servers
```

Required Permission: `dns_server::create`

Body:

```json
{
  "name": "string",
  // Required - Display name
  "enabled": boolean,
  // Optional - Default: true
  "kind": "cloudflare",
  // DnsServerKind enum: "cloudflare" (forward + reverse) or "ovh" (reverse only)
  "url": "string",
  // Optional - API base url (required for OVH, e.g. https://eu.api.ovh.com)
  "token": "string"
  // Required - Credential token. Cloudflare: bearer token.
  //            OVH: "application_key:application_secret:consumer_key"
}
```

#### Update DNS Server

```
PATCH /api/admin/v1/dns_servers/{dns_server_id}
```

Required Permission: `dns_server::update`

Body (all optional): `name`, `enabled`, `kind`, `url`, `token`.

#### Delete DNS Server

```
DELETE /api/admin/v1/dns_servers/{dns_server_id}
```

Required Permission: `dns_server::delete`

Note: DNS servers referenced by any IP range (forward or reverse) cannot be deleted. Remove the reference from all IP
ranges first.

### VM IP Assignment Management

VM IP assignments bind specific IP addresses from IP ranges to virtual machines. These endpoints provide comprehensive
management of these assignments.

#### List VM IP Assignments

```
GET /api/admin/v1/vm_ip_assignments
```

Query Parameters:

- `limit`: number (optional) - Items per page (max 100, default 50)
- `offset`: number (optional) - Pagination offset
- `vm_id`: number (optional) - Filter by VM ID
- `ip_range_id`: number (optional) - Filter by IP range ID
- `ip`: string (optional) - Filter by specific IP address
- `include_deleted`: boolean (optional) - Include soft-deleted assignments (default false)

Required Permission: `ip_range::view`

Returns paginated list of VM IP assignments with enriched data including user IDs, IP range CIDRs, region names, and all
relevant IDs (vm_id, ip_range_id, region_id, user_id) for easy cross-referencing.

**Automatic IP Assignment:** When creating IP assignments without specifying an IP address, the system uses the IP
range's allocation mode:

- **Sequential**: Assigns IPs in order, starting from the beginning of the range
- **Random**: Randomly selects available IPs from the range
- **SLAAC EUI-64**: Uses IPv6 Stateless Address Autoconfiguration with EUI-64 (IPv6 only)

#### Get VM IP Assignment Details

```
GET /api/admin/v1/vm_ip_assignments/{id}
```

Required Permission: `ip_range::view`

Returns detailed information about a specific VM IP assignment including IP range and region details, with all relevant
IDs for easy cross-referencing.

#### Create VM IP Assignment

```
POST /api/admin/v1/vm_ip_assignments
```

Required Permission: `virtual_machines::update`

Body:

```json
{
  "vm_id": number,
  // Required - VM ID to assign IP to
  "ip_range_id": number,
  // Required - IP range ID to assign from
  "ip": "string | null",
  // Optional - Specific IP to assign (if null, auto-assigns from range)
  "arp_ref": "string | null",
  // Optional - External ARP reference ID
  "dns_forward": "string | null",
  // Optional - Forward DNS FQDN
  "dns_reverse": "string | null"
  // Optional - Reverse DNS FQDN
}
```

Note: If `ip` is not provided, the system will automatically assign an available IP from the specified range using the
range's allocation mode (sequential, random, or SLAAC EUI-64). If `ip` is provided, it must be within the specified IP
range's CIDR and not already assigned to another VM.

**Asynchronous Processing:** This endpoint dispatches an `AssignVmIp` work job for distributed processing. The operation
returns immediately with a job ID. Use the job feedback pub/sub channels to monitor progress.

Response:

```json
{
  "data": {
    "job_dispatched": true,
    "job_id": "stream-id-12345"
  }
}
```

#### Update VM IP Assignment

```
PATCH /api/admin/v1/vm_ip_assignments/{id}
```

Required Permission: `virtual_machines::update`

Body (all optional):

```json
{
  "ip": "string",
  // New IP address (must be within the IP range)
  "arp_ref": "string | null",
  // ARP reference ID (null to clear)
  "dns_forward": "string | null",
  // Forward DNS FQDN (null to clear)
  "dns_reverse": "string | null"
  // Reverse DNS FQDN (null to clear)
}
```

**Asynchronous Processing:** This endpoint dispatches an `UpdateVmIp` work job for distributed processing. The operation
returns immediately with a job ID.

Response:

```json
{
  "data": {
    "job_dispatched": true,
    "job_id": "stream-id-12345"
  }
}
```

#### Delete VM IP Assignment

```
DELETE /api/admin/v1/vm_ip_assignments/{id}
```

Required Permission: `virtual_machines::update`

Soft-deletes the VM IP assignment, marking it as deleted rather than permanently removing it from the database.

Response:

```json
{
  "data": {
    "job_id": "stream-id-12345"
  }
}
```

**Asynchronous Processing:** This endpoint dispatches an `UnassignVmIp` work job for distributed processing. The
operation returns immediately with a job ID.

### Work Job Feedback System

Many admin endpoints now dispatch work jobs for asynchronous processing instead of blocking operations. This provides
better performance and scalability for resource-intensive operations.

#### Job Feedback Channels

Work jobs publish real-time feedback via Redis pub/sub channels:

**Specific job feedback:** `worker:feedback:{job_id}` - Monitor a specific job
**Global feedback:** `worker:feedback` - Monitor all job activity

#### Job Feedback Message Format

Job feedback messages use Rust enum serialization where the enum variant becomes the key. Here are the possible status
formats:

**Job Started:**

```json
{
  "job_id": "stream-id-12345",
  "job_type": "StartVm",
  "status": "Started",
  "timestamp": 1640995200,
  "metadata": {}
}
```

**Job Progress:**

```json
{
  "job_id": "stream-id-12345",
  "job_type": "StartVm",
  "status": {
    "Progress": {
      "percent": 50,
      "message": "Configuring network..."
    }
  },
  "timestamp": 1640995200,
  "metadata": {}
}
```

**Job Completed:**

```json
{
  "job_id": "stream-id-12345",
  "job_type": "StartVm",
  "status": {
    "Completed": {
      "result": "VM started successfully"
    }
  },
  "timestamp": 1640995200,
  "metadata": {}
}
```

**Job Failed:**

```json
{
  "job_id": "stream-id-12345",
  "job_type": "StartVm",
  "status": {
    "Failed": {
      "error": "VM failed to start: insufficient resources"
    }
  },
  "timestamp": 1640995200,
  "metadata": {}
}
```

**Job Cancelled:**

```json
{
  "job_id": "stream-id-12345",
  "job_type": "StartVm",
  "status": {
    "Cancelled": {
      "reason": "Admin cancelled operation"
    }
  },
  "timestamp": 1640995200,
  "metadata": {}
}
```

#### Job Status Types

- **Started** - Job has begun execution
- **Progress** - Job progress with percentage (0-100) and optional message
- **Completed** - Job completed successfully with optional result message
- **Failed** - Job failed with detailed error message
- **Cancelled** - Job was cancelled with optional reason

#### Work Job Types

The following admin operations are processed asynchronously via work jobs:

- **CreateVm** - Create a VM for a specific user (admin action)
- **StartVm** - Start a VM via the provisioner
- **StopVm** - Stop a VM via the provisioner
- **DeleteVm** - Delete a VM and clean up resources
- **ProcessVmRefund** - Process automated VM refunds
- **AssignVmIp** - Assign IP address to VM via provisioner
- **UnassignVmIp** - Remove IP assignment from VM via provisioner
- **UpdateVmIp** - Update VM IP assignment configuration
- **ConfigureVm** - Re-configure VM using current database settings
- **BulkMessage** - Send bulk messages to active customers

#### Monitoring Job Progress

To monitor job progress, subscribe to the appropriate Redis pub/sub channel:

```bash
# Monitor all job activity
redis-cli SUBSCRIBE worker:feedback

# Monitor specific job
redis-cli SUBSCRIBE worker:feedback:stream-id-12345
```

**Integration Notes:**

- All job feedback messages are JSON-encoded
- Jobs include unique worker IDs for tracking which worker processed the job
- Failed jobs include detailed error messages for debugging
- Completed jobs may include result data or success confirmations

#### WebSocket Endpoints

For real-time job monitoring via WebSocket connections:

##### Job Feedback WebSocket

```
GET /api/admin/v1/jobs/feedback?auth={auth_token}&job_id={job_id} (WebSocket)
```

Required Permission: Any admin role

**Query Parameters:**

- `auth`: Base64-encoded NIP-98 authentication token (required, since WebSocket headers aren't supported in browsers)
- `job_id`: Specific job ID to monitor (optional, omit for global monitoring)

Establishes a WebSocket connection that streams job feedback messages. When `job_id` is provided, only feedback for that
specific job is sent. When omitted, all job feedback is streamed.

**Message Types:**

All messages are structured with a `type` field for consistent handling:

- **Connected**:
  ```json
  {
    "type": "connected", 
    "message": "Job feedback stream connected"
  }
  ```
  Or for specific job:
  ```json
  {
    "type": "connected", 
    "message": "Connected to job {job_id} feedback stream"
  }
  ```

- **Pong Response**:
  ```json
  {"type": "pong"}
  ```

- **Error Messages**:
  ```json
  {
    "type": "error", 
    "error": "Error description"
  }
  ```

- **Job Feedback**:
  ```json
  {
    "type": "job_feedback",
    "feedback": {
      "job_id": "stream-id-12345",
      "worker_id": "worker-uuid",
      "job_type": "StartVm",
      "status": "Started",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
  ```

  Or for progress/completion:
  ```json
  {
    "type": "job_feedback", 
    "feedback": {
      "job_id": "stream-id-12345",
      "worker_id": "worker-uuid",
      "job_type": "CreateVm",
      "status": {
        "Completed": {
          "result": "VM 456 created successfully for user 123"
        }
      },
      "timestamp": "2024-01-15T10:35:00Z"
    }
  }
  ```

### Referral Program Management

All endpoints require the `referral` resource permissions. Responses never expose
NWC connection secrets (the NWC connection lives on the user's payment method).

#### List Referrals

```
GET /api/admin/v1/referrals
```

Required Permission: `referral::view`

Query Parameters:

- `limit`: number (optional, default 50, max 100)
- `offset`: number (optional, default 0)
- `search`: string (optional) - substring match on referral code, or a 64-char hex user pubkey

Returns a paginated list of `AdminReferralInfo`:

```json
{
  "data": [
    {
      "id": 12,
      "user_id": 34,
      "user_pubkey": "<hex>",
      "code": "ALPHA123",
      "lightning_address": "user@domain.com",
      "mode": "lightning_address",
      "referral_rate": 12.5,
      "created": "2026-07-18T10:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

`referral_rate` is the per-referrer commission override (whole %); `null` means the referred VM's `company.referral_rate` default applies.

#### Get Referral Detail

```
GET /api/admin/v1/referrals/{id}
```

Required Permission: `referral::view`

Returns the referral plus per-currency earned commission, payout history and counts:

```json
{
  "data": {
    "id": 12,
    "user_id": 34,
    "user_pubkey": "<hex>",
    "code": "ALPHA123",
    "lightning_address": "user@domain.com",
    "mode": "lightning_address",
    "referral_rate": 12.5,
    "created": "2026-07-18T10:00:00Z",
    "earned": [ { "currency": "BTC", "amount": 5000 } ],
    "payouts": [
      { "id": 1, "amount": 5000, "currency": "BTC", "created": "2026-07-18T11:00:00Z", "is_paid": true, "invoice": "lnbc...", "pre_image": "<hex>" }
    ],
    "referrals_success": 3,
    "referrals_failed": 1
  }
}
```

`earned` is commission (`first payment * effective_rate%`) aggregated per currency.

#### Update Referral (code / commission override)

```
PATCH /api/admin/v1/referrals/{id}
```

Required Permission: `referral::update`

Body:

```json
{
  "code": "OLDCODE1",
  // Rename the referral code, or omit to leave unchanged. Used to relink a
  // user's enrollment to a historical `vm.ref_code` that was tracked before
  // the user auto-generated their own code. Must be non-empty and not already
  // in use by another referral.
  "referral_rate": 12.5
  // Set (number, >= 0), clear to company default (null), or omit to leave unchanged
}
```

#### List Referral Payouts

```
GET /api/admin/v1/referrals/{id}/payouts
```

Required Permission: `referral::view`

Returns an array of payout records (`AdminReferralPayoutInfo`), most recent first.

#### Create Referral Payout

```
POST /api/admin/v1/referrals/{id}/payouts
```

Required Permission: `referral::create`

Creates a manual payout record (e.g. reconciling an out-of-band payment).

```json
{
  "amount": 5000,
  // Required - smallest currency unit, > 0
  "currency": "BTC",
  // Required
  "invoice": "lnbc...",
  // Optional - associated Lightning invoice
  "is_paid": false
  // Optional - mark already paid (default false)
}
```

#### Update / Reconcile Referral Payout

```
PATCH /api/admin/v1/referrals/{id}/payouts/{payout_id}
```

Required Permission: `referral::update`

```json
{
  "is_paid": true,
  // Optional - mark paid/unpaid
  "invoice": "lnbc...",
  // Optional - set (string) or clear (null) the invoice
  "pre_image": "<hex>"
  // Optional - set (hex, 32 bytes) or clear (null) the payment preimage
}
```

### Reports

#### Time Series Report

```
GET /api/admin/v1/reports/time-series
```

Query Parameters:

- `start_date`: string (required) - YYYY-MM-DD format
- `end_date`: string (required) - YYYY-MM-DD format
- `company_id`: number (required)
- `currency`: string (optional) - EUR, USD, GBP, CAD, CHF, AUD, JPY, BTC

Required Permission: `analytics::view`

Response:

```json
{
  "data": {
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "payments": [
      {
        "id": "a1b2c3d4e5f6...",
        "vm_id": 123,
        "created": "2025-01-15T10:30:45Z",
        "expires": "2025-02-15T10:30:45Z",
        "amount": 125000,
        "currency": "USD",
        "payment_method": "lightning",
        "external_id": "inv_12345",
        "is_paid": true,
        "rate": 1.0,
        "time_value": 2592000,
        "tax": 26250,
        "company_id": 1,
        "company_name": "Acme Corp",
        "company_base_currency": "USD",
        "user_id": 456,
        "host_id": 2,
        "host_name": "host-01",
        "region_id": 1,
        "region_name": "US East"
      }
    ]
  }
}
```

#### Referral Usage Time Series Report

```
GET /api/admin/v1/reports/referral-usage/time-series
```

Query Parameters:

- `start_date`: string (required) - YYYY-MM-DD format
- `end_date`: string (required) - YYYY-MM-DD format
- `company_id`: number (required)
- `ref_code`: string (optional)

Required Permission: `analytics::view`

Response:

```json
{
  "data": {
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "referrals": [
      {
        "vm_id": 123,
        "ref_code": "PROMO2025",
        "created": "2025-01-15T10:30:45Z",
        "amount": 125000,
        "currency": "USD",
        "rate": 1.0,
        "base_currency": "USD",
        "effective_rate": 10.0,
        "commission": 12500
      }
    ]
  }
}
```

`amount` is the referred VM's first payment; `effective_rate` is the applied commission % (the referrer's per-referrer override if set, else the referred VM's `company.referral_rate`); `commission = amount * effective_rate%` (floored), in `currency` smallest units.

#### Profit/Loss Report

```
GET /api/admin/v1/reports/profit-loss
```

Aggregates paid revenue against tracked resource costs (see *Resource Cost
Tracking*) into per-period profit/loss rows. **All amounts are converted into a
single target currency** (the company's base currency by default) using current
exchange rates, so each period yields one row. Recurring costs are normalized to
each calendar month they are active; `ip_range` per-IP costs are multiplied by
the range's current assigned-IP count; one-time (capital) costs are booked in
the period containing their `billing_start`.

Query Parameters:

- `start_date`: string (required) - YYYY-MM-DD
- `end_date`: string (required) - YYYY-MM-DD
- `group_by`: `month` (default) | `year`
- `company_id`: number (optional) - filter the revenue side to one company; `0`/omitted = all companies. Costs are global (not company-scoped) in this version.
- `region_id`: number (optional) - filter both revenue (payment's VM region) and costs (host / IP-range region); `0`/omitted = all regions.
- `currency`: string (optional) - target currency (e.g. `EUR`). Defaults to the selected company's base currency; **required when `company_id` is omitted**.

Required Permission: `analytics::view`

Response:

```json
{
  "data": {
    "start_date": "2026-01-01",
    "end_date": "2026-12-31",
    "group_by": "month",
    "currency": "EUR",
    "periods": [
      {
        "period": "2026-01",
        "revenue_net": 480000,
        "revenue_tax": 96000,
        "cost_recurring": 8000,
        "cost_one_time": 250000,
        "cost_total": 258000,
        "profit": 222000
      }
    ]
  }
}
```

**Notes:**

- **Revenue uses each payment's stored historical `rate`** to reconstruct its
  company-base-currency value (never live rates). A further base→report-currency
  step only applies when aggregating companies with different base currencies.
- **Costs** have no stored rate, so they are converted into the report `currency`
  using current exchange rates (BTC-pivoted).
- `profit = revenue_net - cost_total` and may be negative.
- Amounts are in smallest currency units (cents for fiat, millisats for BTC).
- Recurring-cost month normalization uses ~30.44 days/month for `day` intervals,
  the interval count directly for `month`, and ×12 for `year`.
- Payments/costs in a currency with no available exchange rate are skipped.

#### OSS (One-Stop Shop) VAT Report

```
GET /api/admin/v1/reports/oss
```

Aggregates cross-border EU B2C sales (`tax_treatment = oss_b2c`) by filing
period and destination member state, so the totals can be transcribed onto a
quarterly (or bi-monthly) OSS VAT return. Only **paid** payments are included.
Each row is keyed by `(period, company, destination country, VAT rate)` because
each seller company is a separate VAT-registered entity. Amounts are expressed
in each company's **base currency**, converted from the payment currency using
the exchange rate frozen on the payment at sale time.

Query Parameters:

- `start_date`: string (required) - YYYY-MM-DD
- `end_date`: string (required) - YYYY-MM-DD
- `company_id`: number (optional) - filter to one seller company; `0`/omitted = all companies.
- `period`: `quarter` (default, calendar Q1-Q4) | `bimonthly` (two-month buckets B1=Jan-Feb … B6=Nov-Dec).

Required Permission: `analytics::view`

Response:

```json
{
  "data": {
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "period": "quarter",
    "rows": [
      {
        "period": "2026-Q1",
        "company_id": 1,
        "company_name": "LNVPS",
        "currency": "EUR",
        "country_code": "DEU",
        "vat_rate": 19.0,
        "net_total": 210000,
        "tax_total": 39900,
        "transaction_count": 12
      }
    ]
  }
}
```

**Notes:**

- Only `oss_b2c` lines are counted; `domestic`, `reverse_charge` and
  `out_of_scope` sales are excluded (domestic sales belong on the national VAT
  return, not the OSS return).
- Uses each payment's frozen per-line `tax_breakdown` when present, else the
  payment's summary tax fields when the whole payment was treated as `oss_b2c`.
- `country_code` is the destination member state (ISO 3166-1 alpha-3).
- Amounts are in smallest currency units (cents for fiat, millisats for BTC).
- Payments whose currency cannot be converted to the company base currency are
  skipped.

## Error Responses

All error responses follow the format:

```json
{
  "error": string
  // Error message
}
```

Common HTTP status codes:

- `400` - Bad Request (invalid input / validation errors)
- `401` - Unauthorized (invalid or missing authentication)
- `403` - Forbidden (insufficient permissions; also protected/system resources)
- `404` - Not Found (missing resource, or a nested resource that doesn't belong to the parent in the path, e.g. a payment/history entry that isn't for the given VM)
- `409` - Conflict (the resource's current state conflicts with the request, e.g. acting on an already-deleted VM or an already-completed payment)
- `500` - Internal Server Error

## Pagination

Endpoints that return lists support pagination through the following query parameters:

- `limit` - Number of items to return (default varies by endpoint)
- `offset` - Number of items to skip (default: 0)

Example:

```
GET /api/admin/v1/users?limit=10&offset=20
```

## Search and Filtering

Some endpoints support additional query parameters for search and filtering:

- `search` - Search by user pubkey (hex format) for user endpoints
- `user_id` - Filter VMs by user ID
- `host_id` - Filter VMs by host ID
- Additional filters may be available for specific endpoints

Example:

```
GET /api/admin/v1/vms?user_id=123&limit=10
```

## Available Permissions

The RBAC system uses the following permission format: `resource::action`

### Resources:

- `users` - User management
- `virtual_machines` - VM management
- `hosts` - Host/server management
- `payments` - Payment and billing management
- `analytics` - Analytics and reporting
- `system` - System configuration
- `roles` - Role and permission management
- `audit` - Audit log access
- `access_policy` - Access policy management
- `company` - Company/organization management
- `ip_range` - IP address range management
- `router` - Network router configuration
- `dns_server` - DNS provider configuration
- `vm_custom_pricing` - Custom VM pricing models
- `host_region` - Host region configuration
- `vm_os_image` - VM operating system images
- `vm_payment` - VM-specific payment management
- `vm_template` - VM template management
- `subscriptions` - Subscription management
- `subscription_line_items` - Subscription line item management
- `subscription_payments` - Subscription payment management
- `payment_method_config` - Payment method configuration management

### Actions:

- `create` - Create new resources
- `view` - Read/view resources
- `update` - Modify existing resources
- `delete` - Delete resources

### Example Permissions:

- `users::view` - View user information
- `users::update` - Modify user accounts
- `virtual_machines::view` - View VM information
- `virtual_machines::delete` - Delete VMs
- `roles::create` - Create new roles
- `host_region::view` - View host regions
- `vm_template::create` - Create VM templates
- `ip_range::update` - Modify IP address ranges
- `vm_custom_pricing::delete` - Remove custom pricing models
- `company::view` - View company information
- `subscriptions::view` - View subscriptions
- `subscriptions::create` - Create new subscriptions
- `subscription_line_items::update` - Modify subscription line items
- `subscription_payments::view` - View subscription payments
- `payment_method_config::view` - View payment method configurations
- `payment_method_config::create` - Create payment method configurations

## Response Models

### AdminRefundAmountInfo

```json
{
  "amount": number,
  // Refund amount in smallest currency units (cents for fiat, milli-sats for BTC)
  "currency": "string",
  // Currency code (USD, EUR, BTC, etc.)
  "rate": number,
  // Exchange rate used for calculation
  "expires": "string",
  // VM expiry date (ISO 8601)
  "seconds_remaining": number
  // Seconds until VM expires
}
```

### AdminUserInfo

```json
{
  "id": number,
  "pubkey": "string (hex)",
  "created": "string (ISO 8601)",
  "email": "string | null",
  "contact_nip17": boolean,
  "contact_email": boolean,
  "country_code": "string | null",
  "billing_name": "string | null",
  "billing_address_1": "string | null",
  "billing_address_2": "string | null",
  "billing_city": "string | null",
  "billing_state": "string | null",
  "billing_postcode": "string | null",
  "billing_tax_id": "string | null",
  "geo_country_code": "string | null",
  // ISO 3166-1 alpha-3 country resolved from the client IP (independent VAT place-of-supply evidence)
  "geo_ip": "string | null",
  // Last client IP geolocation was resolved from
  "geo_updated": "string (ISO 8601) | null",
  // When the geolocation was last resolved (auto-updated on admin edit)
  "vm_count": number,
  "last_login": "string (ISO 8601) | null",
  "is_admin": boolean,
  "email_verified": boolean,
  // Whether the user's email address has been verified
  "has_nwc": boolean
  // Whether the user has a Nostr Wallet Connect connection string configured
}
```

### AdminVmInfo

```json
{
  "id": number,
  // VM ID
  "created": "string (ISO 8601)",
  "expires": "string (ISO 8601) | null",
  // null for VMs not yet paid
  "mac_address": "string",
  "image_id": number,
  // OS image ID for linking
  "image_name": "string",
  // OS distribution, version and flavor (e.g., "Ubuntu 22.04 Server")
  "template_id": number,
  // Template ID for linking (standard templates)
  "template_name": "string",
  // Template name - shows "Custom - {pricing_name}" for custom templates
  "custom_template_id": number
  |
  null,
  // Custom template ID if using custom template
  "is_standard_template": boolean,
  // True for standard templates, false for custom templates
  "ssh_key_id": number,
  // SSH key ID for linking
  "ssh_key_name": "string",
  // Simplified: SSH key name only
  "ip_addresses": [
    // Array of IP address objects with IDs for linking
    {
      "id": number,
      // IP assignment ID for linking
      "ip": "string",
      // IP address
      "range_id": number
      // IP range ID for linking to range details
    }
  ],
  "running_state": {
    // Full VM running state with metrics (null if unavailable)
    "timestamp": number,
    // Unix timestamp of when state was collected
    "state": "running",
    // VmRunningStates enum: "unknown", "running", "stopped", "creating"
    "cpu_usage": number,
    // Current CPU usage percentage (0.0-100.0)
    "mem_usage": number,
    // Current memory usage percentage (0.0-100.0)
    "uptime": number,
    // VM uptime in seconds
    "net_in": number,
    // Network bytes received
    "net_out": number,
    // Network bytes transmitted
    "disk_write": number,
    // Disk bytes written
    "disk_read": number
    // Disk bytes read
  }
  |
  null,
  "auto_renewal_enabled": boolean,
  // Whether automatic renewal via NWC is enabled
  "cpu": number,
  // Number of CPU cores allocated
  "cpu_mfg": "string | null",
  // CPU manufacturer (e.g. "intel", "amd", "apple") - omitted if unknown
  "cpu_arch": "string | null",
  // CPU architecture (e.g. "x86_64", "arm64") - omitted if unknown
  "cpu_features": ["string"],
  // CPU features (e.g. ["AVX2", "AES", "VMX"]) - omitted if empty
  "memory": number,
  // Memory in bytes allocated
  "disk_size": number,
  // Disk size in bytes
  "disk_type": "ssd",
  // DiskType enum: "hdd" or "ssd"
  "disk_interface": "pcie",
  // DiskInterface enum: "sata", "scsi", or "pcie"
  "host_id": number,
  "user_id": number,
  "user_pubkey": "string (hex)",
  "user_email": "string | null",
  "host_name": "string",
  "region_id": number,
  "region_name": "string",
  "deleted": boolean,
  "disabled": boolean,
  // Whether the VM has been administratively disabled
  "ref_code": "string | null",
  "subscription": {
    // Full AdminSubscriptionInfo — present when the VM has a linked subscription
    "id": number,
    "name": "string",
    "is_active": boolean,
    "auto_renewal_enabled": boolean,
    "interval_amount": number,
    "interval_type": "day" | "month" | "year",
    "currency": "string",
    "payment_count": number,
    "line_items": [
      {
        "id": number,
        "name": "string",
        "description": "string | null",
        "amount": number,
        // recurring cost in cents/millisats
        "setup_amount": number
        // one-time setup fee in cents/millisats
      }
    ]
  }
  | null
  // null/omitted when no subscription is linked
}
```

### AdminRoleInfo

```json
{
  "id": number,
  "name": "string",
  "description": "string | null",
  "is_system_role": boolean,
  "permissions": [
    "string"
  ],
  "user_count": number,
  "created_at": "string (ISO 8601)",
  "updated_at": "string (ISO 8601)"
}
```

### UserRoleInfo

```json
{
  "role": {
    "id": number,
    "name": "string",
    "description": "string | null",
    "is_system_role": boolean,
    "permissions": [
      "string"
    ],
    "user_count": number,
    "created_at": "string (ISO 8601)",
    "updated_at": "string (ISO 8601)"
  },
  "assigned_by": "number | null",
  "assigned_at": "string (ISO 8601)",
  "expires_at": "string (ISO 8601) | null"
}
```

### AdminHostInfo

```json
{
  "id": number,
  "name": "string",
  "kind": "proxmox",
  // VmHostKind enum: "proxmox", "libvirt"
  "region": {
    "id": number,
    "name": "string",
    "enabled": boolean
  },
  "ip": "string",
  "cpu": number,
  "cpu_mfg": "string | null",
  // CPU manufacturer (e.g. "intel", "amd", "apple") - omitted if unknown
  "cpu_arch": "string | null",
  // CPU architecture (e.g. "x86_64", "arm64") - omitted if unknown
  "cpu_features": ["string"],
  // CPU features (e.g. ["AVX2", "AES", "VMX"]) - omitted if empty
  "memory": number,
  "enabled": boolean,
  "load_cpu": number,
  "load_memory": number,
  "load_disk": number,
  "vlan_id": "number | null",
  "mtu": "number | null",
  // MTU setting for network configuration (null if not set)
  "disks": [
    {
      "id": number,
      "name": "string",
      "size": number,
      "kind": "ssd",
      // DiskType enum: "hdd", "ssd"
      "interface": "pcie",
      // DiskInterface enum: "sata", "scsi", "pcie"
      "enabled": boolean
    }
  ],
  "calculated_load": {
    "overall_load": number,
    // Overall load percentage (0.0-1.0)
    "cpu_load": number,
    // CPU load percentage (0.0-1.0)
    "memory_load": number,
    // Memory load percentage (0.0-1.0)
    "disk_load": number,
    // Disk load percentage (0.0-1.0)
    "available_cpu": number,
    // Available CPU cores
    "available_memory": number,
    // Available memory in bytes
    "active_vms": number
    // Number of active VMs on this host
  },
  "ssh_user": "string | null",
  // SSH username for host utilities (null if not configured)
  "ssh_key_configured": boolean
  // Whether SSH key is configured (key itself is not exposed)
}
```

### AdminRegionInfo

```json
{
  "id": number,
  "name": "string",
  "enabled": boolean,
  "company_id": number,
  // Company that owns this region
  "host_count": number,
  "total_vms": number,
  // Count of active (non-deleted) VMs only
  "total_cpu_cores": number,
  "total_memory_bytes": number,
  // Total memory in bytes (not GB)
  "total_ip_assignments": number
  // IP assignments from active VMs only
}
```

### RegionDeleteResponse

```json
{
  "success": boolean,
  "message": "string"
}
```

### AdminHostDisk

```json
{
  "id": number,
  "name": "string",
  "size": number,
  "kind": "string",
  "interface": "string",
  "enabled": boolean
}
```

### AdminVmHistoryInfo

```json
{
  "id": number,
  "vm_id": number,
  "action_type": "started",
  // AdminVmHistoryActionType enum: "created", "started", "stopped", etc.
  "timestamp": "string (ISO 8601)",
  // When this action occurred
  "initiated_by_user": number
  |
  null,
  // User ID who initiated this action (if applicable)
  "initiated_by_user_pubkey": "string | null",
  // Hex-encoded pubkey of initiating user
  "initiated_by_user_email": "string | null",
  // Email of initiating user
  "description": "string | null"
  // Human-readable description of the action
}
```

### AdminVmPaymentInfo

```json
{
  "id": "string",
  // Hex-encoded payment ID
  "vm_id": number,
  "created": "string (ISO 8601)",
  // When payment was created
  "expires": "string (ISO 8601)",
  // When payment expires
  "amount": number,
  // Amount in smallest currency unit (satoshis, cents)
  "tax": number,
  // Tax amount in smallest currency unit
  "processing_fee": number,
  // Processing fee in smallest currency unit
  "currency": "string",
  // Currency code (e.g., "EUR", "USD", "BTC")
  "company_base_currency": "string",
  // Base currency of the company that owns this VM (e.g., "EUR")
  "payment_method": "lightning",
  // AdminPaymentMethod enum: "lightning", "revolut", "paypal", "stripe"
  "external_id": "string | null",
  // External payment provider ID
  "is_paid": boolean,
  // Whether payment has been completed
  "paid_at": "string (ISO 8601) | null",
  // When payment was completed (null if unpaid)
  "rate": number
  // Exchange rate to company_base_currency
}
```

### AdminSubscriptionInfo

```json
{
  "id": number,
  "user_id": number,
  "name": "string",
  "description": "string | null",
  "created": "string (ISO 8601)",
  "expires": "string (ISO 8601) | null",
  "is_active": boolean,
  "is_setup": boolean,
  // Whether the subscription has been fully set up (resources allocated)
  "currency": "string",
  // "USD", "EUR", "BTC", "GBP", "CAD", "CHF", "AUD", "JPY"
  "interval_amount": number,
  // Billing cycle multiplier (e.g., 1, 3, 12)
  "interval_type": "day"
  |
  "month"
  |
  "year",
  "setup_fee": number,
  // One-time setup fee in cents/millisats
  "auto_renewal_enabled": boolean,
  "external_id": "string | null",
  // External payment processor ID (Stripe, PayPal, etc.)
  "line_items": [
    // All services included in this subscription
    {
      "id": number,
      "subscription_id": number,
      "name": "string",
      "description": "string | null",
      "amount": number,
      // Recurring cost per billing cycle in cents/millisats
      "setup_amount": number,
      // One-time setup fee in cents/millisats
      "configuration": object
      // Service-specific JSON configuration
    }
  ],
  "payment_count": number
  // Total number of payments for this subscription
}
```

### AdminSubscriptionLineItemInfo

```json
{
  "id": number,
  "subscription_id": number,
  "name": "string",
  "description": "string | null",
  "amount": number,
  // Recurring cost per billing cycle in cents/millisats
  "setup_amount": number,
  // One-time setup fee in cents/millisats
  "configuration": object
  |
  null
  // Service-specific JSON configuration
}
```

### AdminSubscriptionPaymentInfo

```json
{
  "id": "string",
  // Hex-encoded payment ID
  "subscription_id": number,
  "user_id": number,
  "created": "string (ISO 8601)",
  "expires": "string (ISO 8601) | null",
  "amount": number,
  // Total amount in cents/millisats
  "currency": "string",
  // "USD", "EUR", "BTC", etc.
  "company_base_currency": "string",
  // Base currency of the company that owns the subscription (e.g., "EUR")
  "payment_method": "lightning"
  |
  "revolut"
  |
  "paypal"
  |
  "stripe",
  "payment_type": "purchase"
  |
  "renewal"
  |
  "upgrade",
  // SubscriptionPaymentType enum
  "external_id": "string | null",
  // External payment processor ID
  "is_paid": boolean,
  "paid_at": "string (ISO 8601) | null",
  // When payment was completed (null if unpaid)
  "rate": number,
  // Exchange rate to company_base_currency
  "time_value": number
  |
  null,
  // Seconds added to expiry when this payment is completed (omitted if not applicable)
  "metadata": object
  |
  null,
  // Service-specific JSON metadata (omitted if none)
  "tax": number,
  // Tax amount in cents/millisats
  "processing_fee": number
  // Processing fee in cents/millisats
}
```

### AdminVmOsImageInfo

```json
{
  "id": number,
  "distribution": "debian",
  // ApiOsDistribution enum: "ubuntu", "debian", "centos", "fedora", "freebsd", "opensuse", "archlinux", "redhatenterprise"
  "flavour": "string",
  "version": "string",
  "enabled": boolean,
  "release_date": "string (ISO 8601)",
  "url": "string",
  "default_username": "string | null",
  "active_vm_count": number,
  // Number of active (non-deleted) VMs using this image
  "sha2": "string | null",
  // SHA-256 checksum of the image file (omitted if not set)
  "sha2_url": "string | null"
  // URL to a file containing the SHA-256 checksum (omitted if not set)
}
```

### AdminVmTemplateInfo

```json
{
  "id": number,
  "name": "string",
  "enabled": boolean,
  "created": "string (ISO 8601)",
  "expires": "string (ISO 8601) | null",
  "cpu": number,
  "cpu_mfg": "string | null",
  // CPU manufacturer (e.g. "intel", "amd", "apple") - omitted if unknown
  "cpu_arch": "string | null",
  // CPU architecture (e.g. "x86_64", "arm64") - omitted if unknown
  "cpu_features": ["string"],
  // CPU features (e.g. ["AVX2", "AES", "VMX"]) - omitted if empty
  "memory": number,
  "disk_size": number,
  "disk_type": "ssd",
  // DiskType enum: "hdd" or "ssd"
  "disk_interface": "pcie",
  // DiskInterface enum: "sata", "scsi", or "pcie"
  "cost_plan_id": number,
  "region_id": number,
  "region_name": "string | null",
  // Populated with region name
  "cost_plan_name": "string | null",
  // Populated with cost plan name
  "active_vm_count": number,
  // Number of active (non-deleted) VMs using this template
  "disk_iops_read": number | null,
  // Maximum disk read IOPS — omitted if uncapped
  "disk_iops_write": number | null,
  // Maximum disk write IOPS — omitted if uncapped
  "disk_mbps_read": number | null,
  // Maximum disk read throughput in MB/s — omitted if uncapped
  "disk_mbps_write": number | null,
  // Maximum disk write throughput in MB/s — omitted if uncapped
  "network_mbps": number | null,
  // Maximum network bandwidth in Mbit/s — omitted if uncapped
  "cpu_limit": number | null
  // Maximum CPU usage as a fraction of allocated cores (e.g. 0.5 = 50%) — omitted if uncapped
}
```

### AdminCustomPricingInfo

```json
{
  "id": number,
  "name": "string",
  "enabled": boolean,
  "created": "string (ISO 8601)",
  "expires": "string (ISO 8601) | null",
  "region_id": number,
  "region_name": "string | null",
  // Populated with region name
  "currency": "string",
  // e.g., "USD", "EUR", "BTC"
  "cpu_mfg": "string | null",
  // CPU manufacturer (e.g. "intel", "amd", "apple") - omitted if unknown
  "cpu_arch": "string | null",
  // CPU architecture (e.g. "x86_64", "arm64") - omitted if unknown
  "cpu_features": ["string"],
  // CPU features (e.g. ["AVX2", "AES", "VMX"]) - omitted if empty
  "cpu_cost": number,
  // Cost per CPU core per month
  "memory_cost": number,
  // Cost per GB RAM per month
  "ip4_cost": number,
  // Cost per IPv4 address per month
  "ip6_cost": number,
  // Cost per IPv6 address per month
  "min_cpu": number,
  // Minimum CPU cores allowed
  "max_cpu": number,
  // Maximum CPU cores allowed
  "min_memory": number,
  // Minimum memory in bytes
  "max_memory": number,
  // Maximum memory in bytes
  "disk_iops_read": number,
  // Maximum disk read IOPS - omitted when uncapped
  "disk_iops_write": number,
  // Maximum disk write IOPS - omitted when uncapped
  "disk_mbps_read": number,
  // Maximum disk read throughput in MB/s - omitted when uncapped
  "disk_mbps_write": number,
  // Maximum disk write throughput in MB/s - omitted when uncapped
  "network_mbps": number,
  // Maximum network bandwidth in Mbit/s - omitted when uncapped
  "cpu_limit": number,
  // Maximum CPU usage as a fraction of allocated cores e.g. 0.5 = 50% - omitted when uncapped
  "disk_pricing": [
    // Array of disk pricing configurations
    {
      "id": number,
      "kind": "ssd",
      // DiskType enum: "hdd" or "ssd"
      "interface": "pcie",
      // DiskInterface enum: "sata", "scsi", or "pcie"
      "cost": number,
      // Cost per GB per month
      "min_disk_size": number,
      // Minimum disk size in bytes for this type/interface
      "max_disk_size": number
      // Maximum disk size in bytes for this type/interface
    }
  ],
  "template_count": number
  // Number of custom templates using this pricing
}
```

### AdminCustomTemplateInfo

```json
{
  "id": number,
  "cpu": number,
  // Number of CPU cores
  "memory": number,
  // Memory in bytes
  "disk_size": number,
  // Disk size in bytes
  "disk_type": "ssd",
  // Enum: "hdd" or "ssd"
  "disk_interface": "pcie",
  // Enum: "sata", "scsi", or "pcie"
  "pricing_id": number,
  "pricing_name": "string | null",
  // Populated with pricing model name
  "region_id": number,
  // From associated pricing model
  "region_name": "string | null",
  // From associated pricing model
  "currency": "string",
  // From associated pricing model
  "calculated_cost": {
    // Calculated monthly cost breakdown
    "cpu_cost": number,
    "memory_cost": number,
    "disk_cost": number,
    "ip4_cost": number,
    // Based on default 1 IPv4
    "ip6_cost": number,
    // Based on default 1 IPv6
    "total_monthly_cost": number
  },
  "vm_count": number
  // Number of VMs using this template
}
```

### AdminCompanyInfo

```json
{
  "id": number,
  "created": "string (ISO 8601)",
  "name": "string",
  "address_1": "string | null",
  "address_2": "string | null",
  "city": "string | null",
  "state": "string | null",
  "country_code": "string | null",
  "tax_id": "string | null",
  "base_currency": "string",
  // Company's base currency (EUR, USD, GBP, CAD, CHF, AUD, JPY, BTC)
  "postcode": "string | null",
  "phone": "string | null",
  "email": "string | null",
  "region_count": number
  // Number of regions assigned to this company
}
```

### AdminIpRangeInfo

```json
{
  "id": number,
  "cidr": "string",
  // CIDR notation (e.g., "192.168.1.0/24")
  "gateway": "string",
  // Gateway IP address
  "enabled": boolean,
  "region_id": number,
  "region_name": "string | null",
  // Populated with region name
  "reverse_zone_id": "string | null",
  // DNS reverse zone ID
  "access_policy_id": "number | null",
  "access_policy_name": "string | null",
  // Populated with access policy name
  "allocation_mode": "sequential",
  // IpRangeAllocationMode enum: "random", "sequential", or "slaac_eui64"
  "use_full_range": boolean,
  // Whether to use first and last IPs in range
  "assignment_count": number,
  // Number of active IP assignments in this range
  "available_ips": "number | null"
  // Number of available IPs (IPv4 only, null for IPv6)
}
```

### AdminAccessPolicyInfo

```json
{
  "id": number,
  "name": "string",
  "kind": "static_arp",
  // NetworkAccessPolicyKind enum: "static_arp" 
  "router_id": "number | null",
  // Router ID for policy application
  "interface": "string | null"
  // Interface name for policy application
}
```

### AdminAccessPolicyDetail

```json
{
  "id": number,
  "name": "string",
  "kind": "static_arp",
  // NetworkAccessPolicyKind enum: "static_arp"
  "router_id": "number | null",
  // Router ID for policy application
  "router_name": "string | null",
  // Populated with router name
  "interface": "string | null",
  // Interface name for policy application
  "ip_range_count": number
  // Number of IP ranges using this policy
}
```

### AdminRouterInfo

Embedded summary returned when a router is referenced inside another object (e.g. inside `AdminAccessPolicyDetail`).

```json
{
  "id": number,
  "name": "string",
  "enabled": boolean,
  "kind": "mikrotik",
  // RouterKind enum: "mikrotik" or "ovh_additional_ip"
  "url": "string"
  // Router API URL
}
```

### AdminRouterDetail

Full detail returned by `GET /api/admin/v1/routers/{id}`.

```json
{
  "id": number,
  "name": "string",
  "enabled": boolean,
  "kind": "ovh_additional_ip",
  // RouterKind enum: "mikrotik" or "ovh_additional_ip"
  "url": "string",
  // Router API URL
  "access_policy_count": number
  // Number of access policies using this router
}
```

### CustomPricingCalculation

```json
{
  "currency": "string",
  "cpu_cost": number,
  // Cost for specified CPU cores
  "memory_cost": number,
  // Cost for specified memory
  "disk_cost": number,
  // Cost for specified disk size
  "ip4_cost": number,
  // Cost for specified IPv4 addresses
  "ip6_cost": number,
  // Cost for specified IPv6 addresses
  "total_monthly_cost": number,
  // Sum of all costs
  "configuration": {
    // Echo of input configuration
    "cpu": number,
    "memory": number,
    "disk_size": number,
    "disk_type": "string",
    "disk_interface": "string",
    "ip4_count": number,
    "ip6_count": number
  }
}
```

### AdminCostPlanInfo

```json
{
  "id": number,
  "name": "string",
  "created": "string (ISO 8601)",
  "amount": number,
  // Cost amount
  "currency": "string",
  // Currency code (e.g., "USD", "EUR")
  "interval_amount": number,
  // Billing interval count
  "interval_type": "day"
  |
  "month"
  |
  "year",
  // Billing interval type
  "template_count": number
  // Number of VM templates using this cost plan
}
```

### ReferralReport

```json
{
  "vm_id": number,
  "ref_code": "string",
  "created": "string (ISO 8601)",
  "amount": number,
  "currency": "string",
  "rate": number,
  "base_currency": "string"
}
```

### ReferralTimeSeriesReport

```json
{
  "start_date": "string",
  "end_date": "string",
  "referrals": [
    "ReferralReport"
  ]
}
```

### TimeSeriesPayment

```json
{
  "id": "string",
  // Hex-encoded payment ID
  "vm_id": number,
  "created": "string (ISO 8601)",
  "expires": "string (ISO 8601)",
  "amount": number,
  // Amount in smallest currency unit
  "currency": "string",
  "payment_method": "string",
  "external_id": "string | null",
  "is_paid": boolean,
  "rate": number,
  // Exchange rate to company's base currency
  "time_value": number,
  // Seconds this payment adds to VM expiry
  "tax": number,
  // Tax amount in smallest currency unit
  "company_id": number,
  "company_name": "string",
  "company_base_currency": "string"
}
```

### TimeSeriesReport

```json
{
  "start_date": "string",
  "end_date": "string",
  "payments": [
    "TimeSeriesPayment"
  ]
}
```

### AdminVmIpAddress

```json
{
  "id": number,
  // IP assignment ID for linking
  "ip": "string",
  // IP address
  "range_id": number
  // IP range ID for linking to range details
}
```

### CalculatedHostLoad

```json
{
  "overall_load": number,
  // Overall load percentage (0.0-1.0)
  "cpu_load": number,
  // CPU load percentage (0.0-1.0)
  "memory_load": number,
  // Memory load percentage (0.0-1.0)
  "disk_load": number,
  // Disk load percentage (0.0-1.0)
  "available_cpu": number,
  // Available CPU cores
  "available_memory": number,
  // Available memory in bytes
  "active_vms": number
  // Number of active VMs on this host
}
```

### AdminHostRegion

```json
{
  "id": number,
  "name": "string",
  "enabled": boolean
}
```

### AdminCustomPricingDisk

```json
{
  "id": number,
  "kind": "ssd",
  // DiskType enum: "hdd" or "ssd"
  "interface": "pcie",
  // DiskInterface enum: "sata", "scsi", or "pcie"
  "cost": number,
  "min_disk_size": number,
  // Minimum disk size in bytes for this type/interface
  "max_disk_size": number
  // Maximum disk size in bytes for this type/interface
}
```

### AdminVmIpAssignmentInfo

```json
{
  "id": number,
  // Assignment ID
  "vm_id": number,
  // VM ID this IP is assigned to
  "ip_range_id": number,
  // IP range ID this IP belongs to
  "region_id": number,
  // Region ID containing the IP range
  "user_id": number,
  // User ID who owns the VM
  "ip": "string",
  // The assigned IP address (IPv4 or IPv6)
  "deleted": boolean,
  // Whether this assignment is soft-deleted
  "arp_ref": "string | null",
  // External ARP reference ID
  "dns_forward": "string | null",
  // Forward DNS FQDN
  "dns_forward_ref": "string | null",
  // External reference for forward DNS entry
  "dns_reverse": "string | null",
  // Reverse DNS FQDN
  "dns_reverse_ref": "string | null",
  // External reference for reverse DNS entry
  "ip_range_cidr": "string | null",
  // CIDR notation of the IP range
  "region_name": "string | null"
  // Name of the region containing the IP range
}
```

### CustomPricingCalculation

```json
{
  "currency": "string",
  "cpu_cost": number,
  // Cost for specified CPU cores
  "memory_cost": number,
  // Cost for specified memory
  "disk_cost": number,
  // Cost for specified disk size
  "ip4_cost": number,
  // Cost for specified IPv4 addresses
  "ip6_cost": number,
  // Cost for specified IPv6 addresses
  "total_monthly_cost": number,
  // Sum of all costs
  "configuration": {
    // Echo of input configuration
    "cpu": number,
    "memory": number,
    "disk_size": number,
    "disk_type": "string",
    "disk_interface": "string",
    "ip4_count": number,
    "ip6_count": number
  }
}
```

---

## IP Space Management

### List IP Spaces

```
GET /api/admin/v1/ip_space
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `is_available`: boolean (optional) - filter by availability
- `registry`: number (optional) - 0=ARIN, 1=RIPE, 2=APNIC, 3=LACNIC, 4=AFRINIC

Required Permission: `ip_space::view`

Response: Paginated list of `AdminAvailableIpSpaceInfo`

### Get IP Space

```
GET /api/admin/v1/ip_space/{id}
```

Required Permission: `ip_space::view`

Response: Single `AdminAvailableIpSpaceInfo`

### Create IP Space

```
POST /api/admin/v1/ip_space
```

Request Body: `CreateAvailableIpSpaceRequest`

Required Permission: `ip_space::create`

Response: Created `AdminAvailableIpSpaceInfo`

### Update IP Space

```
PATCH /api/admin/v1/ip_space/{id}
```

Request Body: `UpdateAvailableIpSpaceRequest`

Required Permission: `ip_space::update`

Response: Updated `AdminAvailableIpSpaceInfo`

### Delete IP Space

```
DELETE /api/admin/v1/ip_space/{id}
```

Required Permission: `ip_space::delete`

Response: Empty success response

Error: `"Cannot delete IP space with active subscriptions. Please cancel subscriptions first."` if active subscriptions
exist

### List IP Space Pricing

```
GET /api/admin/v1/ip_space/{id}/pricing
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0

Required Permission: `ip_space::view`

Response: Paginated list of `AdminIpSpacePricingInfo`

### Get IP Space Pricing

```
GET /api/admin/v1/ip_space/{space_id}/pricing/{pricing_id}
```

Required Permission: `ip_space::view`

Response: Single `AdminIpSpacePricingInfo`

### Create IP Space Pricing

```
POST /api/admin/v1/ip_space/{id}/pricing
```

Request Body: `CreateIpSpacePricingRequest`

Required Permission: `ip_space::create`

Response: Created `AdminIpSpacePricingInfo`

Errors:

- `"Prefix size must be between {min} and {max}"` - prefix_size outside space bounds
- `"Pricing already exists for prefix size /{size}"` - duplicate pricing

### Update IP Space Pricing

```
PATCH /api/admin/v1/ip_space/{space_id}/pricing/{pricing_id}
```

Request Body: `UpdateIpSpacePricingRequest`

Required Permission: `ip_space::update`

Response: Updated `AdminIpSpacePricingInfo`

Errors:

- `"Pricing does not belong to the specified IP space"` - mismatched IDs
- `"Prefix size must be between {min} and {max}"` - prefix_size outside space bounds
- `"Pricing already exists for prefix size /{size}"` - duplicate pricing

### Delete IP Space Pricing

```
DELETE /api/admin/v1/ip_space/{space_id}/pricing/{pricing_id}
```

Required Permission: `ip_space::delete`

Response: Empty success response

### List IP Space Subscriptions

```
GET /api/admin/v1/ip_space/{id}/subscriptions
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `user_id`: number (optional) - filter by user
- `is_active`: boolean (optional) - filter by active status

Required Permission: `subscriptions::view`

Response: Paginated list of `AdminIpRangeSubscriptionInfo`

---

## IP Space Data Types

### AdminAvailableIpSpaceInfo

```json
{
  "id": number,
  "company_id": number,
  // Company that owns this IP space block
  "cidr": "string",
  // e.g., "192.168.0.0/22"
  "min_prefix_size": number,
  // e.g., 24 (smallest allocation /24)
  "max_prefix_size": number,
  // e.g., 22 (largest allocation /22)
  "registry": {
    "value": number,
    // 0=ARIN, 1=RIPE, 2=APNIC, 3=LACNIC, 4=AFRINIC
    "name": "string"
    // "ARIN", "RIPE", etc.
  },
  "external_id": "string | null",
  // RIR allocation ID (e.g., "NET-192-168-0-0-1")
  "is_available": boolean,
  // Whether space is available for allocation
  "is_reserved": boolean,
  // Whether space is reserved for special use
  "metadata": object
  |
  null,
  // JSON metadata (routing requirements, upstream provider, etc.)
  "pricing_count": number
  // Number of pricing tiers configured
}
```

### CreateAvailableIpSpaceRequest

```json
{
  "cidr": "string",
  // CIDR notation (validated)
  "min_prefix_size": number,
  // Must be >= max_prefix_size (larger number = smaller block)
  "max_prefix_size": number,
  // Must be <= min_prefix_size (smaller number = larger block)
  "registry": number,
  // 0=ARIN, 1=RIPE, 2=APNIC, 3=LACNIC, 4=AFRINIC
  "external_id": "string | null",
  // Optional RIR allocation ID
  "is_available": boolean,
  // Optional, default: true
  "is_reserved": boolean,
  // Optional, default: false
  "metadata": object
  |
  null
  // Optional JSON metadata
}
```

### UpdateAvailableIpSpaceRequest

```json
{
  "cidr": "string | null",
  // Optional CIDR update (validated)
  "min_prefix_size": number
  |
  null,
  // Optional, must be >= max_prefix_size
  "max_prefix_size": number
  |
  null,
  // Optional, must be <= min_prefix_size
  "registry": number
  |
  null,
  // Optional registry update
  "external_id": "string | null",
  // Optional, null to clear
  "is_available": boolean
  |
  null,
  // Optional availability update
  "is_reserved": boolean
  |
  null,
  // Optional reserved status update
  "metadata": object
  |
  null
  // Optional, null to clear
}
```

### AdminIpSpacePricingInfo

```json
{
  "id": number,
  "available_ip_space_id": number,
  // Parent IP space ID
  "prefix_size": number,
  // e.g., 24 for /24 subnet
  "price_per_month": number,
  // Monthly recurring price in cents/millisats
  "currency": "string",
  // e.g., "USD", "EUR", "BTC"
  "setup_fee": number,
  // One-time setup fee in cents/millisats
  "cidr": "string | null"
  // Parent CIDR for context (populated by API)
}
```

### CreateIpSpacePricingRequest

```json
{
  "prefix_size": number,
  // Must be within space's min/max bounds
  "price_per_month": number,
  // In cents/millisats (cannot be negative)
  "currency": "string | null",
  // Optional, default: "USD"
  "setup_fee": number
  |
  null
  // Optional, default: 0
}
```

### UpdateIpSpacePricingRequest

```json
{
  "prefix_size": number
  |
  null,
  // Optional, must be within space's min/max bounds
  "price_per_month": number
  |
  null,
  // Optional (cannot be negative)
  "currency": "string | null",
  // Optional currency update
  "setup_fee": number
  |
  null
  // Optional (cannot be negative)
}
```

### AdminIpRangeSubscriptionInfo

```json
{
  "id": number,
  "subscription_line_item_id": number,
  // Links to subscription line item
  "available_ip_space_id": number,
  // IP space this was allocated from
  "cidr": "string",
  // Allocated CIDR e.g., "192.168.1.0/24"
  "is_active": boolean,
  // Whether subscription is active
  "started_at": "string",
  // ISO 8601 datetime
  "ended_at": "string | null",
  // ISO 8601 datetime or null if active
  "metadata": object
  |
  null,
  // JSON metadata (routing info, ASN assignments, etc.)
  "subscription_id": number
  |
  null,
  // Subscription ID (enriched)
  "user_id": number
  |
  null,
  // User ID (enriched)
  "parent_cidr": "string | null"
  // Parent IP space CIDR (enriched)
}
```

---

## Payment Method Configuration Management

Payment method configurations store provider settings for payment processing (Lightning/LND, Revolut, Stripe, PayPal).
This allows payment provider settings to be managed in the database instead of static configuration files.

> **Note:** Bitvora support has been removed as the service has been shut down.

Each configuration belongs to a specific company, and multiple configurations can exist per company/payment method
combination. This allows keeping disabled legacy configurations that are still referenced by historical payments while
having newer active configurations.

### List Payment Method Configurations

```
GET /api/admin/v1/payment_methods
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `company_id`: number (optional) - filter by company ID

Required Permission: `payment_method_config::view`

Returns paginated list of payment method configurations.

### Get Payment Method Configuration

```
GET /api/admin/v1/payment_methods/{id}
```

Required Permission: `payment_method_config::view`

Returns detailed information about a specific payment method configuration.

### Create Payment Method Configuration

```
POST /api/admin/v1/payment_methods
```

Required Permission: `payment_method_config::create`

Body:

```json
{
  "company_id": number,
  // Required - Company this configuration belongs to
  "name": "string",
  // Required - Display name for the configuration
  "enabled": boolean,
  // Optional - Default: true
  "config": ProviderConfig,
  // Required - Typed provider configuration (see examples below)
  "processing_fee_rate": number
  |
  null,
  // Optional - Fee percentage (e.g., 1.0 for 1%)
  "processing_fee_base": number
  |
  null,
  // Optional - Base fee in smallest currency units (e.g., 20 for €0.20)
  "processing_fee_currency": "string | null"
  // Required if processing_fee_base is set - Currency code (e.g., "EUR")
}
```

**Provider Configuration Examples:**

The `config` field is a tagged union using `"type"` as the discriminator field.

LND (Lightning):

```json
{
  "type": "lnd",
  "url": "https://lnd.example.com:8080",
  "cert_path": "/path/to/tls.cert",
  "macaroon_path": "/path/to/admin.macaroon"
}
```

Bitvora (Lightning) - **DEPRECATED: Service shut down**:

```json
{
  "type": "bitvora",
  "token": "bv_api_token_here",
  "webhook_secret": "webhook_secret_here"
}
```

Revolut:

```json
{
  "type": "revolut",
  "url": "https://api.revolut.com",
  "token": "rev_api_token_here",
  "api_version": "2024-09-01",
  "public_key": "pk_xxx",
  "webhook_secret": "whs_xxx"
}
```

Note: The `webhook_secret` field is automatically populated when the API registers a webhook with Revolut. If you need
to manually set this (e.g., when restoring from backup or migrating), you can provide it during creation or update. If
omitted or set to `null`, the system will automatically register a new webhook and store the secret on startup.

Stripe:

```json
{
  "type": "stripe",
  "secret_key": "sk_live_xxx",
  "publishable_key": "pk_live_xxx",
  "webhook_secret": "whsec_xxx"
}
```

PayPal:

```json
{
  "type": "paypal",
  "client_id": "client_id_here",
  "client_secret": "client_secret_here",
  "mode": "live"
}
```

### Update Payment Method Configuration

```
PATCH /api/admin/v1/payment_methods/{id}
```

Required Permission: `payment_method_config::update`

Body (all fields optional):

```json
{
  "name": "string",
  // Display name (cannot be empty)
  "enabled": boolean,
  // Enable/disable the payment method
  "config": PartialProviderConfig,
  // Partial provider configuration (only include fields to update)
  "processing_fee_rate": number
  |
  null,
  // Fee percentage (null to clear)
  "processing_fee_base": number
  |
  null,
  // Base fee in smallest currency units (e.g., 20 for €0.20, null to clear)
  "processing_fee_currency": "string | null"
  // Currency code (required if base fee is set)
}
```

**Partial Config Update Examples:**

When updating config, only provide the fields you want to change. Missing fields will retain their existing values.

Update only the `url` for a Revolut config (keeps token, api_version, etc.):

```json
{
  "config": {
    "type": "revolut",
    "url": "https://merchant.revolut.com/api/"
  }
}
```

Update only the `public_key` for a Revolut config:

```json
{
  "config": {
    "type": "revolut",
    "public_key": "pk_new_key_here"
  }
}
```

Update LND macaroon path only:

```json
{
  "config": {
    "type": "lnd",
    "macaroon_path": "/new/path/to/admin.macaroon"
  }
}
```

**Notes:**

- The `type` field is always required in the config to identify the provider type
- You cannot change the provider type during an update (e.g., from `lnd` to `revolut`)
- If `processing_fee_base` is set, `processing_fee_currency` must also be provided
- Sensitive fields (tokens, secrets) that are not provided will remain unchanged

### Delete Payment Method Configuration

```
DELETE /api/admin/v1/payment_methods/{id}
```

Required Permission: `payment_method_config::delete`

Response:

```json
{
  "data": {
    "success": true,
    "message": "Payment method configuration deleted successfully"
  }
}
```

---

## User Payment Methods Management

User payment methods are the **saved payment methods that users register on their own account** for automatic
renewals (Nostr Wallet Connect connections, or Revolut cards saved off-session). This is distinct from the
**Payment Method Configuration** above, which stores the provider/merchant settings.

> **Security:** The underlying provider tokens / NWC connection strings are **never** returned. Responses expose only
> non-sensitive metadata (provider, label, card brand/last4/expiry, default/enabled flags) plus a
> `has_external_customer_id` boolean.

There is no admin *create* endpoint — methods are added by users via the customer API. Admins can list, inspect,
edit (label / default / enable-disable), and delete them.

### List User Payment Methods

```
GET /api/admin/v1/user_payment_methods
```

Query Parameters:

- `limit`: number (optional) - max 100, default 50
- `offset`: number (optional) - default 0
- `user_id`: number (optional) - filter to a single user's saved methods

Required Permission: `user_payment_method::view`

Returns a paginated list of `AdminUserPaymentMethodInfo`.

### Get User Payment Method

```
GET /api/admin/v1/user_payment_methods/{id}
```

Required Permission: `user_payment_method::view`

Returns a single `AdminUserPaymentMethodInfo`.

### Update User Payment Method

```
PATCH /api/admin/v1/user_payment_methods/{id}
```

Required Permission: `user_payment_method::update`

Request body (all fields optional):

```json
{
  "is_default": boolean,
  // set this method as the owning user's default (clears the flag on their other methods)
  "enabled": boolean,
  // enable/disable the method
  "name": string | null
  // set the user-defined label, or null to clear it
}
```

Returns the updated `AdminUserPaymentMethodInfo`.

### Delete User Payment Method

```
DELETE /api/admin/v1/user_payment_methods/{id}
```

Required Permission: `user_payment_method::delete`

### AdminUserPaymentMethodInfo

```json
{
  "id": number,
  "user_id": number,
  "provider": "nwc",
  // payment processor: "nwc" or "revolut"
  "name": "string | null",
  "created": "2026-07-15T00:00:00Z",
  "has_external_customer_id": boolean,
  // whether a provider customer id is on file (the value itself is redacted)
  "card_brand": "string | null",
  "card_last_four": "string | null",
  "exp_month": number | null,
  "exp_year": number | null,
  "is_default": boolean,
  "enabled": boolean
}
```

---

## Payment Method Configuration Data Types

### AdminPaymentMethodConfigInfo

**Note:** For security reasons, sensitive values (tokens, API keys, secrets) are NEVER returned in API responses.
Instead, the config contains boolean indicators showing whether these values are configured.

```json
{
  "id": number,
  "company_id": number,
  // Company this config belongs to
  "payment_method": "lightning",
  // AdminPaymentMethodType: "lightning", "revolut", "paypal", "stripe"
  "name": "string",
  "enabled": boolean,
  "provider_type": "string",
  // Provider implementation type ("lnd", "revolut", "stripe", "paypal")
  "config": SanitizedProviderConfig
  |
  null,
  // Sanitized provider config - secrets replaced with boolean indicators
  "processing_fee_rate": number
  |
  null,
  // Fee percentage (e.g., 1.0 for 1%)
  "processing_fee_base": number
  |
  null,
  // Base fee in smallest currency units (e.g., 20 for €0.20)
  "processing_fee_currency": "string | null",
  // Currency code for base fee
  "supported_currencies": ["string"],
  // Supported currency codes (e.g., ["EUR", "USD"]). Empty array means use defaults.
  "created": "string (ISO 8601)",
  "modified": "string (ISO 8601)"
}
```

### SanitizedProviderConfig

The `config` field of `AdminPaymentMethodConfigInfo` is a tagged union — the `"type"` field identifies the variant. All secret/token values are replaced with boolean `has_*` indicators.

**LND (`"type": "lnd"`)**

```json
{
  "type": "lnd",
  "url": "string",
  // LND gRPC endpoint URL
  "cert_path": "string",
  // Path to the TLS certificate file on the server
  "macaroon_path": "string"
  // Path to the macaroon file on the server
}
```

**Revolut (`"type": "revolut"`)**

```json
{
  "type": "revolut",
  "url": "string",
  // Revolut API base URL
  "api_version": "string",
  // API version string (e.g. "2024-09-01")
  "public_key": "string",
  // Revolut public key used for webhook verification
  "has_token": boolean,
  // Whether the API token is configured
  "has_webhook_secret": boolean
  // Whether the webhook secret is configured
}
```

**Stripe (`"type": "stripe"`)**

```json
{
  "type": "stripe",
  "publishable_key": "string",
  // Stripe publishable key (safe to expose)
  "has_secret_key": boolean,
  // Whether the secret key is configured
  "has_webhook_secret": boolean
  // Whether the webhook signing secret is configured
}
```

**PayPal (`"type": "paypal"`)**

```json
{
  "type": "paypal",
  "client_id": "string",
  // PayPal OAuth client ID (safe to expose)
  "mode": "string",
  // "sandbox" or "live"
  "has_client_secret": boolean
  // Whether the client secret is configured
}
```

**Bitvora (`"type": "bitvora"`)**

```json
{
  "type": "bitvora",
  "has_token": boolean,
  // Whether the API token is configured
  "has_webhook_secret": boolean
  // Whether the webhook secret is configured
}
```

### CreatePaymentMethodConfigRequest

```json
{
  "company_id": number,
  // Required - Company to create config for
  "name": "string",
  // Required - Display name
  "enabled": boolean,
  // Optional - Default: true
  "config": ProviderConfig,
  // Required - Typed provider config (with "type" discriminator)
  "processing_fee_rate": number
  |
  null,
  // Optional - Fee percentage (e.g., 1.0 for 1%)
  "processing_fee_base": number
  |
  null,
  // Optional - Base fee in smallest currency units (e.g., 20 for €0.20)
  "processing_fee_currency": "string | null",
  // Required if base fee is set
  "supported_currencies": ["string"] | null
  // Optional - Supported currency codes (e.g., ["EUR", "USD"])
}
```

### UpdatePaymentMethodConfigRequest

```json
{
  "name": "string | null",
  // Optional - Display name
  "enabled": boolean
  |
  null,
  // Optional - Enable/disable
  "config": PartialProviderConfig
  |
  null,
  // Optional - Partial provider config (only include fields to update)
  "processing_fee_rate": number
  |
  null,
  // Optional - Fee percentage (null to clear)
  "processing_fee_base": number
  |
  null,
  // Optional - Base fee in smallest currency units (null to clear)
  "processing_fee_currency": "string | null",
  // Optional - Currency (null to clear)
  "supported_currencies": ["string"] | null
  // Optional - Supported currency codes (e.g., ["EUR", "USD"])
}
```

### ProviderConfig (Tagged Union) - For Creation

The `config` field for **creating** a new payment method uses a tagged union format with `"type"` as the discriminator.
All fields except `webhook_secret` are required when creating:

| Type          | Payment Method | Required Fields                                                       |
|---------------|----------------|-----------------------------------------------------------------------|
| `lnd`         | lightning      | `url`, `cert_path`, `macaroon_path`                                   |
| ~~`bitvora`~~ | ~~lightning~~  | ~~`token`, `webhook_secret`~~ (service shut down)                     |
| `revolut`     | revolut        | `url`, `token`, `api_version`, `public_key` (webhook_secret optional) |
| `stripe`      | stripe         | `secret_key`, `publishable_key`, `webhook_secret`                     |
| `paypal`      | paypal         | `client_id`, `client_secret`, `mode`                                  |

### PartialProviderConfig (Tagged Union) - For Updates

The `config` field for **updating** a payment method also uses a tagged union format with `"type"` as the discriminator.
Only the `type` field is required; all other fields are optional and will keep their existing values if not provided:

| Type          | Optional Fields                                               |
|---------------|---------------------------------------------------------------|
| `lnd`         | `url`, `cert_path`, `macaroon_path`                           |
| ~~`bitvora`~~ | ~~`token`, `webhook_secret`~~ (service shut down)             |
| `revolut`     | `url`, `token`, `api_version`, `public_key`, `webhook_secret` |
| `stripe`      | `secret_key`, `publishable_key`, `webhook_secret`             |
| `paypal`      | `client_id`, `client_secret`, `mode`                          |

### Notes

**Provider Types:**

- `lnd` - Lightning Network Daemon for Lightning payments
- ~~`bitvora`~~ - ~~Bitvora API for Lightning payments~~ (service shut down)
- `revolut` - Revolut Business API
- `stripe` - Stripe Payments API
- `paypal` - PayPal REST API

**Multiple Configurations:**
A company can have multiple payment method configurations for the same payment method type. This allows keeping disabled
legacy configurations that are still referenced by historical payments (e.g., VM payments, subscription payments) while
having newer active configurations.

**Processing Fees:**

- `processing_fee_rate` is a percentage (1.0 = 1%, 2.5 = 2.5%)
- `processing_fee_base` is in smallest currency units (e.g., 20 for €0.20, 100 for $1.00)
- For BTC, the value is in millisats (e.g., 1000000 for 1000 sats)
- When `processing_fee_base` is set, `processing_fee_currency` is required

**Security:**

- Configuration JSON may contain sensitive credentials (API keys, secrets)
- Ensure proper access controls are in place for payment method management
- Consider masking sensitive fields in API responses for audit logging

---

### Notes

**IP Space Prefix Sizes:**

- Smaller prefix numbers = larger networks (e.g., /22 = 1024 IPs)
- Larger prefix numbers = smaller networks (e.g., /24 = 256 IPs)
- `min_prefix_size` should be the largest number (smallest allocation)
- `max_prefix_size` should be the smallest number (largest allocation)
- Example: min=24, max=22 allows selling /24, /23, and /22 subnets

**RIR Validation:**

- All RIRs enforce minimum BGP announcement sizes for validation
- IPv4: Minimum prefix size is /24 (256 addresses)
- IPv6: Minimum prefix size is /48
- Prefix sizes are validated against RIR limits when creating/updating IP spaces
- Validation ensures compliance with industry-standard BGP routing requirements

**Pricing Structure:**

- Multiple pricing tiers can exist for the same IP space
- Each tier targets a specific prefix size (e.g., /24, /28, /32)
- One pricing entry per prefix size per space (enforced uniqueness)
- Prices are in smallest currency unit (cents for USD, millisats for BTC)

**IP Space Lifecycle:**

- `is_available=true, is_reserved=false` → Available for customer purchase
- `is_available=false` → Hidden from customer browsing
- `is_reserved=true` → Admin reserved, not for sale
- Cannot delete IP space with active subscriptions

**Public API vs Admin API:**

- Public API: CIDR blocks are hidden for security until purchase; uses `ip_version` field instead
- Admin API: Full CIDR information visible for management purposes

**Metadata Examples:**

```json
{
  "routing_requirements": "BGP announcement required",
  "upstream_provider": "Cogent",
  "asn": "AS64512",
  "notes": "IPv6 PI allocation from ARIN"
}
```

---

## Resource Cost Tracking

Optional, admin-only cost tracking (issue #82) used to compute profit/loss.
Costs are stored in a single generic `resource_cost` table weakly linked to any
resource via `(resource_type, resource_id)` — no schema change is needed to add
new cost-bearing resource kinds, and a single resource may carry multiple cost
records (e.g. a host with recurring rent **and** a one-time hardware investment).

Cost data is **never** exposed to end users. All amounts are in the smallest
currency units (cents for fiat, millisats for BTC). For an `ip_range` recurring
cost, `amount` is the cost per single IP.

The `generic` resource type covers costs **not tied to any internal entity**
(e.g. a colo cross-connect or upstream transit subscription): it carries a
free-form `label` and ignores `resource_id`.

**Permission resource:** `resource_cost` (Create/View/Update/Delete)

### List Resource Costs

`GET /api/admin/v1/resource_costs`

Query parameters:

- `limit` (default 50, max 100), `offset` (default 0)
- `resource_type` (optional): `vm_host` | `ip_range`
- `resource_id` (optional): filter to a single resource

### Get Resource Cost

`GET /api/admin/v1/resource_costs/{id}`

### Create Resource Cost

`POST /api/admin/v1/resource_costs`

```json
{
  "resource_type": "vm_host",
  "resource_id": 12,
  "cost_type": "recurring",
  "amount": 8000,
  "currency": "EUR",
  "interval_amount": 1,
  "interval_type": "month",
  "billing_start": "2026-01-01T00:00:00Z",
  "billing_end": null
}
```

Generic (unlinked) subscription cost — `resource_id` is ignored, `label` required:

```json
{
  "resource_type": "generic",
  "label": "Upstream transit (Cogent)",
  "cost_type": "recurring",
  "amount": 15000,
  "currency": "USD",
  "interval_amount": 1,
  "interval_type": "month"
}
```

One-time capital cost (break-even) example:

```json
{
  "resource_type": "vm_host",
  "resource_id": 12,
  "cost_type": "one_time",
  "amount": 250000,
  "currency": "EUR",
  "billing_start": "2025-11-15T00:00:00Z"
}
```

### Update Resource Cost

`PATCH /api/admin/v1/resource_costs/{id}`

All fields optional. Interval/billing fields use PATCH-clear semantics: omit a
field to leave it unchanged, or send `null` to clear it.

```json
{ "amount": 9000, "billing_end": "2026-06-01T00:00:00Z" }
```

### Delete Resource Cost

`DELETE /api/admin/v1/resource_costs/{id}`

### Data Types

**AdminResourceCostDetail**

| Field           | Type                       | Notes                                             |
|-----------------|----------------------------|---------------------------------------------------|
| id              | u64                        |                                                   |
| resource_type   | `vm_host`\|`ip_range`\|`generic` | Weak link kind                              |
| resource_id     | u64                        | Id within the resource's table (no FK); 0 for `generic` |
| label           | string \| null             | Free-form label; required for `generic`           |
| cost_type       | `recurring` \| `one_time`  |                                                   |
| amount          | u64                        | Smallest currency units; per-IP for ip_range      |
| currency        | string                     | e.g. `USD`, `EUR`                                 |
| interval_amount | u64 \| null                | Required for `recurring`; null for `one_time`     |
| interval_type   | `day`\|`month`\|`year`\|null | Billing interval unit                           |
| billing_start   | datetime \| null           | Cost start / one-time purchase date               |
| billing_end     | datetime \| null           | Cost end date; null = still active/ongoing         |
| created         | datetime                   |                                                   |
| updated         | datetime                   |                                                   |

**Notes:**

- All cost fields are optional; a resource with no `resource_cost` rows simply
  has no cost data (no behaviour change).
- Currency conversion (when costs and revenues differ in currency) is deferred
  to a follow-up issue.