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"`
**AdminUserRole**: `"super_admin"`, `"admin"`, `"read_only"`
**AdminUserStatus**: `"active"`, `"suspended"`, `"deleted"`
**SubscriptionPaymentType**: `"purchase"`, `"renewal"`, `"upgrade"`
**SubscriptionType**: `"ip_range"`, `"asn_sponsoring"`, `"dns_hosting"`
**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",
  "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
- `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

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, "amount": 999, "setup_amount": 0 }]
    }
  }
}
```

`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

Required Permission: `subscriptions::view`

Returns paginated list of subscriptions with embedded line items and payment count.

#### Get Subscription Details

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

Required Permission: `subscriptions::view`

Returns complete subscription information including all line items and payment count.

#### 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
  }
}
```

#### 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. 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`

#### Create Subscription Line Item

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

Required Permission: `subscription_line_items::create`

Request body:

```json
{
  "subscription_id": number,
  "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)
  // service-specific JSON config
}
```

Response: Created line item

#### Update Subscription Line Item

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

Required Permission: `subscription_line_items::update`

Request body (all fields optional):

```json
{
  "name": string,
  "description": string,
  "amount": number,
  "setup_amount": number,
  "configuration": object
}
```

Response: Updated line item

#### 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
}
```

### 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
}
```

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.

#### 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
}
```

The `base_currency` field is validated against the supported Currency enum values.

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.

#### 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
  "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
}
```

#### 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
}
```

#### 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",
    "..."
  ]
}
```

### 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.

### 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"
    }
  }
  ```

### 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"
      }
    ]
  }
}
```

## Error Responses

All error responses follow the format:

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

Common HTTP status codes:

- `400` - Bad Request (invalid input)
- `401` - Unauthorized (invalid or missing authentication)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `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
- `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",
  "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"
  }
}
```

---

## 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"
}
```