Skip to main content

API Documentation

This document provides information about the SecuritySnares API endpoints. The API allows you to interact with the SecuritySnares platform programmatically, enabling you to manage agents, view alerts, and more.

Table of Contents​

Authentication​

Unless noted otherwise, API requests must be authenticated using an API Key with Bearer Token authentication. Some web-portal command endpoints require an authenticated dashboard session and specific user permissions instead of API-key authentication; those endpoints are called out separately.

  • Authentication Method: Bearer Token
  • Header: Authorization: Bearer <Your API Key>
  • Example: 
    Authorization: Bearer your_api_key_here

API Keys can be created and managed through the SecuritySnares dashboard. Each API key is associated with an organization and provides access to that organization's resources.

Example cURL Request:

curl -X GET https://api.securitysnares.com/agents \
  -H "Authorization: Bearer your_api_key_here"

Getting Your API Key:

  1. Log in to the SecuritySnares dashboard
  2. Navigate to your organization settings
  3. Go to the API Keys section
  4. Create a new API key or use an existing one
  5. Copy the API key value to use in your requests

Entity IDs​

Every object in the SecuritySnares platform — including Users, Organizations, Agents, and Alerts — has an entity_id field. This is a unique identifier for that object and is used to reference it across API endpoints.

Organizations​

Get User Organizations​

Get the list of organizations the authenticated user belongs to. For MSSP users, this includes their own MSSP organization as well as any client organizations they manage.

  • URL: /user/organizations

  • Method: GET

  • Auth Required: Yes

  • Example Request:

    curl -X GET https://api.securitysnares.com/user/organizations \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: Returns an array of organization objects. The example below shows an MSSP user who has access to their own MSSP organization and a managed client organization. 
      {
        "success": true,
        "data": [
          {
            "name": "Acme Security",
            "contact_email": "admin@acmesecurity.com",
            "contact_phone": "(555) 123-4567",
            "notification_preferences": "email",
            "created_by_id": "auth0|637d744fc0f8aabff64a6dc3",
            "global_agent_settings": {
              "alertNotificationType": "dialog"
            },
            "organization_type": "mssp",
            "managed_by": "a1b2c3d4e5f6789012345678901234ab",
            "slack_hook_url": null,
            "allowed_login_ips": null,
            "entity_id": "b07e0e7abe68484e88d37efa7621c8af",
            "version": "0bc4409c29be42c18edc787742d5e945",
            "active": 1,
            "latest": 1,
            "role": "admin"
          },
          {
            "name": "Acme Security - Client Site",
            "contact_email": "client@acmeclient.com",
            "contact_phone": "",
            "notification_preferences": null,
            "created_by_id": "c2d3e4f5a6b7890123456789012345cd",
            "global_agent_settings": null,
            "organization_type": "client",
            "managed_by": "b07e0e7abe68484e88d37efa7621c8af",
            "slack_hook_url": null,
            "allowed_login_ips": null,
            "entity_id": "d4e5f6a7b8c9012345678901234567ef",
            "version": "1ab2cd3ef4567890abcdef1234567890",
            "active": 1,
            "latest": 1,
            "role": "mssp_admin",
            "is_managed": 1
          }
        ]
      }

    Response Fields:

    FieldTypeDescription
    namestringOrganization name
    contact_emailstringPrimary contact email address
    contact_phonestring | nullContact phone number
    notification_preferencesstring | nullNotification preference setting (e.g., "email", "slack")
    created_by_idstringID of the user who created the organization
    global_agent_settingsobject | nullDefault agent settings applied to all agents in the organization (see below)
    organization_typestring | nullType of organization: "superadmin", "mssp", or "client"
    managed_bystring | nullEntity ID of the MSSP organization managing this organization
    slack_hook_urlstring | nullSlack webhook URL for alert notifications
    allowed_login_ipsstring | nullAllowed IP addresses for login
    entity_idstringUnique identifier for the organization
    versionstringVersion identifier used for optimistic concurrency control
    activeintegerWhether the organization is active (1 = active)
    latestintegerWhether this is the latest version of the record (1 = latest)
    rolestringThe authenticated user's role in this organization (e.g., "admin", "mssp_admin")
    is_managedintegerOnly present on client organizations managed by the user's MSSP (1 = managed)

    global_agent_settings Fields:

    FieldTypeDescription
    alertNotificationMessageTemplatestringCustom message displayed to end users when an alert is triggered
    alertNotificationTypestringHow alerts are displayed on endpoints: "dialog", "tray", or "none"
    alert_only_modebooleanOrganization fleet posture (true = Alert-Only by default, false = Protect by default)

