/systems/{id}/entitlements/{entitlement}/seats - Give a seat to an application instance

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

{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}

POST /systems/{id}/entitlements/{entitlement}/seats

Bearer auth

Give one seat of a seated add-on to an application instance of the system (any node). The add-on must be active and a seat must be free. Requires manage:entitlements — the permission to buy add-ons — on a system within the caller's hierarchy.

Path parameters

id string Required

System ID
entitlement string Required

Catalog id (or legacy alias) of a seated add-on

application/json

Body Required

module_id string Required

Application instance of the add-on's applies_to on the system

Responses

201 application/json

Seat assigned successfully
Hide response attributes Show response attributes object
- code integer
- message string
- data object
  
  One seat of a seated add-on given to an application instance
  
  Hide data attributes Show data attributes object
  
  id string(uuid)
  
  module_id string
  
  Application instance holding the seat
  
  assigned_at string(date-time)
  
  assigned_by object
  
  Who gave the license; replaced by {"out_of_scope": true} when that user's organization is outside the caller's hierarchy
  
  Hide assigned_by attributes Show assigned_by attributes object
  
  user_id string
  
  Logto ID of the creator
  
  user_name string
  
  Full name of the creator
  
  organization_id string
  
  Organization ID of the creator
  
  organization_name string
  
  Organization name of the creator
  
  channel string
  
  Set to "shop" when the grant was created via POST /entitlements/activate. Omitted otherwise.
  
  in_quota boolean
  
  False for the seats beyond the number bought, oldest first. They are not honored until seats are added.
400 application/json

Not a seated add-on, or no such instance of the add-on's application on the system
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

System not found, or the add-on is not granted to it
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
409 application/json

Add-on not active, system suspended or deleted, instance already holding a seat, or no free seat left
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
500 application/json

Internal server error
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null

POST /systems/{id}/entitlements/{entitlement}/seats

curl \
 --request POST 'https://my.nethesis.it/backend/api/systems/sys_123456789/entitlements/nethvoice-chat/seats' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "module_id": "nethvoice5"
}'

Request examples

{
  "module_id": "nethvoice5"
}

Response examples (201)

{
  "code": 201,
  "message": "seat assigned successfully",
  "data": {
    "id": "8f1c2a8e-4d1b-4e57-9a6f-2b3c4d5e6f70",
    "module_id": "nethvoice5",
    "assigned_at": "2026-10-22T10:00:00Z",
    "assigned_by": {
      "user_id": "53h5zxpwu4vc",
      "user_name": "Edoardo Super",
      "organization_id": "lbswt1rxdhbz",
      "organization_name": "Nethesis Italia",
      "channel": "shop"
    },
    "in_quota": true
  }
}

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

Response examples (409)

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

Response examples (500)

{
  "code": 500,
  "message": "internal server error",
  "data": {}
}