/systems/inventory - Collect system inventory

POST /systems/inventory
Basic auth

System inventory collection endpoint with HTTP Basic authentication

application/json

Body Required

Raw inventory JSON from the system (structure varies by system type)

object object

Raw inventory data sent directly from the system

Additional properties are allowed.

Responses

  • 202 application/json

    Inventory received and queued for processing

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • data_size integer

        Inventory data size in bytes

      • message string

        A message from server

      • queue_status string

        Queue status message

      • system_key string

        System KEY

      • timestamp string(date-time)

        Timestamp of received inventory
  • 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
  • 413 application/json

    Request Entity Too Large

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • max_size_bytes integer

        Maximum allowed request size in bytes

      • received_bytes integer

        Size of received request in bytes
  • 500 application/json

    Internal Server Error

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attribute Show data attribute object
      • error string
POST /systems/inventory 
curl \
 --request POST 'https://collect.your-domain.com/api/systems/inventory' \
 --user "username:password" \
 --header "Content-Type: application/json" \
 --data '{"uuid":"659d2fbe-792f-4a0d-ae58-f278304d4f7f","facts":{"nodes":{"1":{"fqdn":"rl1.dp.nethserver.net","ui_name":"MyNodeRl1","version":"3.17.0-dev.6","default_ipv4":"165.22.17.26","default_ipv6":"2a03:b0c0:3:f0:0:1:dbfe:3000","cluster_leader":true}},"cluster":{"ui_name":"MyNethServer 8","subscription":"community","user_domains":[],"leader_node_id":"1"},"modules":[{"id":"mail1","name":"mail","node":"1","ui_name":"MyMail","version":"1.7.4"}]},"$schema":"https://schema.nethserver.org/facts/2022-12.json","installation":"nethserver"}'
Request example 
{
  "uuid": "659d2fbe-792f-4a0d-ae58-f278304d4f7f",
  "facts": {
    "nodes": {
      "1": {
        "fqdn": "rl1.dp.nethserver.net",
        "ui_name": "MyNodeRl1",
        "version": "3.17.0-dev.6",
        "default_ipv4": "165.22.17.26",
        "default_ipv6": "2a03:b0c0:3:f0:0:1:dbfe:3000",
        "cluster_leader": true
      }
    },
    "cluster": {
      "ui_name": "MyNethServer 8",
      "subscription": "community",
      "user_domains": [],
      "leader_node_id": "1"
    },
    "modules": [
      {
        "id": "mail1",
        "name": "mail",
        "node": "1",
        "ui_name": "MyMail",
        "version": "1.7.4"
      }
    ]
  },
  "$schema": "https://schema.nethserver.org/facts/2022-12.json",
  "installation": "nethserver"
}
Response examples (202) 
{
  "code": 200,
  "message": "Inventory received and queued for processing",
  "data": {
    "data_size": 10145,
    "message": "Your inventory data has been received and will be processed shortly",
    "queue_status": "queued",
    "system_key": "NETH-4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7",
    "timestamp": "2025-07-16T15:46:51.571831+02:00"
  }
}
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 (413) 
{
  "code": 413,
  "message": "Request too large",
  "data": {
    "max_size_bytes": 10485760,
    "received_bytes": 20971520
  }
}
Response examples (500) 
{
  "code": 500,
  "message": "Failed to process inventory",
  "data": {
    "error": "Processing queue unavailable"
  }
}