Create Organization​

Create a new organization with an initial user.

  • URL: /organization

  • Method: POST

  • Auth Required: Yes

  • Request Body:

    {
      "organization_name": "Acme Corporation",
      "organization_type": "client",
      "managed_by": "a1b2c3d4e5f6789012345678901234ab",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@acmecorp.com",
      "contact_phone": "(555) 123-4567"
    }

    Request Fields:

    FieldRequiredDescription
    organization_nameYesName of the new organization
    organization_typeYesType of organization — typically "client" or "mssp"
    managed_byNoEntity ID of the MSSP organization managing this client (for client organizations)
    first_nameYesFirst name of the initial admin user
    last_nameYesLast name of the initial admin user
    emailYesEmail address for the initial admin user
    contact_phoneNoContact phone number for the organization

  • Example Request:

    curl -X POST https://api.securitysnares.com/organization \
      -H "Authorization: Bearer your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{
        "organization_name": "Acme Corporation",
        "organization_type": "client",
        "managed_by": "a1b2c3d4e5f6789012345678901234ab",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@acmecorp.com"
      }'

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "message": "Organization created successfully.",
        "data": {
          "name": "Acme Corporation",
          "contact_email": "jane.smith@acmecorp.com",
          "contact_phone": null,
          "notification_preferences": null,
          "created_by_id": "auth0|637d744fc0f8aabff64a6dc3",
          "global_agent_settings": null,
          "organization_type": "client",
          "managed_by": "a1b2c3d4e5f6789012345678901234ab",
          "slack_hook_url": null,
          "allowed_login_ips": null,
          "entity_id": "c7db33b4ad764874afa8f08e3926c4b6",
          "version": "5bf371eb13344d9ca9e06f2d7cdc1dbb",
          "active": true,
          "latest": true
        }
      }

    Response Fields:

    FieldTypeDescription
    namestringOrganization name
    contact_emailstringContact email (set from the initial user's email)
    contact_phonestring | nullContact phone number
    notification_preferencesstring | nullNotification preference setting
    created_by_idstringID of the user who created the organization
    global_agent_settingsobject | nullDefault agent settings (null for new organizations)
    organization_typestringType of organization: "client" or "mssp"
    managed_bystring | nullEntity ID of the managing MSSP organization
    slack_hook_urlstring | nullSlack webhook URL for alert notifications
    allowed_login_ipsstring | nullAllowed IP addresses for login
    entity_idstringUnique identifier for the new organization
    versionstringVersion identifier used for optimistic concurrency control
    activebooleanWhether the organization is active
    latestbooleanWhether this is the latest version of the record

  • Error Response:

    • Code: 400
    • Content: 
      {
        "success": false,
        "message": "first_name is required."
      }

Get Organization Details​

Get details about a specific organization.

  • URL: /organization/{organization_id}

  • Method: GET

  • Auth Required: Yes

  • URL Parameters:

    FieldRequiredDescription
    organization_idYesThe unique entity ID of the organization

  • Example Request:

    curl -X GET https://api.securitysnares.com/organization/b07e0e7abe68484e88d37efa7621c8af \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "b07e0e7abe68484e88d37efa7621c8af",
          "name": "Organization Name",
          "contact_email": "contact@example.com",
          "contact_phone": "(123) 456-7890",
          "notification_preferences": "email",
          "organization_type": "client"
        }
      }

Agents​

View Protection Mode and Fleet Posture​

Use these endpoints to view the current Alert-Only or Protect state:

  • GET /user/organizations or GET /organization/{organization_id} returns global_agent_settings.alert_only_mode.
    • true means the organization default is Alert-Only.
    • false means the organization default is Protect.
  • GET /agents returns each agent's current alert_only value.
    • 1 or true means the agent is currently in Alert-Only.
    • 0 or false means the agent is currently in Protect.
  • GET /agents also returns hold fields when present. Held agents are marked with hold, held_by, and held_at; the backend poll-time fleet-policy reconciliation skips held agents.

Get All Agents​

