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​

Login​

Authenticates a user and returns an access token.

  • URL: /login
  • Method: POST
  • Auth Required: No
  • Request Body: 
    {
      "email": "user@example.com",
      "password": "your_password"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "message": "Logged in successfully",
        "user": {
          "entity_id": "user_id",
          "email": "user@example.com",
          "first_name": "John",
          "last_name": "Doe",
          "access_token": "jwt_token",
          "access_token_expiry": 1623456789,
          "organizations": [
            {
              "entity_id": "org_id",
              "name": "Organization Name",
              "role": "admin"
            }
          ],
          "mfa_enabled": false
        }
      }
  • Error Response:
    • Code: 400
    • Content: 
      {
        "success": false,
        "message": "Incorrect credentials"
      }

Login with MFA​

If MFA is enabled, you'll need to complete a second authentication step.

  • URL: /login_mfa
  • Method: POST
  • Auth Required: No
  • Request Body: 
    {
      "email": "user@example.com",
      "password": "your_password",
      "otp": "123456"
    }
  • Success Response:
    • Code: 200
    • Content: Same as login response

Reset Password​

Request a password reset email.

  • URL: /reset_password
  • Method: POST
  • Auth Required: No
  • Request Body: 
    {
      "email": "user@example.com"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "message": "Password reset email has been sent"
      }

Organizations​

Get User Organizations​

Get the list of organizations the authenticated user belongs to.

  • URL: /user/organizations
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "org_id",
            "name": "Organization Name",
            "contact_email": "contact@example.com",
            "contact_phone": "(123) 456-7890",
            "notification_preferences": "email",
            "organization_type": "client"
          }
        ]
      }

Get Organization Details​

Get details about a specific organization.

  • URL: /organization/{organization_id}
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "org_id",
          "name": "Organization Name",
          "contact_email": "contact@example.com",
          "contact_phone": "(123) 456-7890",
          "notification_preferences": "email",
          "organization_type": "client"
        }
      }

Update Organization​

Update organization details.

  • URL: /organization
  • Method: PUT
  • Auth Required: Yes
  • Request Body: 
    {
      "entity_id": "org_id",
      "version": "version_id",
      "name": "Updated Organization Name",
      "contact_email": "updated@example.com",
      "contact_phone": "(123) 456-7890",
      "notification_preferences": "email",
      "organization_type": "client",
      "managed_by": "mssp_org_id",
      "uninstall_password": "password123"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "message": "Organization updated successfully",
        "data": {
          "entity_id": "org_id",
          "name": "Updated Organization Name",
          "contact_email": "updated@example.com"
        }
      }

Update Notification Preferences​

Update organization notification preferences.

  • URL: /organization/notification-preferences
  • Method: PUT
  • Auth Required: Yes
  • Request Body: 
    {
      "notification_preferences": "email_and_sms",
      "contact_phone": "(123) 456-7890"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "message": "Notification preferences updated successfully",
        "data": {
          "entity_id": "org_id",
          "name": "Organization Name",
          "notification_preferences": "email_and_sms",
          "contact_phone": "(123) 456-7890"
        }
      }

Agents​

Get All Agents​

Get a list of all agents for an organization.

  • URL: /agents
  • Method: GET
  • Auth Required: Yes (User login or API key)
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "agent_id",
            "name": "Agent Name",
            "hostname": "host.example.com",
            "os_type": "Windows",
            "os_platform": "Windows 10",
            "os_version_number": "10.0.19042",
            "os_version_detail": "Windows 10 Pro",
            "agent_version": "1.2.3",
            "polling_interval": 300,
            "alert_only": false,
            "driver_enabled": true,
            "unseen_crash_logs": 0,
            "unseen_suspicious_processes": 0,
            "last_poll": "2025-06-07T21:30:00Z"
          }
        ]
      }

Update Agent​

Update agent details.

  • URL: /agents
  • Method: PUT
  • Auth Required: Yes
  • Request Body: 
    {
      "entity_id": "agent_id",
      "name": "Updated Agent Name",
      "alert_notification_type": "email",
      "alert_notification_message_template": "Custom alert message template"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "agent_id",
          "name": "Updated Agent Name",
          "alert_notification_type": "email",
          "alert_notification_message_template": "Custom alert message template"
        }
      }

Confirm Agent Uninstall​

Confirm agent uninstallation.

  • URL: /agents/confirm_uninstall
  • Method: POST
  • Auth Required: Yes (API key)
  • Request Body: 
    {
      "instance_id": "agent_id",
      "uninstall_password": "password123"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "success": true
        }
      }

Alerts​

Get Alerts​

Get a list of all alerts for an organization.

  • URL: /alerts
  • Method: GET
  • Auth Required: Yes (User login or API key)
  • Query Parameters:
    • agent_id (optional): Filter alerts by agent ID
    • dismissed (optional): Filter by dismissed status (true/false)
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "alert_id",
            "organization_id": "org_id",
            "agent_id": "agent_id",
            "hostname": "host.example.com",
            "process_name": "suspicious.exe",
            "process_file_path": "C:\\path\\to\\suspicious.exe",
            "process_md5": "md5_hash",
            "alert_time": "2025-06-07T21:30:00Z",
            "action_taken": "blocked"
          }
        ]
      }

