Looking up API Operations

Documentation Version

This helper provides developers with a simple function to search for any currently supported CrowdStrike API operation by operation ID, route, or service collection.

The find_operation function was first introduced in FalconPy v1.5.3.

Result examples
Keyword arguments
Lookup by API operation ID
Lookup by route
Lookup by service collection
Errors

Result examples

Results are returned as a dictionary containing the API operation ID, HTTP method, route, operation description, and associated service collection.

{
    "operation": "GetDeviceDetails",
    "method": "POST",
    "route": "/devices/entities/devices/v2",
    "description": "Get details on one or more hosts by providing host IDs in a POST body.  Supports up to a maximum 5000 IDs.",
    "collection": "hosts"
}

For multiple results, the method will return a list of dictionaries.

[
    {
        "operation": "getDeviceControlPolicies",
        "method": "GET",
        "route": "/policy/entities/device-control/v1",
        "description": "Retrieve a set of Device Control Policies by specifying their IDs",
        "collection": "device_control_policies"
    },
    {
        "operation": "getDeviceControlPoliciesV2",
        "method": "GET",
        "route": "/policy/entities/device-control/v2",
        "description": "Get device control policies for the given filter criteria. (USB and Bluetooth)",
        "collection": "device_control_policies"
    },
    {
        "operation": "GetDeviceCountCollectionQueriesByFilter",
        "method": "GET",
        "route": "/falcon-complete-dashboards/queries/devicecount-collections/v1",
        "description": "Retrieve device count collection Ids that match the provided FQL filter, criteria with scrolling enabled",
        "collection": "falcon_complete_dashboard"
    },
    {
        "operation": "GetDeviceDetails",
        "method": "POST",
        "route": "/devices/entities/devices/v2",
        "description": "Get details on one or more hosts by providing host IDs in a POST body.  Supports up to a maximum 5000 IDs.",
        "collection": "hosts"
    },
    {
        "operation": "GetDeviceDetailsV1",
        "method": "GET",
        "route": "/devices/entities/devices/v1",
        "description": "Get details on one or more hosts by providing agent IDs (AID). You can get a host's agent IDs (AIDs) from the /devices/queries/devices/v1 endpoint, the Falcon console or the Streaming API",
        "collection": "hosts"
    },
    {
        "operation": "GetDeviceDetailsV2",
        "method": "GET",
        "route": "/devices/entities/devices/v2",
        "description": "Get details on one or more hosts by providing host IDs as a query parameter.  Supports up to a maximum 100 IDs.",
        "collection": "hosts"
    }
]

Keyword arguments

This method supports three keywords.

Keyword	Data type	Default	Allowed values
`search_for`	String	None	Any
`search_by`	String	`id`	`id`, `route`, or `collection`
`exact`	Boolean	True	True or False

Looking up operations by operation ID

Since the first argument is assumed to be search_for, and the default search_by is id, you may search for an operation by ID by specifying the ID as the first argument without providing additional keywords. This assumes you are looking for an exact match to the string provided to the method.

Code example

from falconpy import find_operation
result = find_operation("GetDeviceDetails")
print(result)

Output example

{
    "operation": "GetDeviceDetails",
    "method": "POST",
    "route": "/devices/entities/devices/v2",
    "description": "Get details on one or more hosts by providing host IDs in a POST body.  Supports up to a maximum 5000 IDs.",
    "collection": "hosts"
}

The following two examples will produce the same result:

from falconpy import find_operation
result = find_operation("GetDeviceDetails", "id", True)
print(result)

from falconpy import find_operation
result = find_operation(search_for="GetDeviceDetails", search_by="id", exact=True)
print(result)

Exact match searches are case sensitive.

To return every API operation that contains the string specified for the search_by argument, set exact to False.

from falconpy import find_operation
result = find_operation(search_for="Device", search_by="id", exact=False)
print(result)

You do not need to specify every keyword argument to accomplish this.

from falconpy import find_operation
result = find_operation("Device", exact=False)
print(result)

When searching with exact set to False, case insensitive matches are returned.

from falconpy import find_operation
result = find_operation("device", exact=False)
print(result)

Looking up operations by operation route

You may search by API operation route by changing the value of search_by to route.

By default, searching by route is an exact match, which will result in a case sensitive search.

from falconpy import find_operation
result = find_operation(search_for="/devices/entities/devices/v1", search_by="route")
print(result)

As before, you do not need to use keyword argument syntax, and may specify arguments positionally as necessary.

from falconpy import find_operation
result = find_operation("/devices/entities/devices/v1", "route")
print(result)

from falconpy import find_operation
result = find_operation("/devices/entities/devices/v1", search_by="route")
print(result)

You may disable exact matching when searching by route, which will provide you with all case insensitive matches.

from falconpy import find_operation
result = find_operation("/DEVICES/", search_by="route", exact=False)
print(result)

Looking up operations by API service collection

You may search by API service collection by changing the value of search_by to collection.

By default, searching by service collection is an exact match, which will result in a case sensitive search.

from falconpy import find_operation
result = find_operation(search_for="hosts", search_by="collection")
print(result)

Arguments may be specified positionally, or mixed with keyword arguments.

from falconpy import find_operation
result = find_operation("hosts", "collection")
print(result)

from falconpy import find_operation
result = find_operation("hosts", search_by="collection")
print(result)

You may disable exact matching when searching by collection, which will provide you with all case insensitive matches.

from falconpy import find_operation
result = find_operation("HOST", search_by="collection", exact=False)

Search errors

There are several error types that may be produced when this method receives invalid input.

InvalidOperationSearch

Returned when an invalid value is specified for the search_by keyword argument.

from falconpy import find_operation
result = find_operation("some_value", search_by="invalid_option")

falconpy._error._exceptions.InvalidOperationSearch: Invalid operation search specified

InvalidOperation

Returned when searching for an operation by ID and there is no result.

from falconpy import find_operation
result = find_operation("bad_route", exact=False)

falconpy._error._exceptions.InvalidOperation: Invalid API operation specified.

InvalidRoute

Returned when searching for an operation by route and there is no result.

from falconpy import find_operation
result = find_operation("bad_route", exact=False)

falconpy._error._exceptions.InvalidRoute: This API route does not exist

InvalidServiceCollection

Returned when searching for an operation by service collection and there is no result.

from falconpy import find_operation
result = find_operation("bad_service_collection", exact=False)

falconpy._error._exceptions.InvalidServiceCollection: Invalid API Service Collection specified

The CrowdStrike Falcon Wiki for Python