Get a list of all agents for an organization.

  • URL: /agents

  • Method: GET

  • Auth Required: Yes

  • Example Request:

    curl -X GET https://api.securitysnares.com/agents \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "hostid": "FA163EFBAD0D",
            "name": "Agent 100",
            "organization_id": "4a01ee2047444639993cb978cf249dcc",
            "agent_version": "2.0.1.0",
            "polling_interval": 60,
            "hostname": "WIN-SERVER01",
            "os_type": "WIN",
            "os_platform": "x64",
            "os_version_number": "Microsoft Windows NT 10.0.26100.0",
            "os_version_detail": "Windows Server 2022",
            "alert_notification_type": null,
            "alert_notification_message_template": null,
            "alert_only": 0,
            "driver_enabled": 1,
            "log_level": {
              "corelib": 1
            },
            "created_on": "2026-02-01T02:26:53+00:00",
            "safe_mode": 0,
            "hold": 0,
            "held_by": null,
            "held_at": null,
            "entity_id": "12939172759f4b6bb1b291078e1b436e",
            "version": "fdf6ae4a8f464171813c6c9ebb986547",
            "active": 1,
            "latest": 1,
            "unseen_crash_logs": 0,
            "unseen_suspicious_processes": 0,
            "last_poll": "2026-02-17T02:31:36+00:00"
          }
        ]
      }

    Response Fields:

    FieldTypeDescription
    hostidstring | nullHardware-based host identifier (MAC address)
    namestringDisplay name of the agent
    organization_idstringID of the organization this agent belongs to
    agent_versionstringInstalled agent version
    polling_intervalintegerHow often the agent polls the server, in seconds
    hostnamestringHostname of the machine running the agent
    os_typestringOperating system type (e.g., "WIN")
    os_platformstringPlatform architecture (e.g., "x64")
    os_version_numberstringFull OS version string
    os_version_detailstringHuman-readable OS version (e.g., "Windows Server 2022", "Windows 11")
    alert_notification_typestring | nullPer-agent alert notification type override ("dialog", "tray", "none")
    alert_notification_message_templatestring | nullPer-agent custom alert message override
    alert_onlyinteger | nullWhether the agent is in alert-only mode (1 = alert only, 0 = block and alert)
    driver_enabledintegerWhether the kernel driver is enabled (1 = enabled)
    log_levelobjectLogging configuration (e.g., {"corelib": 1})
    created_onstringISO 8601 timestamp of when the agent was created
    safe_modeinteger | nullWhether the agent is running in safe mode (1 = safe mode)
    holdinteger | boolean | nullWhether the agent is marked as a hold exception (1/true = held)
    held_bystring | nullEntity ID of the user who placed the agent on hold
    held_atstring | nullUTC timestamp of when the agent was placed on hold
    entity_idstringUnique identifier for the agent
    versionstringVersion identifier used for optimistic concurrency control
    activeintegerWhether the agent is active (1 = active)
    latestintegerWhether this is the latest version of the record (1 = latest)
    unseen_crash_logsintegerNumber of crash logs not yet viewed
    unseen_suspicious_processesintegerNumber of suspicious process reports not yet viewed
    last_pollstringISO 8601 timestamp of the agent's last check-in

Set Agent Hold​

Set or release a per-agent hold exception. A hold is a server-side flag used by the fleet protection policy workflow.

Portal session endpoint

This endpoint is used by the web portal. In the current backend, it requires an authenticated dashboard session and the manage_agents permission; it is not authenticated with a bearer API key.

  • URL: /agents/{entity_id}/hold

  • Method: PUT

  • Auth Required: Yes, dashboard session with manage_agents

  • URL Parameters:

    FieldRequiredDescription
    entity_idYesUnique identifier of the agent

  • Request Body:

    {
      "hold": true
    }

    Request Fields:

    FieldRequiredDescription
    holdYestrue places the agent on hold; false releases the hold

  • Success Response:

    • Code: 200
    • Content: Returns the updated agent object.

Commands​

Set Fleet Protection Posture​

Set the organization-wide Alert-Only or Protect posture. The web portal uses this endpoint when an administrator applies the Protection Policy setting.

Portal session endpoint

This endpoint is used by the web portal. In the current backend, it requires an authenticated dashboard session and the manage_agents permission; it is not authenticated with a bearer API key.

  • URL: /command/organization

  • Method: POST or PUT

  • Auth Required: Yes, dashboard session with manage_agents

  • Request Body:

    {
      "command_type": "SET_ALERT_ONLY",
      "data": [
        {
          "key": "enabled",
          "value": false
        }
      ]
    }

    Request Fields:

    FieldRequiredDescription
    command_typeYesUse SET_ALERT_ONLY for Alert-Only or Protect posture changes
    data[].keyYesUse enabled
    data[].valueYesfalse sets Protect mode; true sets Alert-Only mode
    mfaConditionalRequired when changing from Protect to Alert-Only; not required when changing from Alert-Only to Protect

  • Behavior:

    • Updates global_agent_settings.alert_only_mode on the organization.
    • Creates pending SET_ALERT_ONLY commands for agents in the organization.
    • Agents apply the change on their next poll/check-in.

  • Success Response:

    • Code: 200
    • Content: Returns the pending command objects created for the organization.

