POST /api/activities/convertsearch

Convert simple filter criteria into Shield's advanced query syntax for use with the Activities API.

Endpoint

POST /api/activities/convertsearch

Authentication

Requires API Key with read access (all keys have read access).

Authorization: Bearer <api-key>

Purpose

This endpoint converts human-readable filter objects into Shield's advanced query string format. This approach allows you to build queries programmatically without manually constructing complex query strings.

The generated query string can then be used with:

GET /api/activities - Retrieve activities
GET /api/activities/csv - Export activities to CSV
GET /api/alertlogs - Retrieve alert execution logs (when using alert-specific fields)

Request Body

{
  "simpleToAdvanced": {
    "field_name": "value" or ["value1", "value2"] or {complex_filter}
  }
}

Filter Types

Time Range Filters

Within Last (Relative Time)

{
  "simpleToAdvanced": {
    "timestamp": {
      "withinLast": {
        "days": 7,
        "hours": 0,
        "minutes": 0
      }
    }
  }
}

In The Range (Absolute Time)

{
  "simpleToAdvanced": {
    "timestamp": {
      "inTheRange": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      }
    }
  }
}

More Than (Older Than)

{
  "simpleToAdvanced": {
    "timestamp": {
      "moreThan": {
        "days": 30,
        "hours": 0,
        "minutes": 0
      }
    }
  }
}

Boolean Filters

{
  "simpleToAdvanced": {
    "detected": ["true"],
    "obfuscated": ["false"],
    "blocked": ["false"]
  }
}

String/UUID Array Filters

{
  "simpleToAdvanced": {
    "usernames": ["john.doe@company.com", "jane.smith@company.com"],
    "userGroups": ["Engineering", "Finance"],
    "detectedDatatypes": ["US_SSN", "CREDIT_CARD"],
    "apps": ["app-uuid-1"],
    "hostnames": ["api.example.com"]
  }
}

Combined Filters

{
  "simpleToAdvanced": {
    "timestamp": {"withinLast": {"days": 7, "hours": 0, "minutes": 0}},
    "detected": ["true"],
    "detectedDatatypes": ["US_SSN", "CREDIT_CARD"],
    "userGroups": ["Finance"]
  }
}

Available Filter Fields

Activity-Specific Fields

Field	Type	Description	Example Value
`timestamp`	time range	Activity timestamp	See Time Range Filters
`detected`	boolean	Sensitive data was detected	`["true"]` or `["false"]`
`obfuscated`	boolean	Data was masked	`["true"]` or `["false"]`
`blocked`	boolean	Request was blocked	`["true"]` or `["false"]`
`bypassed`	boolean	Scanning was bypassed	`["true"]` or `["false"]`
`detectedDatatypes`	string[]	Data type identifiers detected (UPPERCASE)	`["US_SSN", "CREDIT_CARD"]`
`obfuscatedDatatypes`	string[]	Data type identifiers obfuscated (UPPERCASE)	`["US_SSN", "EMAIL_ADDRESS"]`
`apps`	UUID[]	Application UUIDs	`["uuid-1"]`
`rules`	UUID[]	Rule UUIDs matched	`["uuid-1"]`
`usernames`	string[]	Username(s)	`["john.doe@company.com"]`
`userGroups`	string[]	User group(s)	`["Finance", "Engineering"]`
`hostnames`	string[]	Hostname(s)	`["api.example.com"]`
`contentTypes`	string[]	Content type(s)	`["application/json"]`
`clientDevices`	string[]	Device type(s)	`["Mobile", "Desktop"]`
`clientIpAddresses`	string[]	Client IP address(es)	`["192.168.1.100"]`

Alert Log-Specific Fields

Use these fields when building queries for GET /api/alertlogs:

Field	Type	Description	Example Value
`alertNames`	string[]	Alert name(s)	`["High-Volume PII Detection"]`
`notificationTypes`	string[]	Notification types	`["email", "slack"]`
`slackChannels`	string[]	Slack channel UUIDs	`["channel-uuid-1"]`
`emailRecipients`	string[]	Email addresses	`["security@company.com"]`

Response Format

{
  "simpleToAdvanced": "ADVANCED_QUERY_STRING"
}

The simpleToAdvanced field contains the encoded query string to use with /api/activities or /api/activities/csv.

Complete Examples

Last 7 Days with Detections

Get activities from the last 7 days where sensitive data was detected.

cURLPythonNode.js

