Introduction

The GYTPOL Customer API enables organizations to integrate GYTPOL's configuration security intelligence directly into their systems. Through this API, users can automate the retrieval of misconfiguration data, assess impact across devices, and trigger remediation actions without manual intervention. This guide provides a comprehensive reference for interacting with the API.

Overview

This guide is based on the OpenAPI 3.0 specification and outlines all endpoints available for use. Each section includes request types, endpoint paths, descriptions, required parameters, request/response schemas, and example usage notes.

For the full OpenAPI documentation, visit: GYTPOL Customer API Documentation

Base URL

The Base URL variable in both the scripts and the examples provided below should be set to your GYTPOL URL.

EU customers:
https://your-tenant.eu.cloud.gytpol.com/customer_api/v1/
US customers:
https://your-tenant.us.cloud.gytpol.com/customer_api/v1/

API Port

There is no need to specify a port, as the URL utilizes port 443 by default.

HTTP Return Codes

200 OK – The request was successful.

400 Bad Request – The request was invalid or malformed (details will be provided in the response).

401 Unauthorized – Authentication failed; the API key is missing or incorrect.

429 Too Many Requests – The API rate limit has been exceeded.

500 Internal Server Error – An unexpected server error occurred.

Authentication

All endpoints require authentication via an API key. If you don’t have one, please contact your GYTPOL Technical Account Manager.
Include the API key in the request header as follows:

x-api-key: <your_api_key>

Remediation API Endpoints

This section lists all core Remediation API endpoints with simple examples (no pagination cursor).
For advanced usage and full schemas, see the official developer documentation.

Get Available Filters

GET /filters
Returns the list of filter values available for use in queries (e.g., groups, OS, labels, etc.).
View in API Docs

Basic Example:
A curl command for retrieving all known operating system values currently in your GYTPOL for filtering purposes.

Method: GET
URL: /filters?type=os&limit=1000

curl -X GET "https://<your-tenant>.gytpol.com/customer_api/v1/filters?type=os&limit=1000" -H "x-api-key: <your_api_key>"

Sample Output:

{
  "data": ["Windows 10", "Windows 11", "Windows Server 2019"],
  "nextCursor": ""
}

Get All Remediable Misconfigurations

POST /misconfigurations
Fetches a list of active and remediable misconfigurations currently detected in your environment.
View in API Docs

Basic Example:
A curl command for retrieving all remediable misconfigurations without any filters.

Method: POST
URL: /misconfigurations?limit=1000

curl -X POST "https://<your-tenant>.gytpol.com/customer_api/v1/misconfigurations?limit=1000" -H "x-api-key: <your_api_key>" -H "Content-Type: application/json" -d "{}"

Sample Output:

{
  "data": [
    {
      "misconfigurationId": "gytDisableSMBv1",
      "title": "Disable SMBv1 (Windows)",
      "description": "Ensures SMBv1 is disabled to mitigate security risks.",
      "severity": "high",
      "alertsCount": 34,
      "devicesCount": 18,
      "instancesCount": 1,
      "instanceValueCategory": "state",
      "scores": {
        "cvss": 7.5
      }
    }
  ],
  "nextCursor": ""
}

List Misconfiguration Instances

POST /misconfigurations/instances
Returns all known instance values for a specific misconfiguration.
View in API Docs

Basic Example:
A curl command for retrieving all version instances (e.g., Java versions) for a specific misconfiguration.

Method: POST
URL: /misconfigurations/instances?misconfigurationId=gytJavaVersion&limit=1000

curl -X POST "https://<your-tenant>.gytpol.com/customer_api/v1/misconfigurations/instances?misconfigurationId=gytJavaVersion&limit=1000" -H "x-api-key: <your_api_key>" -H "Content-Type: application/json" -d "{}"

Sample Output:

{
  "data": [
    {
      "instanceId": "java8u311",
      "devicesCount": 10,
      "alertsCount": 10
    },
    {
      "instanceId": "java11.0.2",
      "devicesCount": 5,
      "alertsCount": 5
    }
  ],
  "nextCursor": "",
  "instanceValueCategory": "version"
}

List Affected Devices