Alerts​

Get Alerts​

Get a list of all alerts for an organization.

  • URL: /alerts

  • Method: GET

  • Auth Required: Yes

  • Query Parameters:

    • agent_id (optional): Filter alerts by agent ID
    • dismissed (optional): Filter by dismissed status (true/false)

  • Example Request:

    curl -X GET https://api.securitysnares.com/alerts \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "organization_id": "4a01ee2047444639993cb978cf249dcc",
            "agent_id": "52b2134021d1438ab8a8ed43d870cb84",
            "agent_version": "2.0.1.0",
            "hostname": "WIN-SERVER01",
            "ip_address": "192.168.1.100",
            "mac_address": "FA163EEB5102",
            "process_id": "12776",
            "process_name": "babax.exe",
            "process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
            "process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
            "process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
            "process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
            "parent_process_id": "10404",
            "parent_process_name": "babax.exe",
            "parent_process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
            "parent_process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
            "parent_process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
            "parent_process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
            "write_attempted_file_path": "C:\\Users\\Administrator\\Documents\\tmp\\test_0_1.doc.enc",
            "write_attempted_file_size": 0,
            "write_attempted_file_md5": "9451bcb01117e96d3aec4f982248037d",
            "write_attempted_file_sha1": "7a99353f9ae38262a26ea0150fd005e9841d8f5c",
            "write_attempted_file_sha256": "423e6cac44e407ba7f7a568748b58cd63d9a3904b2a5be181c4401b84910e59b",
            "suspicious_process_filename": "d8434931-d98d-4321-9c6e-50af73fa8c80.zip",
            "action_taken": "killed",
            "ai_analysis": "{\"summary\": \"AI-Enhanced Analysis: The process attempted to write a file with an '.enc' extension, indicative of file encryption typical in ransomware.\", \"severity\": 90}",
            "dismissal_reason": null,
            "script_info": null,
            "exfiltrate_info": null,
            "executing_username": "WIN-SERVER01\\Administrator",
            "executing_user_sid": "S-1-5-21-2928516678-962286722-4132840994-500",
            "alert_time": "2026-02-26T19:12:04+00:00",
            "is_wipersnare": 0,
            "organization_name": null,
            "agent_name": null,
            "alert_count": null,
            "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
            "version": "9c55253849f14c35b17d529fab8b7966",
            "active": 1,
            "latest": 1,
            "changed_on": "2026-02-26T19:12:04+00:00"
          }
        ]
      }

    Response Fields:

    FieldTypeDescription
    organization_idstringID of the organization this alert belongs to
    agent_idstringID of the agent that generated the alert
    agent_versionstringVersion of the agent at the time of the alert
    hostnamestringHostname of the machine where the alert occurred
    ip_addressstringIP address of the machine
    mac_addressstringMAC address of the machine
    process_idstringPID of the suspicious process
    process_namestringName of the suspicious process
    process_file_pathstringFull file path of the suspicious process
    process_md5stringMD5 hash of the suspicious process
    process_sha1stringSHA-1 hash of the suspicious process
    process_sha256stringSHA-256 hash of the suspicious process
    parent_process_idstringPID of the parent process
    parent_process_namestringName of the parent process
    parent_process_file_pathstringFull file path of the parent process
    parent_process_md5stringMD5 hash of the parent process
    parent_process_sha1stringSHA-1 hash of the parent process
    parent_process_sha256stringSHA-256 hash of the parent process
    write_attempted_file_pathstringFile path the process attempted to write to
    write_attempted_file_sizeintegerSize of the file being written
    write_attempted_file_md5stringMD5 hash of the file being written
    write_attempted_file_sha1stringSHA-1 hash of the file being written
    write_attempted_file_sha256stringSHA-256 hash of the file being written
    suspicious_process_filenamestring | nullFilename of the quarantined suspicious process archive
    action_takenstringAction taken by the agent (e.g., "killed")
    ai_analysisstring | nullJSON string containing AI analysis with summary and severity (0-100) fields
    dismissal_reasonstring | nullReason the alert was dismissed, if applicable
    script_infostring | nullJSON string with script details if the alert was triggered by a scripting engine (e.g., {"script_name": "Python", "script_path": "..."})
    exfiltrate_infostring | nullJSON string with data exfiltration details if applicable (e.g., {"exfiltrate_name": "...", "exfiltrate_pattern": "..."})
    executing_usernamestringWindows username of the account running the process
    executing_user_sidstringWindows SID of the account running the process
    alert_timestringISO 8601 timestamp of when the alert was generated
    is_wipersnareintegerWhether this alert was generated by WiperSnare (1 = yes)
    organization_namestring | nullOrganization name (populated in some contexts)
    agent_namestring | nullAgent name (populated in some contexts)
    alert_countinteger | nullNumber of related alerts (populated in collapsed views)
    entity_idstringUnique identifier for the alert
    versionstringVersion identifier used for optimistic concurrency control
    activeintegerWhether the alert is active (1 = active)
    latestintegerWhether this is the latest version of the record (1 = latest)
    changed_onstringISO 8601 timestamp of the last modification

