/systems/{id} - Update system | my.nethesis.it API documentation

/systems/{id} - Update system

PUT /systems/{id}

Update a system. All fields are optional. Users can update systems created by their organization based on hierarchical permissions.

Path parameters

id string Required

System ID

application/json

Body Required

name string

System name
organization_id string

Organization ID to associate the system with
custom_data object

Custom system data
Hide custom_data attribute Show custom_data attribute object
- * string Additional properties
notes string

Additional notes or description for the system

Responses

200 application/json

System updated successfully
Hide response attributes Show response attributes object
- code integer
- message string
- data object
  
  Hide data attributes Show data attributes object
  
  id string
  
  System ID
  
  name string
  
  System name
  
  type string | null
  
  System type (auto-detected by collect service, null until first inventory collection)
  
  Values are ns8 or nsec.
  
  status string
  
  System operational status (defaults to 'unknown', auto-updated by collect service)
  
  Values are unknown, online, offline, or deleted.
  
  fqdn string
  
  Fully qualified domain name
  
  ipv4_address string
  
  IPv4 address
  
  ipv6_address string
  
  IPv6 address
  
  version string
  
  System version
  
  system_key string
  
  Auto-generated unique commercial system key. Hidden (empty string) until system is registered.
  
  organization_id string
  
  Organization ID to which this system belongs
  
  organization_name string
  
  Organization name to which this system belongs (resolved from distributors, resellers, or customers)
  
  custom_data object
  
  Custom system data
  
  Additional properties are allowed.
  
  system_secret string
  
  Auto-generated system secret token in format my_. (only returned during creation/regeneration, never stored or displayed again)
  
  notes string
  
  Additional notes or description for the system
  
  created_at string(date-time)
  
  System creation timestamp
  
  updated_at string(date-time)
  
  System last update timestamp
  
  created_by object
  
  Hide created_by attributes Show created_by attributes object
  
  user_id string
  
  User ID who created the system
  
  name string
  
  Full name of the user who created the system
  
  email string
  
  Email of the user who created the system
  
  organization_id string
  
  Organization ID of the creator
  
  organization_name string
  
  Organization name of the creator
  
  heartbeat_status string
  
  System heartbeat status (alive=<15min, dead=>15min, zombie=never communicated)
  
  Values are alive, dead, or zombie.
  
  last_heartbeat string(date-time)
  
  Last heartbeat timestamp
  
  heartbeat_minutes integer
  
  Minutes since last heartbeat
  
  registered_at string(date-time) | null
  
  Registration timestamp. NULL means not yet registered, non-NULL means system registered at that time. When NULL, system_key is hidden.
400 application/json

Bad request - validation error
Hide response attributes Show response attributes object
- code integer
  
  HTTP error code
- message string
  
  Error message
- data object
  
  Hide data attributes Show data attributes object
  
  type string
  
  Type of error
  
  Values are validation_error or external_api_error.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  Field name that failed validation
  
  message string
  
  Error code or message
  
  value string
  
  Value that failed validation
  
  details
  
  Additional error details
401 application/json

Unauthorized - invalid or missing token
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
403 application/json

Forbidden - insufficient permissions
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
404 application/json

Resource not found
Hide response attributes Show response attributes object
- code integer
  
  HTTP error code
- message string
  
  Error message
- data object
  
  Hide data attributes Show data attributes object
  
  type string
  
  Type of error
  
  Values are validation_error or external_api_error.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  Field name that failed validation
  
  message string
  
  Error code or message
  
  value string
  
  Value that failed validation
  
  details
  
  Additional error details

PUT /systems/{id}

curl \
 --request PUT 'https://collect.your-domain.com/api/systems/sys_123456789' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"name":"Production Server 01","organization_id":"org_123456789","custom_data":{"tier":"web","datacenter":"EU-West-1","environment":"production"},"notes":"Production web server for EU region"}'

Request examples

{
  "name": "Production Server 01",
  "organization_id": "org_123456789",
  "custom_data": {
    "tier": "web",
    "datacenter": "EU-West-1",
    "environment": "production"
  },
  "notes": "Production web server for EU region"
}

Response examples (200)

{
  "code": 200,
  "message": "system updated successfully",
  "data": {
    "id": "4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7",
    "name": "Production Server 01",
    "type": "nsec",
    "status": "unknown",
    "fqdn": "prod-web-01.example.com",
    "ipv4_address": "192.168.1.100",
    "ipv6_address": "2001:db8::1",
    "version": "2.1.4",
    "system_key": "ABC123DEF456",
    "organization_id": "org_123456789",
    "organization_name": "Acme Corporation",
    "custom_data": {
      "tier": "web",
      "datacenter": "EU-West-1",
      "environment": "production"
    },
    "system_secret": "my_a1b2c3d4e5f6g7h8i9j0.k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
    "notes": "Production web server for EU region",
    "created_at": "2025-07-01T09:00:00Z",
    "updated_at": "2025-07-10T10:30:00Z",
    "created_by": {
      "user_id": "53h5zxpwu4vc",
      "name": "Edoardo Super",
      "email": "edoardo.spadoni@nethesis.it",
      "organization_id": "lbswt1rxdhbz",
      "organization_name": "Nethesis Italia"
    },
    "heartbeat_status": "alive",
    "last_heartbeat": "2025-07-21T10:25:00Z",
    "heartbeat_minutes": 5,
    "registered_at": "2025-11-06T10:30:00Z"
  }
}

Response examples (400)

{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}

Response examples (401)

{
  "code": 401,
  "message": "invalid token",
  "data": {}
}

Response examples (403)

{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}

Response examples (404)

{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}