Get single system

GET /systems/{id}

Bearer auth

Get a specific system by ID. Users can access systems created by their organization based on hierarchical permissions.

Path parameters

id string Required

System ID

Responses

200 application/json

System retrieved 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
  
  System type
  
  status string
  
  System operational status
  
  Values are online, offline, or maintenance.
  
  fqdn string
  
  Fully qualified domain name
  
  ipv4_address string
  
  IPv4 address
  
  ipv6_address string
  
  IPv6 address
  
  version string
  
  System version
  
  last_seen string(date-time)
  
  Last seen timestamp from inventory
  
  custom_data object
  
  Custom system data
  
  Additional properties are allowed.
  
  secret_hint string
  
  Last 4 characters of system secret for identification
  
  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
  
  user_name string
  
  Username 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
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

GET /systems/{id}

curl \
 --request GET 'https://collect.your-domain.com/api/systems/sys_123456789' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

Response examples (200)

{
  "code": 200,
  "message": "system retrieved successfully",
  "data": {
    "id": "4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7",
    "name": "Production Server 01",
    "type": "ns8",
    "status": "online",
    "fqdn": "prod-web-01.example.com",
    "ipv4_address": "192.168.1.100",
    "ipv6_address": "2001:db8::1",
    "version": "2.1.4",
    "last_seen": "2025-07-10T10:30:00Z",
    "custom_data": {
      "tier": "web",
      "datacenter": "EU-West-1",
      "environment": "production"
    },
    "secret_hint": "a7b9",
    "created_at": "2025-07-01T09:00:00Z",
    "updated_at": "2025-07-10T10:30:00Z",
    "created_by": {
      "user_id": "usr_123456789",
      "user_name": "admin",
      "organization_id": "org_123456789",
      "organization_name": "Nethesis"
    },
    "heartbeat_status": "alive",
    "last_heartbeat": "2025-07-21T10:25:00Z",
    "heartbeat_minutes": 5
  }
}

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