Create system

POST /systems

Bearer auth

Create a new system. Any authenticated user can create systems - access control is based on the creator's organization.

application/json

Body Required

name string Required

System name
type string Required

System type
custom_data object

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

Responses

201 application/json

System created 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
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

POST /systems

curl \
 --request POST 'https://collect.your-domain.com/api/systems' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"name":"Production Server 01","type":"ns8","custom_data":{"tier":"web","datacenter":"EU-West-1","environment":"production"}}'

Request examples

{
  "name": "Production Server 01",
  "type": "ns8",
  "custom_data": {
    "tier": "web",
    "datacenter": "EU-West-1",
    "environment": "production"
  }
}

Response examples (201)

{
  "code": 201,
  "message": "system created 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 (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": {}
}