Get Alert by Entity ID​

Get detailed information for a specific alert by its entity ID.

  • URL: /alert/{entity_id}

  • Method: GET

  • Auth Required: Yes

  • URL Parameters:

    FieldRequiredDescription
    entity_idYesThe unique entity ID of the alert

  • Example Request:

    curl -X GET https://api.securitysnares.com/alert/21b1968c7e8f477cab44b3aa3bd2d4ad \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "organization_id": "4a01ee2047444639993cb978cf249dcc",
          "agent_id": "52b2134021d1438ab8a8ed43d870cb84",
          "agent_version": "2.0.1.0",
          "hostname": "WIN-SERVER01",
          "ip_address": "192.168.1.100",
          "mac_address": "FA163EEB5102",
          "process_id": "12776",
          "process_name": "babax.exe",
          "process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
          "process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
          "process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
          "process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
          "parent_process_id": "10404",
          "parent_process_name": "babax.exe",
          "parent_process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
          "parent_process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
          "parent_process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
          "parent_process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
          "write_attempted_file_path": "C:\\Users\\Administrator\\Documents\\tmp\\test_0_1.doc.enc",
          "write_attempted_file_size": 0,
          "write_attempted_file_md5": "9451bcb01117e96d3aec4f982248037d",
          "write_attempted_file_sha1": "7a99353f9ae38262a26ea0150fd005e9841d8f5c",
          "write_attempted_file_sha256": "423e6cac44e407ba7f7a568748b58cd63d9a3904b2a5be181c4401b84910e59b",
          "suspicious_process_filename": "d8434931-d98d-4321-9c6e-50af73fa8c80.zip",
          "action_taken": "killed",
          "ai_analysis": "{\"summary\": \"AI-Enhanced Analysis: The process attempted to write a file with an '.enc' extension, indicative of file encryption typical in ransomware.\", \"severity\": 90}",
          "dismissal_reason": null,
          "script_info": null,
          "exfiltrate_info": null,
          "executing_username": "WIN-SERVER01\\Administrator",
          "executing_user_sid": "S-1-5-21-2928516678-962286722-4132840994-500",
          "alert_time": "2026-02-26T19:12:04+00:00",
          "is_wipersnare": 0,
          "organization_name": null,
          "agent_name": null,
          "alert_count": null,
          "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
          "version": "9c55253849f14c35b17d529fab8b7966",
          "active": 1,
          "latest": 1,
          "changed_on": "2026-02-26T19:12:04+00:00"
        }
      }

    Response Fields: Same as Get Alerts.

  • Error Response:

    • Code: 404
    • Content: 
      {
        "success": false,
        "message": "Alert with entity_id 'alert_id' not found."
      }

Get Paginated Alerts​

Get a paginated list of alerts.

  • URL: /alerts/paginated

  • Method: GET

  • Auth Required: Yes

  • Query Parameters:

    • agent_id (optional): Filter alerts by agent ID
    • dismissed (optional): Filter by dismissed status (true/false)
    • page (optional): Page number (default: 1)
    • per_page (optional): Items per page (default: 10)

  • Example Request:

    curl -X GET 'https://api.securitysnares.com/alerts/paginated?page=1&per_page=10' \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: Same format as Get Alerts, with one additional field per alert object:
    FieldTypeDescription
    private_file_existsintegerWhether a quarantined file exists for download (1 = exists, 0 = not available)

Get Collapsed Alerts​

Get a paginated list of collapsed alerts (grouped by process name and hostname).

  • URL: /collapsed-alerts/paginated
  • Method: GET
  • Auth Required: Yes
  • Query Parameters:
    • agent_id (optional): Filter alerts by agent ID
    • dismissed (optional): Filter by dismissed status (true/false)
    • process_name (optional): Filter by process name
    • hostname (optional): Filter by hostname
    • page (optional): Page number (default: 1)
    • per_page (optional): Items per page (default: 10)
  • Example Request: 
    curl -X GET 'https://api.securitysnares.com/collapsed-alerts/paginated?page=1&per_page=10' \
      -H "Authorization: Bearer your_api_key_here"
  • Success Response:
    • Code: 200
    • Content: Same format as Get Alerts. Alerts are grouped by process name and hostname, with the alert_count field populated to indicate how many alerts are in each group.

