/entitlements/catalog/{id}/availability - Add a commercial availability rule

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 /entitlements/catalog/{id}/availability

Bearer auth

Restrict who may buy/self-activate the add-on: unlock it for a whole hierarchy role OR one specific organization (exactly one of the two). By default (no rules) an add-on is available to everyone. Only the owner organization or a Super Admin can manage availability rules.

Path parameters

id string Required

Catalog id

application/json

Body Required

org_role string

Hierarchy role to unlock the item for (mutually exclusive with organization_id)

Values are distributor, reseller, or customer.
organization_id string

Specific organization to unlock the item for (mutually exclusive with org_role)

Responses

201 application/json

Availability rule created successfully
Hide response attributes Show response attributes object
- code integer
- message string
- data object
  
  One commercial unlock for a catalog item: the add-on can be bought or self-activated by a whole hierarchy role OR by one specific organization (exactly one of the two is set). A catalog item without any rule is available to everyone. Availability rules do not affect /auth enforcement on collect.
  
  Hide data attributes Show data attributes object
  
  id string(uuid)
  
  Rule ID
  
  entitlement string
  
  Catalog id the rule applies to
  
  org_role string
  
  Hierarchy role the item is unlocked for (mutually exclusive with organization_id)
  
  Values are distributor, reseller, or customer.
  
  organization_id string
  
  Specific organization the item is unlocked for (mutually exclusive with org_role)
  
  created_by object
  
  Snapshot of the user who created the grant or availability rule
  
  Hide created_by attributes Show created_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.
  
  created_at string(date-time)
400 application/json

Both or neither of org_role/organization_id set, or invalid org_role (must be distributor, reseller or customer)
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

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
409 application/json

Availability rule already exists
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
500 application/json

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

POST /entitlements/catalog/{id}/availability

curl \
 --request POST 'https://api.your-domain.com/api/entitlements/catalog/nsec-blacklist/availability' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"org_role":"reseller","organization_id":"akkbs6x2wo82"}'

Request examples

{
  "org_role": "reseller",
  "organization_id": "akkbs6x2wo82"
}

Response examples (201)

{
  "code": 201,
  "message": "availability rule created successfully",
  "data": {
    "id": "9f1b7c2e-4a3d-4a2b-8f6e-1c2d3e4f5a6b",
    "entitlement": "nsec-blacklist",
    "org_role": "reseller",
    "organization_id": "akkbs6x2wo82",
    "created_by": {
      "user_id": "53h5zxpwu4vc",
      "user_name": "Edoardo Super",
      "organization_id": "lbswt1rxdhbz",
      "organization_name": "Nethesis Italia",
      "channel": "shop"
    },
    "created_at": "2026-07-01T10:00:00Z"
  }
}

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": 409,
  "message": "availability rule already exists",
  "data": {}
}

Response examples (500)

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