POST /misconfigurations/applicable_devices
Fetches the list of devices affected by a specific misconfiguration.
View in API Docs

Basic Example:
A curl command for retrieving all devices currently affected by the misconfiguration gytDisableSMBv1.

Method: POST
URL: /misconfigurations/applicable_devices?misconfigurationId=gytDisableSMBv1&limit=1000

curl -X POST "https://<your-tenant>.gytpol.com/customer_api/v1/misconfigurations/applicable_devices?misconfigurationId=gytDisableSMBv1&limit=1000" -H "x-api-key: <your_api_key>" -H "Content-Type: application/json" -d "{}"

Sample Output:

{
  "data": [
    {
      "deviceId": 1234,
      "device": "LAPTOP-1",
      "ip": "192.168.1.5",
      "mac": "00:11:22:33:44:55",
      "os": "Windows 10",
      "instanceId": "enabled"
    }
  ],
  "title": "Disable SMBv1 (Windows)",
  "severity": "high",
  "desc": "Ensures SMBv1 is disabled to mitigate security risks.",
  "misconfigurationId": "gytDisableSMBv1",
  "instanceValueCategory": "state",
  "nextCursor": ""
}

Schedule a Remediation Action

POST /action/schedule
Schedules remediation for a selected misconfiguration on filtered devices.
View in API Docs

Basic Example:
A curl command for scheduling remediation of SMBv1 for all devices in group ID 1.

Method: POST
URL: /action/schedule?misconfigurationId=gytDisableSMBv1

curl -X POST "https://<your-tenant>.gytpol.com/customer_api/v1/action/schedule?misconfigurationId=gytDisableSMBv1" -H "x-api-key: <your_api_key>" -H "Content-Type: application/json" -d "{\"filter\": {\"groupId\": 1}, \"remark\": \"Disabling SMBv1 via API\"}"

Sample Output:

{
  "actionId": 9876
}

Check Remediation Status

GET /action/status
Retrieves the current status of a previously scheduled remediation action.
View in API Docs

Basic Example:
A curl command for checking progress of remediation action 9876.

Method: GET
URL: /action/status?actionId=9876&limit=1000

curl -X GET "https://<your-tenant>.gytpol.com/customer_api/v1/action/status?actionId=9876&limit=1000" -H "x-api-key: <your_api_key>"

Sample Output:

{
  "actionId": 9876,
  "state": "completed",
  "actionProgress": {
    "total": 10,
    "success": 9,
    "failed": 1,
    "pending": 0,
    "cancelled": 0,
    "reverted": 0,
    "reverting": 0,
    "revertFailed": 0,
    "revertCancelled": 0
  },
  "data": [
    {
      "deviceId": 1234,
      "device": "LAPTOP-1",
      "instanceId": "enabled",
      "state": "success"
    }
  ],
  "remark": "Disabling SMBv1 via API",
  "nextCursor": ""
}

Windows PowerShell Script Example:
Retrieve Top Impact Misconfiguration with Instances and Devices
(Remediation Example Included, Not Executed)

# === GYTPOL API Setup ===
$API_KEY = Read-Host "Enter your API Key"
$BASE_URL = Read-Host "Enter your Base URL (e.g., https://your.tenant.gytpol.com/customer_api/v1)"
$EXPORT_PATH = Read-Host "Enter the export path for the JSON files (e.g., C:\GYTPOL\Export)"
$Headers = @{ "x-api-key" = $API_KEY }

# Ensure export directory exists
if (-not (Test-Path $EXPORT_PATH)) {
    New-Item -Path $EXPORT_PATH -ItemType Directory -Force | Out-Null
}

# === Step 1: Get Filters
Write-Host "=== Step 1: Get Filters"
$filters = Invoke-RestMethod -Method GET -Uri "$BASE_URL/filters?type=os&limit=1000" -Headers $Headers
$filters | ConvertTo-Json | Out-File -Encoding utf8 -FilePath (Join-Path $EXPORT_PATH "filters_os.json")
Write-Host "filters_os.json saved"