Get MSSP Alerts​

Get alerts across all managed client organizations. Supports optional time-based filtering. This endpoint is only available to users with MSSP (Managed Security Service Provider) privileges. The authenticated API key must belong to an MSSP organization.

  • URL: /mssp/alerts
  • Method: GET
  • Auth Required: Yes
  • Query Parameters:
    • minutes (optional): Return alerts from the last N minutes
    • days (optional): Return alerts from the last N days
    • start_time (optional): Start of a custom date range (ISO 8601 format, e.g. 2026-01-01T10:00:00)
    • end_time (optional): End of a custom date range (ISO 8601 format, e.g. 2026-03-01T13:50:00)
note
  • If no time parameters are provided, all alerts are returned.
  • Use either minutes, days, or the start_time/end_time pair. Do not combine them.

  • Example Requests:

    Get all alerts (no time filter):

    curl -X GET 'https://api.securitysnares.com/mssp/alerts' \
      -H 'Authorization: Bearer your_api_key_here'

    Get alerts from the last 15 minutes:

    curl -X GET 'https://api.securitysnares.com/mssp/alerts?minutes=15' \
      -H 'Authorization: Bearer your_api_key_here'

    Get alerts from the last 7 days:

    curl -X GET 'https://api.securitysnares.com/mssp/alerts?days=7' \
      -H 'Authorization: Bearer your_api_key_here'

    Get alerts with a custom date range:

    curl -X GET 'https://api.securitysnares.com/mssp/alerts?start_time=2026-01-01T10:00:00&end_time=2026-03-01T13:50:00' \
      -H 'Authorization: Bearer your_api_key_here'

  • Success Response:

  • Error Responses:

    • Code: 403 - The authenticated user does not have MSSP privileges

Dismiss Alert​

Dismiss an alert.

  • URL: /alerts/dismiss

  • Method: POST

  • Auth Required: Yes

  • Request Body:

    {
      "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
      "dismissal_reason": "False positive"
    }
    FieldRequiredDescription
    entity_idYesThe unique entity ID of the alert to dismiss
    dismissal_reasonYesReason for dismissing the alert

  • Example Request:

    curl -X POST https://api.securitysnares.com/alerts/dismiss \
      -H "Authorization: Bearer your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{"entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad", "dismissal_reason": "False positive"}'

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
          "dismissal_reason": "False positive"
        }
      }

Dismiss Multiple Alerts​

Dismiss multiple alerts at once.

  • URL: /alerts/dismiss-multiple

  • Method: POST

  • Auth Required: Yes

  • Request Body:

    {
      "entity_ids": ["21b1968c7e8f477cab44b3aa3bd2d4ad", "6dd6e7c1a2cc4b25adfc78a1a69cac74"],
      "dismissal_reason": "False positive"
    }
    FieldRequiredDescription
    entity_idsYesArray of alert entity IDs to dismiss
    dismissal_reasonYesReason for dismissing the alerts

  • Example Request:

    curl -X POST https://api.securitysnares.com/alerts/dismiss-multiple \
      -H "Authorization: Bearer your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{"entity_ids": ["21b1968c7e8f477cab44b3aa3bd2d4ad", "6dd6e7c1a2cc4b25adfc78a1a69cac74"], "dismissal_reason": "False positive"}'

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
            "dismissal_reason": "False positive"
          },
          {
            "entity_id": "6dd6e7c1a2cc4b25adfc78a1a69cac74",
            "dismissal_reason": "False positive"
          }
        ]
      }

Allow Alert​

