/systems - Create system

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api.my.nethesis.it/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}
Close
POST /systems
Bearer auth

Create a new system. Users can create systems for organizations they can manage based on hierarchical permissions. The organization_id must be specified in the request.

application/json

Body Required

  • name string Required

    System name

  • organization_id string Required

    Organization Logto ID to associate the system with (use the logto_id from organization responses)

  • custom_data object

    Custom system data (optional)

    Hide custom_data attribute Show custom_data attribute object
    • * string Additional properties
  • notes string

    Additional notes or description for the system (optional)

  • created_by_organization_id string

    Optional. Attributes the new system's created_by display org to an ancestor org (a reseller or distributor) instead of the caller's own org — used when an upper tier creates a system on behalf of a lower one (e.g. bulk import). Honored only for owner or distributor callers, with the target within the caller's hierarchy. Display/audit only: system ownership and visibility stay governed by organization_id. Empty = attributed to the caller's organization. When set, the created_by snapshot in responses shows the attributed org and carries on_behalf_of: true.

  • created_at string(date-time)

    Optional. Creation timestamp the system already has in an external source of record (e.g. a bulk import), used instead of the API call time. Honored only for owner or distributor callers; cannot be in the future.

  • registered_at string(date-time)

    Optional. Registration timestamp the system already has in an external source of record. The system is created already registered, so POST /api/systems/register is not needed (and would return 409). Honored only for owner or distributor callers; cannot be in the future or precede created_at.

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 | null

        System type (auto-detected by collect service, null until first inventory collection)

        Values are ns8 or nsec.

      • status string

        Unified system status. Priority: suspended > deleted > unknown/active/inactive. Computed from heartbeat + suspension state.

        Values are unknown, active, inactive, suspended, 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 object

        Organization information embedded in system response

        Hide organization attributes Show organization attributes object
        • id string

          Database UUID of the organization (empty string for owner organization)

        • logto_id string

          Logto organization ID (used for identity/auth purposes)

        • name string

          Organization name

        • type string

          Organization type

          Values are owner, distributor, reseller, or customer.

      • 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

        • username string

          Username of the user 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

        • on_behalf_of boolean

          True when the system was attributed to a different organization via created_by_organization_id (the user acted on behalf of organization_name rather than belonging to it). Omitted when false.

      • last_heartbeat string(date-time)

        Last heartbeat timestamp

      • last_inventory string(date-time) | null

        Last inventory received timestamp. NULL means no inventory received yet.

      • 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.

      • suspended_at string(date-time) | null

        Suspension timestamp. NULL means active, non-NULL means suspended.

      • suspended_by_org_id string | null

        Organization ID that caused cascade suspension (for targeted reactivation).

      • rebranding_enabled boolean

        Whether rebranding is active for this system (direct or inherited)

      • rebranding_org_id string | null

        Logto organization ID (logto_id) that provides the rebranding assets (the org itself or an ancestor). Use this value as the :org_id parameter in /api/rebranding/:org_id/* endpoints.
  • 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","organization_id":"akkbs6x2wo82","custom_data":{"datacenter":"EU-West-1","environment":"production","tier":"web"},"notes":"Production web server for EU region","created_by_organization_id":"0lomt7qqpbue","created_at":"2019-03-18T12:20:53Z","registered_at":"2021-01-21T17:24:10Z"}'
Request examples 
{
  "name": "Production Server 01",
  "organization_id": "akkbs6x2wo82",
  "custom_data": {
    "datacenter": "EU-West-1",
    "environment": "production",
    "tier": "web"
  },
  "notes": "Production web server for EU region",
  "created_by_organization_id": "0lomt7qqpbue",
  "created_at": "2019-03-18T12:20:53Z",
  "registered_at": "2021-01-21T17:24:10Z"
}
Response examples (201) 
{
  "code": 201,
  "message": "system created successfully",
  "data": {
    "id": "4cf3053f-d0d5-4b10-b752-ff8f7b63c2f7",
    "name": "Production Server 01",
    "type": "nsec",
    "status": "active",
    "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": "4405ffd0-0aca-44ef-bae2-c8545bce94f4",
      "logto_id": "akkbs6x2wo82",
      "name": "ACME Corp",
      "type": "customer"
    },
    "custom_data": {
      "datacenter": "EU-West-1",
      "environment": "production",
      "tier": "web"
    },
    "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",
      "username": "edoardo.super",
      "name": "Edoardo Super",
      "email": "edoardo.spadoni@nethesis.it",
      "organization_id": "lbswt1rxdhbz",
      "organization_name": "Nethesis Italia",
      "on_behalf_of": true
    },
    "last_heartbeat": "2025-07-21T10:25:00Z",
    "last_inventory": "2025-07-21T10:20:00Z",
    "registered_at": "2025-11-06T10:30:00Z",
    "suspended_at": "2025-11-10T14:00:00Z",
    "suspended_by_org_id": "org_abc123",
    "rebranding_enabled": true,
    "rebranding_org_id": "org_dist001"
  }
}
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": {}
}