Get Paginated Alerts​

Get a paginated list of alerts.

  • URL: /alerts/paginated
  • Method: GET
  • Auth Required: Yes (User login or API key)
  • 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)
  • Success Response:
    • Code: 200
    • Content: Same format as /alerts

Get Alert Count​

Get the count of alerts.

  • URL: /alerts/count
  • Method: GET
  • Auth Required: Yes
  • Query Parameters:
    • agent_id (optional): Filter alerts by agent ID
    • dismissed (optional): Filter by dismissed status (true/false)
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "total": 42
        }
      }

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 (User login or API key)
  • 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)
  • Success Response:
    • Code: 200
    • Content: Similar to /alerts/paginated

Add Alert​

Add a new alert (typically used by agents).

  • URL: /alerts
  • Method: POST
  • Auth Required: Yes (API key)
  • Request Body: 
    {
      "uuid": "agent_id",
      "version": "agent_version",
      "hostname": "host.example.com",
      "ip_address": "192.168.1.100",
      "mac_address": "00:11:22:33:44:55",
      "pid": 1234,
      "process_name": "suspicious.exe",
      "process_path": "C:\\path\\to\\suspicious.exe",
      "process_md5": "md5_hash",
      "process_sha1": "sha1_hash",
      "process_sha256": "sha256_hash",
      "parent_pid": 1000,
      "parent_process_name": "explorer.exe",
      "parent_process_path": "C:\\Windows\\explorer.exe",
      "file_path": "C:\\path\\to\\target.txt",
      "file_size": 1024,
      "md5": "file_md5_hash",
      "sha1": "file_sha1_hash",
      "sha256": "file_sha256_hash",
      "quarantine_file_name": "quarantined_file.bin",
      "action_taken": "blocked",
      "detected_at": 1623456789
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "alert_id",
          "organization_id": "org_id",
          "agent_id": "agent_id",
          "hostname": "host.example.com",
          "process_name": "suspicious.exe"
        }
      }

Dismiss Alert​

Dismiss an alert.

  • URL: /alerts/dismiss
  • Method: POST
  • Auth Required: Yes
  • Request Body: 
    {
      "entity_id": "alert_id",
      "dismissal_reason": "False positive"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "alert_id",
          "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": ["alert_id_1", "alert_id_2"],
      "dismissal_reason": "False positive"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "alert_id_1",
            "dismissal_reason": "False positive"
          },
          {
            "entity_id": "alert_id_2",
            "dismissal_reason": "False positive"
          }
        ]
      }

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
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "url": "https://presigned-url-to-download-file"
      }

Crash Logs​

Get Crash Logs​

Get a list of crash logs for an organization or specific agent.

  • URL: /crash_logs or /crash_logs/{agent_id}
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "crash_log_id",
            "organization_id": "org_id",
            "agent_id": "agent_id",
            "s3_key": "crash_logs/org_id/agent_id/20250607123456.zip",
            "file_size": 1024,
            "added_on": "2025-06-07T12:34:56Z",
            "seen": false
          }
        ]
      }

Download Crash Log​

Get a download URL for a crash log file.

  • URL: /crash_logs/download/{entity_id}
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "url": "https://presigned-url-to-download-file"
      }

API Keys​

Get API Keys​

Get a list of API keys for an organization.

  • URL: /organization/{organization_id}/api_keys
  • Method: GET
  • Auth Required: Yes
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": [
          {
            "entity_id": "api_key_id",
            "label": "Agent API Key",
            "key": "api_key_value",
            "status": true,
            "organization_id": "org_id"
          }
        ]
      }

Create or Update API Key​

Create a new API key or update an existing one.

  • URL: /organization/{organization_id}/api_keys
  • Method: POST or PUT
  • Auth Required: Yes
  • Request Body: 
    {
      "label": "New API Key",
      "status": true,
      "entity_id": "api_key_id",  // Include for updates, omit for creation
      "version": "version_id"     // Include for updates, omit for creation
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "data": {
          "entity_id": "api_key_id",
          "label": "New API Key",
          "key": "api_key_value",
          "status": true,
          "organization_id": "org_id"
        }
      }

Delete API Key​

Delete an API key.

  • URL: /organization/{organization_id}/api_keys
  • Method: DELETE
  • Auth Required: Yes
  • Request Body: 
    {
      "entity_id": "api_key_id"
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "message": "API Key deleted successfully."
      }

File Upload​

Get File Upload URL​

Get a pre-signed URL for uploading files.

  • URL: /file-upload-url/{prefix} or /file-upload-url/{prefix}/{s3_key}
  • Method: POST
  • Auth Required: Yes (API key)
  • Request Body: 
    {
      "fileName": "file.zip",
      "contentType": "application/zip",
      "metadata": {
        "agent_id": "agent_id"
      }
    }
  • Success Response:
    • Code: 200
    • Content: 
      {
        "success": true,
        "url": "https://presigned-url-to-upload-file"
      }

Authentication Notes​

  • Most endpoints require authentication via a JWT token obtained from the /login endpoint.
  • Include the token in the Authorization header as Bearer {token}.
  • Some endpoints can be accessed using an API key instead of a user login.
  • For API key authentication, include the key in the X-API-Key header.

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