Allow a single alert, marking it as accepted/expected behavior. An optional reason can be provided to describe why the alert is being allowed.

  • URL: /alerts/allow

  • Method: POST

  • Auth Required: Yes

  • Request Body:

    {
      "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
      "allow_reason": "Known internal testing tool"
    }
    FieldRequiredDescription
    entity_idYesThe unique entity ID of the alert to allow
    allow_reasonNoReason for allowing the alert (max 50 characters)

  • Example Request:

    curl -X POST https://api.securitysnares.com/alerts/allow \
      -H "Authorization: Bearer your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{"entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad", "allow_reason": "Known internal testing tool"}'

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "organization_id": "4a01ee2047444639993cb978cf249dcc",
          "agent_id": "52b2134021d1438ab8a8ed43d870cb84",
          "agent_version": "2.0.1.0",
          "hostname": "WIN-SERVER01",
          "ip_address": "192.168.1.100",
          "mac_address": "FA163EEB5102",
          "process_id": "12776",
          "process_name": "babax.exe",
          "process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
          "process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
          "process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
          "process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
          "parent_process_id": "10404",
          "parent_process_name": "babax.exe",
          "parent_process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
          "parent_process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
          "parent_process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
          "parent_process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
          "write_attempted_file_path": "C:\\Users\\Administrator\\Documents\\tmp\\test_0_1.doc.enc",
          "write_attempted_file_size": 0,
          "write_attempted_file_md5": "9451bcb01117e96d3aec4f982248037d",
          "write_attempted_file_sha1": "7a99353f9ae38262a26ea0150fd005e9841d8f5c",
          "write_attempted_file_sha256": "423e6cac44e407ba7f7a568748b58cd63d9a3904b2a5be181c4401b84910e59b",
          "suspicious_process_filename": "d8434931-d98d-4321-9c6e-50af73fa8c80.zip",
          "action_taken": "killed",
          "ai_analysis": null,
          "dismissal_reason": "Known internal testing tool",
          "script_info": null,
          "exfiltrate_info": null,
          "executing_username": "WIN-SERVER01\\Administrator",
          "executing_user_sid": "S-1-5-21-2928516678-962286722-4132840994-500",
          "alert_time": "2026-02-26T19:12:04+00:00",
          "is_wipersnare": 0,
          "organization_name": null,
          "agent_name": null,
          "alert_count": null,
          "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
          "version": "9c55253849f14c35b17d529fab8b7966",
          "active": 1,
          "latest": 1,
          "changed_on": "2026-02-26T19:12:04+00:00"
        }
      }

    Response Fields: Same as Get Alerts. The dismissal_reason field will be set to the provided allow_reason value.

Allow Multiple Alerts​