curl -X POST "https://your-shield-host:8080/api/activities/convertsearch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "simpleToAdvanced": {
      "detected": ["true"],
      "timestamp": {"withinLast": {"days": 7, "hours": 0, "minutes": 0}}
    }
  }'

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

query_request = {
    "simpleToAdvanced": {
        "detected": ["true"],
        "timestamp": {"withinLast": {"days": 7, "hours": 0, "minutes": 0}}
    }
}

response = requests.post(
    f"{BASE_URL}/api/activities/convertsearch",
    headers=HEADERS,
    json=query_request
)

query = response.json()["simpleToAdvanced"]
print(f"Query: {query}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const queryRequest = {
  simpleToAdvanced: {
    detected: ['true'],
    timestamp: { withinLast: { days: 7, hours: 0, minutes: 0 } }
  }
};

axios.post(`${BASE_URL}/api/activities/convertsearch`, queryRequest, { headers: HEADERS })
  .then(response => {
    const query = response.data.simpleToAdvanced;
    console.log(`Query: ${query}`);
  });

Response:

{
  "simpleToAdvanced": "detected in (true) and timestamp >= '-7d'"
}

Specific User and Data Types

Query activities for a specific user with SSN or credit card detections in the last 24 hours.

cURLPythonNode.js

# Build and execute query
curl -X POST "https://your-shield-host:8080/api/activities/convertsearch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "simpleToAdvanced": {
      "usernames": ["john.doe@company.com"],
      "detectedDatatypes": ["US_SSN", "CREDIT_CARD"],
      "timestamp": {"withinLast": {"days": 1, "hours": 0, "minutes": 0}}
    }
  }'

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Build query
query_request = {
    "simpleToAdvanced": {
        "usernames": ["john.doe@company.com"],
        "detectedDatatypes": ["US_SSN", "CREDIT_CARD"],
        "timestamp": {"withinLast": {"days": 1, "hours": 0, "minutes": 0}}
    }
}

response = requests.post(
    f"{BASE_URL}/api/activities/convertsearch",
    headers=HEADERS,
    json=query_request
)

query = response.json()["simpleToAdvanced"]
print(f"Query: {query}")

# Use the query to get activities
activities = requests.get(
    f"{BASE_URL}/api/activities",
    headers=HEADERS,
    params={"search": query}
).json()

print(f"Found {activities['count']} matching activities")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

async function queryUserActivities() {
  // Build query
  const queryRequest = {
    simpleToAdvanced: {
      usernames: ['john.doe@company.com'],
      detectedDatatypes: ['US_SSN', 'CREDIT_CARD'],
      timestamp: { withinLast: { days: 1, hours: 0, minutes: 0 } }
    }
  };

  const queryResp = await axios.post(
    `${BASE_URL}/api/activities/convertsearch`,
    queryRequest,
    { headers: HEADERS }
  );

  const query = queryResp.data.simpleToAdvanced;
  console.log(`Query: ${query}`);

  // Use the query to get activities
  const activitiesResp = await axios.get(
    `${BASE_URL}/api/activities`,
    { headers: HEADERS, params: { search: query } }
  );

  console.log(`Found ${activitiesResp.data.count} matching activities`);
}

queryUserActivities();

Date Range for Compliance Report

Generate a monthly PII detection report for January 2024.

cURLPythonNode.js

# Build query for date range
curl -X POST "https://your-shield-host:8080/api/activities/convertsearch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "simpleToAdvanced": {
      "timestamp": {
        "inTheRange": {
          "start": "2024-01-01T00:00:00Z",
          "end": "2024-01-31T23:59:59Z"
        }
      },
      "detectedDatatypes": ["ssn-uuid", "credit-card-uuid", "email-uuid"],
      "obfuscated": ["true"]
    }
  }'

import requests
from datetime import datetime

BASE_URL = "https://your-shield-host:8080"
API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def generate_monthly_report(year, month, datatype_ids):
    # Calculate date range
    start = datetime(year, month, 1)
    if month == 12:
        end = datetime(year + 1, 1, 1)
    else:
        end = datetime(year, month + 1, 1)

    # Build query
    query_request = {
        "simpleToAdvanced": {
            "timestamp": {
                "inTheRange": {
                    "start": start.isoformat() + "Z",
                    "end": end.isoformat() + "Z"
                }
            },
            "detectedDatatypes": datatype_ids,
            "obfuscated": ["true"]
        }
    }

    query = requests.post(
        f"{BASE_URL}/api/activities/convertsearch",
        headers=HEADERS,
        json=query_request
    ).json()["simpleToAdvanced"]

    print(f"Generated query: {query}")
    return query