# === Step 2: Get Misconfigurations
Write-Host "=== Step 2: Get Misconfigurations"
$misconfigs = Invoke-RestMethod -Method POST -Uri "$BASE_URL/misconfigurations?limit=1000" -Headers $Headers -Body '{}' -ContentType "application/json"
$misconfigs | ConvertTo-Json -Depth 5 | Out-File -Encoding utf8 -FilePath (Join-Path $EXPORT_PATH "misconfigurations.json")
Write-Host "misconfigurations.json saved"

# Extract best misconfigurationId (based on alertsCount * devicesCount)
$top = $misconfigs.data | Sort-Object { $_.alertsCount * $_.devicesCount } -Descending | Select-Object -First 1
$MISCONFIG_ID = $top.misconfigurationId
Write-Host "Using misconfigurationId: $MISCONFIG_ID"

# === Step 3: List Instances
Write-Host "=== Step 3: List Instances"
$instances = Invoke-RestMethod -Method POST -Uri "$BASE_URL/misconfigurations/instances?misconfigurationId=$MISCONFIG_ID&limit=1000" `
    -Headers $Headers -Body '{}' -ContentType "application/json"
$instances | ConvertTo-Json -Depth 5 | Out-File -Encoding utf8 -FilePath (Join-Path $EXPORT_PATH "instances.json")
Write-Host "instances.json saved"

# === Step 4: List Affected Devices
Write-Host "=== Step 4: List Affected Devices"
$devices = Invoke-RestMethod -Method POST -Uri "$BASE_URL/misconfigurations/applicable_devices?misconfigurationId=$MISCONFIG_ID&limit=1000" `
    -Headers $Headers -Body '{}' -ContentType "application/json"
$devices | ConvertTo-Json -Depth 5 | Out-File -Encoding utf8 -FilePath (Join-Path $EXPORT_PATH "affected_devices.json")
Write-Host "affected_devices.json saved"

# === Skipping Step 5: Schedule Remediation
Write-Host "=== Skipping Step 5: Schedule Remediation"
Write-Host "=== Skipping Step 6: Check Remediation Status"

<#
# === Step 5: Schedule Remediation
Write-Host "=== Step 5: Schedule Remediation"
$body = @{ remark = "Scheduled via PowerShell" } | ConvertTo-Json -Compress
$schedule = Invoke-RestMethod -Method POST -Uri "$BASE_URL/action/schedule?misconfigurationId=$MISCONFIG_ID" `
    -Headers $Headers -Body $body -ContentType "application/json"
$schedule | ConvertTo-Json -Depth 5 | Out-File -Encoding utf8 -FilePath (Join-Path $EXPORT_PATH "schedule.json")
Write-Host "schedule.json saved"

# Extract actionId
$ACTION_ID = $schedule.actionId
Write-Host "Using actionId: $ACTION_ID"

# === Step 6: Check Remediation Status
Write-Host "=== Step 6: Check Remediation Status"
$status = Invoke-RestMethod -Method GET -Uri "$BASE_URL/action/status?actionId=$ACTION_ID&limit=1000" -Headers $Headers
$status | ConvertTo-Json -Depth 5 | Out-File -Encoding utf8 -FilePath (Join-Path $EXPORT_PATH "action_status.json")
Write-Host "action_status.json saved"
#>

Write-Host "=== Done ==="
Write-Host "=== JSON files saved in: $EXPORT_PATH ==="
Write-Host "=== See Commented Out Step 5 and 6 ==="

Input parameters (via `Read-Host`) explained:

Parameter Name	Description	Example Input

Parameter Name	Description	Example Input
`API_KEY`	The API key required to authenticate against the GYTPOL Customer API. You can obtain it from the your Technical Account Manager.	`aBc123xYz789`
`BASE_URL`	The base URL of the GYTPOL Customer API. This is tenant-specific. Typically ends in `/customer_api/v1`.	`https://your-tenant.region.cloud.gytpol.com/customer_api/v1`
`EXPORT_PATH`	The local directory path where you want to save the JSON output files. This folder will be created if it does not exist.	`C:\Temp\GYTPOL_Export`

Action API Endpoints

This section lists all core Action API endpoints with simple examples (no pagination cursor).
For advanced usage and full schemas, see the official developer documentation.

For more information, visit: GYTPOL Customer API Documentation

Get Actions