Allow multiple alerts at once. Allowing an alert marks it as an accepted/expected behavior, setting the dismissal reason to "allowed". The response returns the full updated alert objects.

  • URL: /alerts/allow-multiple

  • Method: POST

  • Auth Required: Yes

  • Request Body:

    {
      "entity_ids": ["21b1968c7e8f477cab44b3aa3bd2d4ad", "6dd6e7c1a2cc4b25adfc78a1a69cac74"]
    }
    FieldRequiredDescription
    entity_idsYesArray of alert entity IDs to allow

  • Example Request:

    curl -X POST https://api.securitysnares.com/alerts/allow-multiple \
      -H "Authorization: Bearer your_api_key_here" \
      -H "Content-Type: application/json" \
      -d '{"entity_ids": ["21b1968c7e8f477cab44b3aa3bd2d4ad", "6dd6e7c1a2cc4b25adfc78a1a69cac74"]}'

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "organization_id": "4a01ee2047444639993cb978cf249dcc",
            "agent_id": "52b2134021d1438ab8a8ed43d870cb84",
            "agent_version": "2.0.1.0",
            "hostname": "WIN-SERVER01",
            "ip_address": "192.168.1.100",
            "mac_address": "FA163EEB5102",
            "process_id": "12776",
            "process_name": "babax.exe",
            "process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
            "process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
            "process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
            "process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
            "parent_process_id": "10404",
            "parent_process_name": "babax.exe",
            "parent_process_file_path": "C:\\Users\\Administrator\\Desktop\\babax.exe",
            "parent_process_md5": "8dec9a9f3741cdf40d2fd257c3021434",
            "parent_process_sha1": "8537cdd34104484676301645dd83ba9f25de0652",
            "parent_process_sha256": "9cb1691c394cbbd34eaa731c9c2c2ce6879fee9f3e33c96e5671394106e89d64",
            "write_attempted_file_path": "C:\\Users\\Administrator\\Documents\\tmp\\test_0_1.doc.enc",
            "write_attempted_file_size": 0,
            "write_attempted_file_md5": "9451bcb01117e96d3aec4f982248037d",
            "write_attempted_file_sha1": "7a99353f9ae38262a26ea0150fd005e9841d8f5c",
            "write_attempted_file_sha256": "423e6cac44e407ba7f7a568748b58cd63d9a3904b2a5be181c4401b84910e59b",
            "suspicious_process_filename": "d8434931-d98d-4321-9c6e-50af73fa8c80.zip",
            "action_taken": "killed",
            "ai_analysis": null,
            "dismissal_reason": "allowed",
            "script_info": null,
            "exfiltrate_info": null,
            "executing_username": "WIN-SERVER01\\Administrator",
            "executing_user_sid": "S-1-5-21-2928516678-962286722-4132840994-500",
            "alert_time": "2026-02-26T19:12:04+00:00",
            "is_wipersnare": 0,
            "organization_name": null,
            "agent_name": null,
            "alert_count": null,
            "entity_id": "21b1968c7e8f477cab44b3aa3bd2d4ad",
            "version": "9c55253849f14c35b17d529fab8b7966",
            "active": 1,
            "latest": 1,
            "changed_on": "2026-02-26T19:12:04+00:00"
          },
          {
            "organization_id": "4a01ee2047444639993cb978cf249dcc",
            "agent_id": "7c3a92f1b5e847d6a012df8e64c7ab39",
            "agent_version": "2.0.1.0",
            "hostname": "WIN-SERVER01",
            "ip_address": "192.168.1.100",
            "mac_address": "FA163EEB5102",
            "process_id": "8940",
            "process_name": "python.exe",
            "process_file_path": "C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python314\\python.exe",
            "process_md5": "b7f47165a0634b2290c67514e104e230",
            "process_sha1": "3dc4a8e92f154c68b021e79a5bd8f3ce7124a109",
            "process_sha256": "e8c912af4b7d4f1ca89253d70e6b41f9ab1c3d8e7f52a690b4d1e8c3f7a29b05",
            "parent_process_id": "3148",
            "parent_process_name": "cmd.exe",
            "parent_process_file_path": "C:\\Windows\\System32\\cmd.exe",
            "parent_process_md5": "b4a9f3c27e1d485fa6890c1d2e73b4a8",
            "parent_process_sha1": "9f5c31a8d7e24b16c083a4e2f6d91b7c5e3a8f04",
            "parent_process_sha256": "c3d7e9a1f4b8264d5a0e1c9f7b3d6a8e2f4c0b5d7e9a1f3c5b8d2e4a6f0c3e7",
            "write_attempted_file_path": "C:\\Users\\Administrator\\Documents\\tmp\\test_0_1.doc",
            "write_attempted_file_size": 0,
            "write_attempted_file_md5": "a3e8f1c7d4b9265e0f1a3c5d7e9b2f48",
            "write_attempted_file_sha1": "6b2d4f8a1c3e5079d2a4b6c8e0f1a3d5c7e9b2f4",
            "write_attempted_file_sha256": "1a3c5e7f9b2d4068a0c2e4f6b8d1a3c5e7f9b2d4068a0c2e4f6b8d1a3c5e7f9",
            "suspicious_process_filename": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.zip",
            "action_taken": "killed",
            "ai_analysis": null,
            "dismissal_reason": "allowed",
            "script_info": "{\"script_name\":\"Python\",\"script_path\":\"encryptor.py\"}",
            "exfiltrate_info": null,
            "executing_username": "WIN-SERVER01\\Administrator",
            "executing_user_sid": "S-1-5-21-2928516678-962286722-4132840994-500",
            "alert_time": "2026-02-26T19:12:04+00:00",
            "is_wipersnare": 0,
            "organization_name": null,
            "agent_name": null,
            "alert_count": null,
            "entity_id": "6dd6e7c1a2cc4b25adfc78a1a69cac74",
            "version": "b8e2a4c6d0f1357e9a2c4e6f8b0d2a4c",
            "active": 1,
            "latest": 1,
            "changed_on": "2026-02-26T19:12:04+00:00"
          }
        ]
      }

    Response Fields: Same as Get Alerts. The dismissal_reason field will be set to "allowed" for each alert.

Download Suspicious Process​

Get a download URL for a suspicious process file associated with an alert.

  • URL: /alert/suspicious_process/download/{entity_id}

  • Method: GET

  • Auth Required: Yes

  • URL Parameters:

    FieldRequiredDescription
    entity_idYesThe unique entity ID of the alert

  • Example Request:

    curl -X GET https://api.securitysnares.com/alert/suspicious_process/download/21b1968c7e8f477cab44b3aa3bd2d4ad \
      -H "Authorization: Bearer your_api_key_here"

  • Success Response:

    • Code: 200
    • Content: 
      {
        "success": true,
        "url": "https://presigned-url-to-download-file"
      }

    Response Fields:

    FieldTypeDescription
    urlstringPre-signed URL to download the quarantined suspicious process file

Error Handling​

All API endpoints return a consistent error format:

{
  "success": false,
  "message": "Error message describing what went wrong"
}

Common HTTP status codes:

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 401: Unauthorized (missing or invalid authentication)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found (resource doesn't exist)
  • 500: Internal Server Error