Skip to main content
Infrastructure

Hosts and Infrastructure

Manage server inventory with customer filtering, software assignments, network interfaces, and reference data for infrastructure management.

Auth required: Yes (auth:api) for all endpoints.

The hosts section covers physical and virtual server inventory, including datacenters, infrastructures, and associated metadata (OS, roles, services, etc.).

Model Properties

Host

Property Type Required Description
id integer auto Unique identifier
customer_id integer Yes FK to customers
code string Yes Unique host code/identifier (must be unique)
name string Yes Host name
address string No IPv4 address of the host
vlan string No VLAN identifier
host_os_id integer No FK to host_os. Operating system
host_role_id integer No FK to host_roles. Role of this host (e.g. primary, backup)
host_service_id integer No FK to host_services. Main service running on this host
host_shell_id integer No FK to host_shells. Shell environment
host_type_id integer No FK to host_types. Type (e.g. physical, VM, container)
host_function_id integer No FK to host_functions. Function classification
host_supplier_id integer No FK to host_suppliers. Hardware or hosting supplier
nichandle string No OVH NIC-handle or provider identifier
free1 string No Free-form custom field 1
free2 string No Free-form custom field 2
managed boolean No Whether this host is actively managed
config text No Configuration notes or data
infrastructure_id integer No FK to infrastructures
supplier_identification string No Supplier-specific identifier
datacenter_id integer No FK to datacenters
comment text No Internal notes
installed_at date No Installation date
created_at datetime auto Creation timestamp
updated_at datetime auto Last update timestamp

Hosts

Base URL: /api/v1/hosts

GET /v1/hosts

List hosts. Supports filtering by customer.

Query parameters:

Parameter Type Description
filter[customer_id] integer Filter by customer

Response 200: Array of host objects with relations: customer, os, role, shell, type, infrastructure.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/hosts?filter[customer_id]=42" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/hosts",
    params={"filter[customer_id]": 42},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
hosts = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/hosts', [
        'filter[customer_id]' => 42,
    ]);

$hosts = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/hosts?filter[customer_id]=42",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Accept": "application/json"
    }
  }
);
const hosts = await response.json();

POST /v1/hosts

Create a new host.

Body (JSON): Validated via Host::rules()['store'].

Date fields (format d/m/Y): parsed automatically. Datetime fields (format d/m/Y H:i:s): parsed via Carbon.

Response 201: Created host object. Response 422: Validation error.

GET /v1/hosts/{id}

Get a single host with all relations: customer, datacenter, documents, softwares, interfaces, os, role, shell, supplier, type, sheets, tickets.

Response 200: Host object with full relations. Response 404: Not found.

Examples:

curl -s -X GET "https://your-instance.bluerocktel.net/api/v1/hosts/15" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

import requests

response = requests.get(
    "https://your-instance.bluerocktel.net/api/v1/hosts/15",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
host = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://your-instance.bluerocktel.net/api/v1/hosts/15');

$host = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/hosts/15",
  {
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Accept": "application/json"
    }
  }
);
const host = await response.json();

PUT /v1/hosts/{id}

Update a host. Date/datetime fields are automatically converted.

Response 201: Updated host object. Response 404: Not found.

DELETE /v1/hosts/{id}

Delete a host.

Response 201: Success message. Response 404: Not found.

POST /v1/hosts/{host}/soft_attach

Attach software(s) to a host (many-to-many, without detaching existing).

URL parameters:

Parameter Type Description
host integer Host ID

Body (JSON):

Field Type Description
host_softwares array Array of host_software IDs to attach

Response 201: Updated host object.

Examples:

curl -s -X POST "https://your-instance.bluerocktel.net/api/v1/hosts/15/soft_attach" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host_softwares": [1, 3, 7]}'

import requests

response = requests.post(
    "https://your-instance.bluerocktel.net/api/v1/hosts/15/soft_attach",
    json={"host_softwares": [1, 3, 7]},
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)
host = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://your-instance.bluerocktel.net/api/v1/hosts/15/soft_attach', [
        'host_softwares' => [1, 3, 7],
    ]);

$host = $response->json();

const response = await fetch(
  "https://your-instance.bluerocktel.net/api/v1/hosts/15/soft_attach",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ host_softwares: [1, 3, 7] })
  }
);
const host = await response.json();

POST /v1/hosts/{host}/soft_detach

Detach specific software(s) from a host.

URL parameters:

Parameter Type Description
host integer Host ID

Body (JSON):

Field Type Description
host_softwares array Array of host_software IDs to detach

Response 201: Updated host object.

Infrastructures

Base URL: /api/v1/infrastructures

Standard CRUD (resource routes)

Method Route Description
GET /v1/infrastructures List all infrastructures
POST /v1/infrastructures Create a new infrastructure
GET /v1/infrastructures/{id} Get a single infrastructure
PUT /v1/infrastructures/{id} Update an infrastructure
DELETE /v1/infrastructures/{id} Delete an infrastructure

Datacenters

Base URL: /api/v1/datacenters

Standard CRUD (resource routes)

Method Route Description
GET /v1/datacenters List all datacenters
POST /v1/datacenters Create a new datacenter
GET /v1/datacenters/{id} Get a single datacenter
PUT /v1/datacenters/{id} Update a datacenter
DELETE /v1/datacenters/{id} Delete a datacenter

Host Reference Data

These resources provide the reference/lookup data used when creating or editing hosts:

Resource Base URL Description
Host Functions /api/v1/host_functions Functions/roles of hosts
Host OS /api/v1/host_os Operating systems
Host Roles /api/v1/host_roles Roles (primary, backup, etc.)
Host Services /api/v1/host_services Services running on hosts
Host Shells /api/v1/host_shells Shell environments
Host Softwares /api/v1/host_softwares Software installed on hosts
Host Suppliers /api/v1/host_suppliers Suppliers for hosts
Host Types /api/v1/host_types Types (physical, VM, container, etc.)
Host Network Interfaces /api/v1/host_network_interfaces Network interfaces

All of the above support standard CRUD resource routes (GET list, POST create, GET show, PUT update, DELETE destroy).

Next PBX (3CX)