{
  "openapi": "3.0.1",
  "x-hideTryItPanel": true,
  "info": {
    "title": "Cortex Cloud Logging and Collection Service Management APIs",
    "version": "1.0.0",
    "description": "The Cloud Logging and Collection Service (CLCS) Management APIs allow you to programmatically manage Next-Generation Firewalls (NGFWs) connected to your CLCS environment.\n\nCLCS enables NGFWs to forward logs directly to Cortex XDR for analysis and threat detection. These APIs provide the ability to list all connected devices and disconnect one or more devices in bulk, replacing the slow, manual UI workflow that only supports one-at-a-time removal.\n\n**Required licenses:** This feature is included with Cortex Cloud Runtime Security or Cortex Cloud Posture Management.\n\n**RBAC permissions:**\n- List connected devices: Data Collection > Data Sources > View\n- Disconnect devices: Data Collection > Data Sources > Edit",
    "contact": {
      "email": "docs-cortex@paloaltonetworks.com",
      "name": "Cortex Documentation Team",
      "url": "https://cortex-docs.paloaltonetworks.com/"
    },
    "license": {
      "name": "Palo Alto Networks",
      "url": "https://www.paloaltonetworks.com/legal-notices/terms-of-use"
    }
  },
  "servers": [
    {
      "url": "https://api-yourfqdn",
      "description": "Your Cortex Cloud tenant API endpoint. Replace `yourfqdn` with your tenant's fully qualified domain name."
    }
  ],
  "tags": [
    {
      "name": "CLCS Management",
      "x-displayName": "CLCS Management",
      "description": "The Cloud Logging and Collection Service (CLCS) Management APIs allow you to programmatically manage Next-Generation Firewalls (NGFWs) connected to your CLCS environment."
    }
  ],
  "paths": {
    "/public_api/v1/clcs/get_connected_devices": {
      "get": {
        "operationId": "getClcsConnectedDevices",
        "summary": "List connected NGFW devices",
        "description": "Returns a list of all Next-Generation Firewalls (NGFWs) currently connected to the Cloud Logging and Collection Service (CLCS) for the authenticated tenant.\n\nEach device in the response includes its serial number (`device_id`), the CSP account ID it belongs to, and the region it is deployed in.\n\n**Required license:** This feature is included with Cortex Cloud Runtime Security or Cortex Cloud Posture Management.\n\n**Required permission:** Data Collection > Data Sources > View",
        "tags": [
          "CLCS Management"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Authorization"
          },
          {
            "$ref": "#/components/parameters/XdrAuthId"
          },
          {
            "$ref": "#/components/parameters/XdrNonce"
          },
          {
            "$ref": "#/components/parameters/XdrTimestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "A list of NGFW devices currently connected to CLCS.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetConnectedDevicesResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Two connected devices",
                    "value": {
                      "reply": {
                        "devices": [
                          {
                            "device_id": "01234567890",
                            "csp_account_id": 123456,
                            "region": "us"
                          },
                          {
                            "device_id": "01234567891",
                            "csp_account_id": 123456,
                            "region": "eu"
                          }
                        ]
                      }
                    }
                  },
                  "empty": {
                    "summary": "No connected devices",
                    "value": {
                      "reply": {
                        "devices": []
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The API key or key ID is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "reply": {
                    "err_code": 401,
                    "err_msg": "Unauthorized",
                    "err_extra": "Invalid API key or key ID."
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key does not have the required permissions to list connected devices. Ensure the key has Data Collection > Data Sources > View permission.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "reply": {
                    "err_code": 403,
                    "err_msg": "Forbidden",
                    "err_extra": "Insufficient permissions. Required: Data Collection > Data Sources > View."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. An unexpected error occurred on the server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "reply": {
                    "err_code": 500,
                    "err_msg": "Internal server error",
                    "err_extra": "An unexpected error occurred. Please try again later."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/public_api/v1/clcs/disconnect_devices": {
      "post": {
        "operationId": "postClcsDisconnectDevices",
        "summary": "Disconnect NGFW devices from CLCS",
        "description": "Disconnects one or more Next-Generation Firewalls (NGFWs) from the Cloud Logging and Collection Service (CLCS). This operation removes the specified devices from CLCS so they no longer forward logs to Cortex XDR.\n\nThe request must specify the target devices by their serial numbers (`device_ids`), along with the CSP account ID and region that the devices belong to. Up to 1000 device IDs can be submitted in a single request.\n\nIf a device ID in the request does not exist or is not connected, it is silently ignored. The response returns only the IDs of devices that were successfully disconnected.\n\n**Required license:** This feature is included with Cortex Cloud Runtime Security or Cortex Cloud Posture Management.\n\n**Required permission:** Data Collection > Data Sources > Edit\n\n**Validation rules:**\n- `device_ids`: Must contain 1–1000 unique alphanumeric strings, each 1–50 characters long.\n- `csp_account_id`: Must be a positive integer.\n- `region`: Must be a non-empty string (not whitespace-only, not a number).",
        "tags": [
          "CLCS Management"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Authorization"
          },
          {
            "$ref": "#/components/parameters/XdrAuthId"
          },
          {
            "$ref": "#/components/parameters/XdrNonce"
          },
          {
            "$ref": "#/components/parameters/XdrTimestamp"
          }
        ],
        "requestBody": {
          "description": "The list of NGFW devices to disconnect, identified by their serial numbers, CSP account ID, and region.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DisconnectDevicesRequest"
              },
              "examples": {
                "disconnect-two-devices": {
                  "summary": "Disconnect two devices",
                  "value": {
                    "request_data": {
                      "device_ids": [
                        "01234567890",
                        "01234567891"
                      ],
                      "csp_account_id": 123456,
                      "region": "us"
                    }
                  }
                },
                "disconnect-single-device": {
                  "summary": "Disconnect a single device",
                  "value": {
                    "request_data": {
                      "device_ids": [
                        "033333333330123"
                      ],
                      "csp_account_id": 789012,
                      "region": "eu"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation completed. The response contains the IDs of devices that were successfully disconnected. Device IDs that were not found are silently omitted from the response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DisconnectDevicesResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Two devices disconnected",
                    "value": {
                      "reply": {
                        "device_ids": [
                          "01234567890",
                          "01234567891"
                        ]
                      }
                    }
                  },
                  "none-found": {
                    "summary": "No matching devices found",
                    "value": {
                      "reply": {
                        "device_ids": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "**Note:** This response describes the intended validation error envelope. The backend currently raises a generic `500 Internal Server Error` for these validation failures pending a fix to wrap Pydantic validation errors in the documented envelope. Treat the structure below as the contract clients should code against.\n\nBad request. The request body failed validation. Common causes include duplicate device IDs, an invalid or zero-value `csp_account_id`, or an empty `region`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "duplicate-ids": {
                    "summary": "Duplicate device IDs",
                    "value": {
                      "reply": {
                        "err_code": 400,
                        "err_msg": "Bad Request",
                        "err_extra": "Duplicate device IDs found: 01234567890"
                      }
                    }
                  },
                  "invalid-account-id": {
                    "summary": "Invalid csp_account_id",
                    "value": {
                      "reply": {
                        "err_code": 400,
                        "err_msg": "Bad Request",
                        "err_extra": "The csp_account_id 0 is invalid. Try again using a number greater than zero."
                      }
                    }
                  },
                  "empty-region": {
                    "summary": "Empty region",
                    "value": {
                      "reply": {
                        "err_code": 400,
                        "err_msg": "Bad Request",
                        "err_extra": "The region is empty. Try again by providing a valid region."
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The API key or key ID provided for this request is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "reply": {
                    "err_code": 401,
                    "err_msg": "Unauthorized",
                    "err_extra": "Invalid API key or key ID."
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The API key does not have the required permissions to disconnect devices. Ensure the key has Data Collection > Data Sources > Edit permission.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "reply": {
                    "err_code": 403,
                    "err_msg": "Forbidden",
                    "err_extra": "Insufficient permissions. Required: Data Collection > Data Sources > Edit."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. An unexpected error occurred while processing the disconnect request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "reply": {
                    "err_code": 500,
                    "err_msg": "Internal server error",
                    "err_extra": "An unexpected error occurred. Please try again later."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Authorization": {
        "name": "Authorization",
        "in": "header",
        "description": "Your Cortex Cloud API key.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "{api_key}"
        }
      },
      "XdrAuthId": {
        "name": "x-xdr-auth-id",
        "in": "header",
        "description": "Your Cortex Cloud API key ID.",
        "required": true,
        "schema": {
          "type": "string",
          "example": "{api_key_id}"
        }
      },
      "XdrNonce": {
        "name": "x-xdr-nonce",
        "in": "header",
        "description": "A unique nonce value used for request authentication.",
        "required": false,
        "schema": {
          "type": "string",
          "example": "0123456789abcdef"
        }
      },
      "XdrTimestamp": {
        "name": "x-xdr-timestamp",
        "in": "header",
        "description": "The Unix timestamp in milliseconds at the time the request is sent.",
        "required": false,
        "schema": {
          "type": "string",
          "example": "1714118400000"
        }
      }
    },
    "schemas": {
      "GetConnectedDevicesResponse": {
        "type": "object",
        "description": "The response envelope for the get connected devices operation.",
        "example": {
          "reply": {
            "devices": [
              {
                "device_id": "01234567890",
                "csp_account_id": 123456,
                "region": "us"
              }
            ]
          }
        },
        "properties": {
          "reply": {
            "type": "object",
            "description": "The response payload containing the list of connected devices.",
            "example": {
              "devices": [
                {
                  "device_id": "01234567890",
                  "csp_account_id": 123456,
                  "region": "us"
                }
              ]
            },
            "properties": {
              "devices": {
                "type": "array",
                "description": "A list of NGFW devices currently connected to CLCS. Returns an empty array if no devices are connected.",
                "example": [
                  {
                    "device_id": "01234567890",
                    "csp_account_id": 123456,
                    "region": "us"
                  }
                ],
                "items": {
                  "$ref": "#/components/schemas/ConnectedDevice"
                }
              }
            },
            "required": [
              "devices"
            ]
          }
        },
        "required": [
          "reply"
        ]
      },
      "ConnectedDevice": {
        "type": "object",
        "description": "Represents a single NGFW device connected to CLCS.",
        "example": {
          "device_id": "01234567890",
          "csp_account_id": 123456,
          "region": "us"
        },
        "properties": {
          "device_id": {
            "type": "string",
            "description": "The unique serial number of the NGFW device.",
            "example": "01234567890"
          },
          "csp_account_id": {
            "type": "integer",
            "description": "The CSP (Cloud Service Provider) account ID that the device belongs to.",
            "example": 123456
          },
          "region": {
            "type": "string",
            "description": "The cloud region where the device is deployed.",
            "example": "us"
          }
        },
        "required": [
          "device_id",
          "csp_account_id",
          "region"
        ]
      },
      "DisconnectDevicesRequest": {
        "type": "object",
        "description": "The request body for disconnecting NGFW devices from CLCS.",
        "example": {
          "request_data": {
            "device_ids": [
              "01234567890",
              "01234567891"
            ],
            "csp_account_id": 123456,
            "region": "us"
          }
        },
        "properties": {
          "request_data": {
            "type": "object",
            "description": "The parameters specifying which devices to disconnect.",
            "example": {
              "device_ids": [
                "01234567890",
                "01234567891"
              ],
              "csp_account_id": 123456,
              "region": "us"
            },
            "properties": {
              "device_ids": {
                "type": "array",
                "description": "A list of NGFW device serial numbers to disconnect. Must contain 1–1000 unique alphanumeric strings, each between 1 and 50 characters long.",
                "minItems": 1,
                "maxItems": 1000,
                "example": [
                  "01234567890",
                  "01234567891"
                ],
                "items": {
                  "type": "string",
                  "description": "An alphanumeric NGFW device serial number, between 1 and 50 characters.",
                  "minLength": 1,
                  "maxLength": 50,
                  "pattern": "^[a-zA-Z0-9]+$",
                  "example": "01234567890"
                }
              },
              "csp_account_id": {
                "type": "integer",
                "description": "The CSP (Cloud Service Provider) account ID that the devices belong to. Must be a positive integer.",
                "minimum": 1,
                "example": 123456
              },
              "region": {
                "type": "string",
                "description": "The cloud region where the devices are deployed. Must be a non-empty string (not whitespace-only, not a numeric value).",
                "minLength": 1,
                "example": "us"
              }
            },
            "required": [
              "device_ids",
              "csp_account_id",
              "region"
            ]
          }
        },
        "required": [
          "request_data"
        ]
      },
      "DisconnectDevicesResponse": {
        "type": "object",
        "description": "The response envelope for the disconnect devices operation.",
        "example": {
          "reply": {
            "device_ids": [
              "01234567890",
              "01234567891"
            ]
          }
        },
        "properties": {
          "reply": {
            "type": "object",
            "description": "The response payload containing the IDs of successfully disconnected devices.",
            "example": {
              "device_ids": [
                "01234567890",
                "01234567891"
              ]
            },
            "properties": {
              "device_ids": {
                "type": "array",
                "description": "The serial numbers of devices that were successfully disconnected. Device IDs from the request that were not found are silently omitted.",
                "example": [
                  "01234567890",
                  "01234567891"
                ],
                "items": {
                  "type": "string",
                  "description": "An alphanumeric NGFW device serial number.",
                  "example": "01234567890"
                }
              }
            },
            "required": [
              "device_ids"
            ]
          }
        },
        "required": [
          "reply"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "A standard error response envelope returned when a request fails.",
        "example": {
          "reply": {
            "err_code": 400,
            "err_msg": "Bad Request",
            "err_extra": "Duplicate device IDs found: 01234567890"
          }
        },
        "properties": {
          "reply": {
            "type": "object",
            "description": "The error payload containing the status code, message, and additional detail.",
            "example": {
              "err_code": 400,
              "err_msg": "Bad Request",
              "err_extra": "Duplicate device IDs found: 01234567890"
            },
            "properties": {
              "err_code": {
                "type": "integer",
                "description": "The HTTP status code of the error.",
                "example": 400
              },
              "err_msg": {
                "type": "string",
                "description": "A short description of the error.",
                "example": "Bad Request"
              },
              "err_extra": {
                "type": "string",
                "description": "Additional detail about the error, including remediation guidance where applicable.",
                "example": "Duplicate device IDs found: 01234567890"
              }
            },
            "required": [
              "err_code",
              "err_msg"
            ]
          }
        },
        "required": [
          "reply"
        ]
      }
    }
  }
}