# Generate January 2024 report query
query = generate_monthly_report(2024, 1, ["US_SSN", "CREDIT_CARD", "EMAIL_ADDRESS"])

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

async function generateMonthlyReport(year, month, datatypeIds) {
  // Calculate date range
  const start = new Date(year, month - 1, 1);
  const end = new Date(year, month, 1);

  // Build query
  const queryRequest = {
    simpleToAdvanced: {
      timestamp: {
        inTheRange: {
          start: start.toISOString(),
          end: end.toISOString()
        }
      },
      detectedDatatypes: datatypeIds,
      obfuscated: ['true']
    }
  };

  const response = await axios.post(
    `${BASE_URL}/api/activities/convertsearch`,
    queryRequest,
    { headers: HEADERS }
  );

  const query = response.data.simpleToAdvanced;
  console.log(`Generated query: ${query}`);
  return query;
}

// Generate January 2024 report query
generateMonthlyReport(2024, 1, ['US_SSN', 'CREDIT_CARD', 'EMAIL_ADDRESS']);

Query Alert Logs

Use convertsearch to query alert execution logs.

PythonNode.js

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Build query for alert logs
convert_body = {
    "simpleToAdvanced": {
        "alertNames": ["High-Volume PII Detection", "Blocked Request Alert"],
        "emailRecipients": ["security@company.com"],
        "timestamp": {"withinLast": {"days": 7, "hours": 0, "minutes": 0}}
    }
}

# Convert to query string
convert_response = requests.post(
    f"{BASE_URL}/api/activities/convertsearch",
    headers=HEADERS,
    json=convert_body
)

query_string = convert_response.json()["simpleToAdvanced"]

# Query alert logs with generated query
logs_response = requests.get(
    f"{BASE_URL}/api/alertlogs",
    headers=HEADERS,
    params={"search": query_string}
)

print(f"Found {logs_response.json()['count']} alert log entries:")
for log in logs_response.json()["items"]:
    print(f"  - {log['alertName']}: {log['occurrencesCount']} occurrences at {log['timestamp']}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

async function queryAlertLogs() {
  // Build query for alert logs
  const convertBody = {
    simpleToAdvanced: {
      alertNames: ['High-Volume PII Detection', 'Blocked Request Alert'],
      emailRecipients: ['security@company.com'],
      timestamp: { withinLast: { days: 7, hours: 0, minutes: 0 } }
    }
  };

  // Convert to query string
  const convertResponse = await axios.post(
    `${BASE_URL}/api/activities/convertsearch`,
    convertBody,
    { headers: HEADERS }
  );

  const queryString = convertResponse.data.simpleToAdvanced;

  // Query alert logs with generated query
  const logsResponse = await axios.get(`${BASE_URL}/api/alertlogs`, {
    headers: HEADERS,
    params: { search: queryString }
  });

  console.log(`Found ${logsResponse.data.count} alert log entries:`);
  logsResponse.data.items.forEach(log => {
    console.log(`  - ${log.alertName}: ${log.occurrencesCount} occurrences at ${log.timestamp}`);
  });
}

queryAlertLogs();

Error Responses

Status Code	Description	Resolution
400	Invalid filter structure	Check JSON format and field names
401	Invalid or missing API key	Verify authentication
500	Server error	Check Shield logs

Best Practices

Always use convertsearch - Don't manually construct query strings. The format may change between Shield versions.
Get UUIDs dynamically - Fetch data type, app, and rule UUIDs from their respective API endpoints rather than hardcoding them.
Validate time ranges - Ensure start dates are before end dates when using inTheRange.
Test queries incrementally - Start with basic filters and add complexity gradually.
Reuse queries - Store successfully built queries for repeated use.

GET /api/activities - Use the generated query to retrieve activities
GET /api/activities/csv - Export query results to CSV
GET /api/alertlogs - Query alert execution logs using alert-specific fields
Available Filter Fields - Complete list of filter fields you can use in queries
Extracting Activity Data Workflow - Complete workflow guide

POST /api/activities/convertsearch

Endpoint

Authentication

Purpose

Request Body

Filter Types

Time Range Filters

Within Last (Relative Time)

In The Range (Absolute Time)

More Than (Older Than)

Boolean Filters

String/UUID Array Filters

Combined Filters

Available Filter Fields

Activity-Specific Fields

Alert Log-Specific Fields

Response Format

Complete Examples

Error Responses

Best Practices

Related Topics