GET /actions
Retrieves the list of actions (e.g., remediations, reverts) created or modified in the last 3 months.
View in API Docs

Basic Example:
A curl command to list all actions with pagination (limit 1000):

Method: GET
URL: /actions?limit=1000

curl -X GET "https://<your-tenant>.gytpol.com/customer_api/v1/actions?limit=1000" -H "x-api-key: <your_api_key>"

Sample Output:

{
    "data": [
        {
            "id": 662,
            "state": "done",
            "actionType": "generic",
            "actionDatum": "restart",
            "applyScheme": "asap",
            "afterTime": 0,
            "timezone": 180,
            "weekDay": null,
            "window": 0,
            "lastChangedBy": "{\"Title\": \"Tester\", \"Groups\": null, \"UserName\": \"Tester@gytpol.com\", \"DisplayName\": \"Tester\"}",
            "latestChange": "2025-05-21T12:34:02.179861Z",
            "exclusionStart": null,
            "exclusionWeekDay": null,
            "exclusionWindow": null,
            "expiration": null,
            "progress": {
                "total": 1,
                "pending": 0,
                "success": 1,
                "reverting": 0,
                "reverted": 0,
                "cancelled": 0,
                "failed": 0,
                "revertFailed": 0,
                "revertCancelled": 0
            },
            "devices": 1
        }
    ],
    "nextCursor": null
}

Get Action Log

GET /action/log
Retrieves the full log associated with a specific remediation or revert action.
View in API Docs

Basic Example:
A curl command to retrieve the log for action ID 662.

Method: GET
URL: /action/log?actionId=662

curl -X GET "https://<your-tenant>.gytpol.com/customer_api/v1/action/log?actionId=662" -H "x-api-key: <your_api_key>"

Sample Output:

{
    "data": [
        {
            "byUser": {
                "UserName": "(System)",
                "DisplayName": "",
                "Title": ""
            },
            "date": "2025-06-04T16:00:35.938193Z",
            "operation": "done",
            "notes": ""
        },
        {
            "byUser": {
                "UserName": "tester@gytpol.com",
                "DisplayName": "Tester",
                "Title": "Tester"
            },
            "date": "2025-05-21T12:34:02.179861Z",
            "operation": "create",
            "notes": ""
        }
    ],
    "nextCursor": null
}

Check Action Status

GET /action/status
Retrieves the current status of a previous action.
View in API Docs

Basic Example:
A curl command for checking progress of remediation action 662.

Method: GET
URL: /action/status?actionId=662&limit=1000

curl -X GET "https://<your-tenant>.gytpol.com/customer_api/v1/action/status?actionId=9876&limit=1000" -H "x-api-key: <your_api_key>"

Sample Output:

{
    "actionId": 662,
    "state": "done",
    "actionType": "generic",
    "actionDatum": "restart",
    "applyScheme": "asap",
    "afterTime": 0,
    "timezone": 180,
    "weekDay": null,
    "window": 0,
    "actionProgress": {
        "total": 1,
        "pending": 0,
        "success": 1,
        "reverting": 0,
        "reverted": 0,
        "cancelled": 0,
        "failed": 0,
        "revertFailed": 0,
        "revertCancelled": 0
    },
    "devices": 1,
    "data": [
        {
            "deviceId": 166,
            "device": "NITAY-LATITUDE-5440",
            "instanceId": null,
            "state": "Success"
        }
    ],
    "nextCursor": null
}

API Guide: Modern Endpoints (v2.0 Enhanced)

Introduction

Overview

Base URL

API Port

HTTP Return Codes

Authentication

Remediation API Endpoints

Get Available Filters

Get All Remediable Misconfigurations

List Misconfiguration Instances

List Affected Devices

Schedule a Remediation Action

Check Remediation Status

Windows PowerShell Script Example:Retrieve Top Impact Misconfiguration with Instances and Devices(Remediation Example Included, Not Executed)

Input parameters (via Read-Host) explained:

Action API Endpoints

Get Actions

Get Action Log

Check Action Status

Windows PowerShell Script Example:
Retrieve Top Impact Misconfiguration with Instances and Devices
(Remediation Example Included, Not Executed)

Input parameters (via `Read-Host`) explained: