Sign in

v62

latestOpenAPI 3.1.0Dual (AGPL3.0, Commercial License Available)raw.githubusercontent.com2026-08-03211303932.5 KB
Services

Create a new service

Creates a service with optional bindings to ip_addresses or ports. The id, created_at, updated_at, and source fields are generated server-side. Bindings are specified without service_id or network_id - these are assigned automatically.

Binding Validation Rules

  • Cross-host validation: All bindings must reference ports/interfaces that belong to the service's host. Bindings referencing entities from other hosts will be rejected.
  • Deduplication: Duplicate bindings in the same request are automatically deduplicated.
  • All-interfaces precedence: If a port binding with ip_address_id: null (all ip_addresses) is included, any specific-interface bindings for the same port are automatically removed.
  • Conflict detection: Interface bindings conflict with port bindings on the same interface. A port binding on all ip_addresses conflicts with any interface binding.
post/api/v1/services

Request body

host_idstring uuid required

The host this entity belongs to.

namestring required

Human-facing name for the service.

network_idstring uuid required

The network this entity belongs to.

service_definitionstring required

Which known software this service is, if identified.

tagsstring[] required

Tags assigned to this entity.

Response

Service created successfully

errorstring nullable

Human-readable failure message. Omitted on success.

successboolean required

true when the request succeeded. false responses carry error instead of data.

Example response

{
  "data": {
    "bindings": [
      {
        "created_at": "2026-07-29T15:23:06.668616Z",
        "first_discovery_id": null,
        "id": "7ad6de19-781d-4c36-b3a6-426ca0d47007",
        "ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
        "last_discovery_id": null,
        "last_seen_at": "2026-07-29T15:23:06.668616Z",
        "lineage_id": null,
        "network_id": "550e8400-e29b-41d4-a716-446655440002",
        "port_id": "550e8400-e29b-41d4-a716-446655440006",
        "service_id": "550e8400-e29b-41d4-a716-446655440007",
        "type": "Port",
        "updated_at": "2026-07-29T15:23:06.668616Z",
        "valid_from": "2026-07-29T15:23:06.668616Z",
        "valid_to": null
      }
    ],
    "created_at": "2026-01-15T10:30:00Z",
    "first_discovery_id": null,
    "host_id": "550e8400-e29b-41d4-a716-446655440003",
    "id": "550e8400-e29b-41d4-a716-446655440007",
    "last_discovery_id": null,
    "last_seen_at": "2026-01-15T10:30:00Z",
    "lineage_id": null,
    "name": "nginx",
    "network_id": "550e8400-e29b-41d4-a716-446655440002",
    "position": 0,
    "service_definition": "Unclaimed Open Ports",
    "source": {
      "type": "Manual"
    },
    "tags": [],
    "updated_at": "2026-01-15T10:30:00Z",
    "valid_from": "2026-01-15T10:30:00Z",
    "valid_to": null,
    "virtualization": null
  },
  "meta": {
    "api_version": 1,
    "server_version": "0.17.7"
  }
}