### Install Incydr SDK

Source: https://developer.code42.com/sdk

Install the Incydr SDK using pip. Use the --upgrade flag to upgrade an existing installation.

```bash
pip install incydr
```

```bash
pip install incydr --upgrade
```

--------------------------------

### Add Roles to Users Example

Source: https://developer.code42.com/cli/cmds/users

Example of adding roles to users using a JSON-lines formatted file.

```bash
incydr users bulk-update-roles path/to/file.json --add --format json-lines
```

--------------------------------

### Bulk Update Alert States Example

Source: https://developer.code42.com/cli/cmds/alerts

Demonstrates how to bulk update alert states by piping search results to the bulk-update-state command. This example targets 'PENDING' alerts older than a specified date and resolves them.

```bash
incydr alerts search --end <DATE> --state PENDING --format json-lines | incydr alerts bulk-update-state - --state RESOLVED --note "bulk resolved alerts older than <DATE>"
```

--------------------------------

### Install Incydr CLI

Source: https://developer.code42.com/cli

Install the Incydr CLI extension to the Incydr SDK using pip. This command installs the necessary packages for the CLI functionality.

```bash
$ pip install 'incydr[cli]'

```

--------------------------------

### get

Source: https://developer.code42.com/sdk/clients/watchlists

Get a single watchlist.

```APIDOC
## get

### Description
Get a single watchlist.

### Method
GET

### Endpoint
/v2/watchlists/{watchlist_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.

### Response
#### Success Response (200)
- **watchlist** (Watchlist) - A `Watchlist` object.
```

--------------------------------

### Specify Full Syslog Output Configuration

Source: https://developer.code42.com/cli/syslogging

This example demonstrates how to explicitly specify the protocol, hostname, and port for the syslog output.

```bash
--output TCP:syslog.example.com:601
```

--------------------------------

### Initialize Incydr Client and Get Case

Source: https://developer.code42.com/sdk/clients/cases

Demonstrates how to initialize the Incydr client and retrieve a specific case by its number.

```python
>>> import incydr
>>> client = incydr.Client(**kwargs)
>>> client.cases.v1.get_case(23)

```

--------------------------------

### Alerts Search with JSON Output

Source: https://developer.code42.com/cli/cmds/alerts

Example of setting the output format to pretty JSON.

```bash
alerts search -f json-pretty

```

--------------------------------

### Activate Org Command Usage

Source: https://developer.code42.com/cli/cmds/orgs

Shows the usage for activating a specific organization by its GUID.

```bash
orgs activate [OPTIONS] ORG_GUID
```

--------------------------------

### Initialize and Get Directory Groups Page

Source: https://developer.code42.com/sdk/clients/directory_groups

Demonstrates how to initialize the Code42 client and retrieve a page of directory groups using the `get_page` method.

```python
import incydr
client = incydr.Client(**kwargs)
client.directory_groups.v1.get_page()
```

--------------------------------

### Get Customer Details

Source: https://developer.code42.com/sdk/client

Retrieve customer-specific information using the `customer` client.

```python
>>> client.customer.v1.get()

```

--------------------------------

### Get All Available Roles

Source: https://developer.code42.com/sdk/clients/users

Fetches a list of all roles that can be assigned by the current user.

```python
client.users.v1.list_roles()
```

--------------------------------

### Show Org Command Usage

Source: https://developer.code42.com/cli/cmds/orgs

Displays the usage for viewing details of a specific organization by its GUID.

```bash
orgs show [OPTIONS] ORG_GUID
```

--------------------------------

### Alerts Search with Checkpointing

Source: https://developer.code42.com/cli/cmds/alerts

Example of using checkpointing to retrieve only new alert search results.

```bash
alerts search --checkpoint <checkpoint-name>

```

--------------------------------

### Alerts Search with Advanced Query from File

Source: https://developer.code42.com/cli/cmds/alerts

Example of using an advanced query defined in a JSON file.

```bash
alerts search --advanced-query @query.json

```

--------------------------------

### Search File Events with Query

Source: https://developer.code42.com/sdk/client

Search for file events using a constructed `EventQuery`. This example filters by file category and a date range.

```python
>>> from incydr import EventQuery
>>> query = EventQuery(start_date='P30D').equals('file.category', 'Document')

>>> client.file_events.v2.search(query)

```

--------------------------------

### Initialize Customer Client and Get Account Info

Source: https://developer.code42.com/sdk/clients/customer

Demonstrates how to initialize the Code42 SDK client and use the customer.v1.get() method to retrieve account information. Ensure you have the necessary authentication credentials configured.

```python
>>> import incydr
>>> client = incydr.Client(**kwargs)
>>> client.customer.v1.get()

```

--------------------------------

### Get a Specific Organization

Source: https://developer.code42.com/sdk/clients/orgs

Retrieves details for a single organization using its unique GUID. This is useful for fetching specific organization information.

```python
client.orgs.v1.get_org(org_guid='unique-org-guid-789')
```

--------------------------------

### Initialize Incydr Client and List Orgs

Source: https://developer.code42.com/sdk/clients/orgs

Demonstrates how to initialize the Incydr client and call the list_orgs method. Ensure you have your authentication credentials set up.

```python
>>> import incydr
>>> 
>>> client = incydr.Client(**kwargs)
>>> client.orgs.v1.list_orgs()

```

--------------------------------

### Initialize Files Client and Download File by SHA256

Source: https://developer.code42.com/sdk/clients/files

Demonstrates how to initialize the Incydr client and use the `download_file_by_sha256` method to download a file. Requires client initialization with appropriate credentials.

```python
>>> import incydr
>>> 
>>> client = incydr.Client(**kwargs)
>>> client.files.v1.download_file_by_sha256("example_hash", "./testfile.test")

```

--------------------------------

### Initialize Incydr Client and Get Agent Page

Source: https://developer.code42.com/sdk/clients/agents

Demonstrates how to initialize the Incydr client and retrieve a paginated list of agents. Ensure you have your authentication credentials set up.

```python
>>> import incydr
>>> client = incydr.Client(**kwargs)
>>> client.agents.v1.get_page()

```

--------------------------------

### Alerts Search with Custom CA Certificates

Source: https://developer.code42.com/cli/cmds/alerts

Example of specifying a CA certificate chain file for TLS-TCP protocol.

```bash
alerts search --certs "/path/to/ca.crt"

```

--------------------------------

### Import and Initialize Incydr Client

Source: https://developer.code42.com/sdk/clients/devices

Shows how to import the incydr library and initialize a client instance. This is a prerequisite for using any of the client's methods.

```python
import incydr
client = incydr.Client(**kwargs)
```

--------------------------------

### Activate an Organization

Source: https://developer.code42.com/sdk/clients/orgs

Re-activates a previously deactivated organization using its unique GUID. This operation requires the organization's GUID.

```python
client.orgs.v1.activate(org_guid='unique-org-guid-789')
```

--------------------------------

### Initialize Departments Client

Source: https://developer.code42.com/sdk/clients/departments

Instantiate the DepartmentsV1 client and retrieve a page of departments. Ensure the incydr library is installed and client arguments are properly configured.

```python
import incydr
client = incydr.Client(**kwargs)
client.departments.v1.get_page()
```

--------------------------------

### get_included_actor

Source: https://developer.code42.com/sdk/clients/watchlists

Get an included actor from a watchlist.

```APIDOC
## get_included_actor

### Description
Get an included actor from a watchlist.

### Method
GET

### Endpoint
/v2/watchlists/{watchlist_id}/included-actors/{actor_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **actor_id** (str) - Required - Unique actor ID.

### Response
#### Success Response (200)
- **actor** (WatchlistActor) - A `WatchlistActor` object.
```

--------------------------------

### get_excluded_actor

Source: https://developer.code42.com/sdk/clients/watchlists

Get an excluded actor from a watchlist.

```APIDOC
## get_excluded_actor

### Description
Get an excluded actor from a watchlist.

### Method
GET

### Endpoint
/v2/watchlists/{watchlist_id}/excluded-actors/{actor_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **actor_id** (str) - Required - Unique actor ID.

### Response
#### Success Response (200)
- **actor** (WatchlistActor) - A `WatchlistActor` object.
```

--------------------------------

### Create Org Command Options

Source: https://developer.code42.com/cli/cmds/orgs

Lists options specific to creating an organization, including external references, notes, parent org, and output formatting.

```bash
--external-reference TEXT  The external reference string for the org.
                             Defaults to None.
--notes TEXT               The notes string for the org. Defaults to None.
--parent-org-guid TEXT     The org guid for the created org's parent.
                             Defaults to your tenant's parent org.
-f, --format SINGLEFORMAT  Format to print result. One of 'rich', 'json-
                             pretty', or 'json-lines'. If environment has
                             INCYDR_USE_RICH=false set, defaults to 'json-
                             lines', else defaults to 'rich'.
--columns TEXT             Comma-delimited string of column names. Nested
                             values should be specified in dot-notation.
                             Limits output to contain only the specified
                             columns in CSV or Table format.  Ignored for JSON
                             output formats.
--log-stderr               Enable logging to stderr.
--log-file TEXT            Specify file path to write log output to.
--log-level TEXT           Set level for Incydr client logging.
--help                     Show this message and exit.
```

--------------------------------

### get_department

Source: https://developer.code42.com/sdk/clients/watchlists

Get an included department from a watchlist.

```APIDOC
## get_department

### Description
Get an included department from a watchlist.

### Method
GET

### Endpoint
/v2/watchlists/{watchlist_id}/departments/{department}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **department** (str) - Required - A included department.

### Response
#### Success Response (200)
- **department** (IncludedDepartment) - An `IncludedDepartment` object.
```

--------------------------------

### get_directory_group

Source: https://developer.code42.com/sdk/clients/watchlists

Get an included directory group from a watchlist.

```APIDOC
## get_directory_group

### Description
Get an included directory group from a watchlist.

### Method
GET

### Endpoint
/v2/watchlists/{watchlist_id}/directory-groups/{group_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **group_id** (str) - Required - Directory group ID.

### Response
#### Success Response (200)
- **directory_group** (IncludedDirectoryGroup) - An `IncludedDirectoryGroup` object.
```

--------------------------------

### get_trusted_activity

Source: https://developer.code42.com/sdk/clients/trusted_activities

Get a single trusted activity by its unique ID.

```APIDOC
## get_trusted_activity

### Description
Get a single trusted activity.

### Parameters
#### Path Parameters
* None

#### Query Parameters
* **activity_id** (str) - Required - The unique ID for the trusted activity.

### Request Example
```python
client.trusted_activities.v2.get_trusted_activity('123')
```

### Response
#### Success Response (200)
* A `TrustedActivity` object.

#### Response Example
```json
{
  "id": 123,
  "accountName": "example_account",
  "description": "Trust for corporate account",
  "dropbox": true,
  "oneDrive": false
}
```
```

--------------------------------

### Show Device Command Options

Source: https://developer.code42.com/cli/cmds/devices

Details the options for the 'devices show' command, including output formatting and logging. The format option adjusts the output presentation.

```bash
-f, --format SINGLEFORMAT  Format to print result. One of 'rich', 'json-
                             pretty', or 'json-lines'. If environment has
                             INCYDR_USE_RICH=false set, defaults to 'json-
                             lines', else defaults to 'rich'.
  --log-stderr               Enable logging to stderr.
  --log-file TEXT            Specify file path to write log output to.
  --log-level TEXT           Set level for Incydr client logging.
  --help                     Show this message and exit.
```

--------------------------------

### get_org

Source: https://developer.code42.com/sdk/clients/orgs

Retrieves details for a specific organization by its unique GUID.

```APIDOC
## get_org

### Description
Retrieves details for a specific organization by its unique GUID.

### Method
GET

### Endpoint
/v1/orgs/{orgGuid}

### Parameters
#### Path Parameters
- **org_guid** (str) - Required - The unique ID for the org.

### Returns
#### Success Response (200)
- An `Org` object representing the org.

### Response Example
```json
{
  "orgGuid": "existing-org-guid-123",
  "orgName": "Example Org",
  "orgExtRef": "ext-ref-abc",
  "parentOrgGuid": null,
  "notes": "This is an example organization.",
  "active": true,
  "created": "2023-10-26T09:00:00Z",
  "lastUpdated": "2023-10-26T09:30:00Z"
}
```
```

--------------------------------

### Valid start_date Examples for EventQuery

Source: https://developer.code42.com/sdk/clients/file_event_queries

Demonstrates various valid formats for the `start_date` parameter in `EventQuery`, including string, datetime object, UTC timestamp, timedelta, and ISO duration.

```python
import datetime

# Filter for events after September 10th, 2020
start_str = "2020-09-10 11:12:13"  # string formatted as "%Y-%m-%d %H:%M:%S"

start_datetime = datetime.datetime(2020, 9, 10, 11, 12, 13) # datetime object

start_utc = 1599736333.0  # UTC timestamp

# Filter for events that occurred in the last 7 days
start_timedelta = datetime.timedelta(days=7)

start_iso_duration = "P7D"
```

--------------------------------

### deactivate

Source: https://developer.code42.com/sdk/clients/orgs

Deactivates a specified organization using its unique GUID.

```APIDOC
## deactivate

### Description
Deactivates a specified organization using its unique GUID.

### Method
POST

### Endpoint
/v1/orgs/{orgGuid}/deactivate

### Parameters
#### Path Parameters
- **org_guid** (str) - Required - The unique ID for the org.

### Returns
#### Success Response (200)
- A `requests.Response` indicating success.

### Request Example
```json
{
  "orgGuid": "string"
}
```

### Response Example
```json
{
  "message": "Organization deactivated successfully"
}
```
```

--------------------------------

### activate

Source: https://developer.code42.com/sdk/clients/orgs

Activates a specified organization using its unique GUID.

```APIDOC
## activate

### Description
Activates a specified organization using its unique GUID.

### Method
POST

### Endpoint
/v1/orgs/{orgGuid}/activate

### Parameters
#### Path Parameters
- **org_guid** (str) - Required - The unique ID for the org.

### Returns
#### Success Response (200)
- A `requests.Response` indicating success.

### Request Example
```json
{
  "orgGuid": "string"
}
```

### Response Example
```json
{
  "message": "Organization activated successfully"
}
```
```

--------------------------------

### Initialize Incydr Client

Source: https://developer.code42.com/sdk/client

Instantiate the Incydr client with your API credentials and domain. Ensure you replace placeholders with your actual values.

```python
>>> import incydr
>>> client = incydr.Client(url="<api_domain>", api_client_id="<client_id>", api_client_secret="<client_secret>")

```

--------------------------------

### Get a single watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details for a specific watchlist by its ID.

```APIDOC
## Get Watchlist

### Description
Retrieves details for a specific watchlist by its ID.

### Method
GET

### Endpoint
/v1/watchlists/{watchlist_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.

### Response
#### Success Response (200)
- **id** (str) - The watchlist ID.
- **title** (str) - The watchlist title.
- **description** (str) - The watchlist description.
- **type** (WatchlistType) - The type of the watchlist.

#### Response Example
```json
{
  "id": "watchlist-id-789",
  "title": "Example Watchlist",
  "description": "This is an example watchlist.",
  "type": "CUSTOM"
}
```
```

--------------------------------

### List All Cases

Source: https://developer.code42.com/cli/cmds/cases

Lists all cases with options for output format and column selection. Defaults to JSON lines if INCYDR_USE_RICH is false, otherwise defaults to table.

```bash
cases list [OPTIONS]
```

--------------------------------

### Show Org Command Options

Source: https://developer.code42.com/cli/cmds/orgs

Lists options for showing organization details, including output formatting and column selection.

```bash
-f, --format SINGLEFORMAT  Format to print result. One of 'rich', 'json-
                             pretty', or 'json-lines'. If environment has
                             INCYDR_USE_RICH=false set, defaults to 'json-
                             lines', else defaults to 'rich'.
--columns TEXT             Comma-delimited string of column names. Nested
                             values should be specified in dot-notation.
                             Limits output to contain only the specified
                             columns in CSV or Table format.  Ignored for JSON
                             output formats.
--log-stderr               Enable logging to stderr.
--log-file TEXT            Specify file path to write log output to.
--log-level TEXT           Set level for Incydr client logging.
--help                     Show this message and exit.
```

--------------------------------

### Get a single device

Source: https://developer.code42.com/sdk/clients/devices

Retrieves a single device by its unique ID.

```APIDOC
## get_device

### Description
Get a single device.

### Method
GET

### Endpoint
/v1/devices/{device_id}

### Parameters
#### Path Parameters
- **device_id** (str) - Required - The unique ID for the device.

### Returns
A `Device` object representing the device.
```

--------------------------------

### move

Source: https://developer.code42.com/sdk/clients/users

Moves a specified user to a different organization, identified by its GUID.

```APIDOC
## move

### Description
Move a user to a specified organization.

### Method
POST

### Endpoint
/v1/users/{userId}/move

### Parameters
#### Path Parameters
- **userId** (str) - Required - The unique ID for the user.

#### Request Body
- **orgGuid** (str) - Required - The GUID of the organization to move the user to.

### Returns
- A `requests.Response` indicating success.
```

--------------------------------

### AlertQuery Construction and Filtering

Source: https://developer.code42.com/sdk/clients/alert_queries

Demonstrates how to instantiate the AlertQuery class with a date range and apply filters using methods like 'equals'. It also shows how to combine filters using AND logic by default, or OR logic with 'matches_any()'.

```APIDOC
## AlertQuery Construction and Filtering

### Description
Construct an `AlertQuery` object to define search parameters for alerts. You can specify a date range using `start_date` and `end_date`, which accept various formats including Unix timestamps, date strings, `datetime` objects, and `timedelta`. The `on` argument can be used to filter alerts created on a specific date. Various filter methods like `.equals()`, `.not_equals()`, `.contains()`, and `.does_not_contain()` are available to refine your search based on specific terms and values. By default, filters are combined with an AND operator; use `.matches_any()` to combine them with an OR operator.

### Usage
```python
from datetime import timedelta
from incydr import AlertQuery

# Create a query for alerts created in the past 3 days with state OPEN or PENDING
query = AlertQuery(start_date=timedelta(days=3)).equals('State', ['OPEN', 'PENDING'])

# Example of OR logic for filters
# query = AlertQuery(start_date=timedelta(days=3)).equals('State', ['OPEN', 'PENDING']).matches_any()

# To execute the query, pass the query object to the client.alerts.v1.search() method.
# Example:
# client.alerts.v1.search(query)
```

### Parameters for AlertQuery Constructor
- **start_date**: Sets the beginning of the date range. Accepts `int` or `float` (Unix epoch timestamp), date strings (`%Y-%m-%d %H:%M:%S` or `%Y-%m-%d`), `datetime.datetime` objects, or `datetime.timedelta`.
- **end_date** (Optional): Sets the end of the date range. Accepts the same formats as `start_date`.
- **on**: Filters alerts created on a specific date. Accepts `datetime.date`, `datetime.datetime`, or date strings (`%Y-%m-%d %H:%M:%S` or `%Y-%m-%d`). Time information is ignored.

### Filter Methods
All filter methods require a `term` (string) specifying the field to filter and a `value` (or list of values) to search for.
- **`.equals(term, value)`**: Filters for exact matches.
- **`.not_equals(term, value)`**: Filters for non-matches.
- **`.contains(term, value)`**: Filters for values that contain the specified term.
- **`.does_not_contain(term, value)`**: Filters for values that do not contain the specified term.

### Logic Modifiers
- **`.matches_any()`**: Changes the filter logic from AND (default) to OR.
```

--------------------------------

### Get a watchlist ID by name

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves a watchlist ID by its type or title.

```APIDOC
## Get Watchlist ID by Name

### Description
Retrieves a watchlist ID by its type (e.g., `DEPARTING_EMPLOYEE`) or its title in the case of `CUSTOM` watchlists.

### Method
GET

### Endpoint
/v1/watchlists/id/{name}

### Parameters
#### Path Parameters
- **name** (str, WatchlistType) - Required - A `WatchlistType` or, in the case of `CUSTOM` watchlists, the watchlist `title`.

### Response
#### Success Response (200)
- **id** (str) - The watchlist ID.

#### Response Example
```json
{
  "id": "watchlist-id-abc"
}
```
```

--------------------------------

### Initialize Risk Profiles Client and Get Page

Source: https://developer.code42.com/sdk/clients/risk_profiles

Demonstrates how to initialize the Incydr client and retrieve the first page of risk profiles using the deprecated `RiskProfilesV1` client. Ensure you have your authentication credentials set up.

```python
>>> import incydr
>>> client = incydr.Client(**kwargs)
>>> client.risk_profiles.v1.get_page()
```

--------------------------------

### Create a Case with Incydr SDK

Source: https://developer.code42.com/sdk

Example of creating a new case using the Incydr SDK's cases client. The client automatically loads credentials from environment variables if not provided.

```python
>>> import incydr
>>> client = incydr.Client()
>>> client.cases.v1.create(name="Test", description="Created with Incydr SDK")
Case(
    number=28,
    name='Test',
    created_at=datetime.datetime(2022, 8, 2, 13, 11, 7, 803762, tzinfo=datetime.timezone.utc),
    updated_at=datetime.datetime(2022, 8, 2, 13, 11, 7, 803762, tzinfo=datetime.timezone.utc),
    description='Created with Incydr SDK',
    findings=None,
    subject=None,
    subject_username=None,
    status='OPEN',
    assignee=None,
    assignee_username=None,
    created_by_user_id=None,
    created_by_username=None,
    last_modified_by_user_id=None,
    last_modified_by_username=None
)


```

--------------------------------

### Get Included Department from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves a specific department included on a watchlist.

```python
client.watchlists.get_department(watchlist_id='some_watchlist_id', department='department_name')

```

--------------------------------

### Initialize Users Client

Source: https://developer.code42.com/sdk/clients/users

Initializes the UsersV1 client for interacting with user endpoints. Requires an Incydr client instance.

```python
>>> import incydr
>>> client = incydr.Client(**kwargs)
>>> client.users.v1.get_page()
```

--------------------------------

### Get Single Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details for a specific watchlist using its ID.

```python
client.watchlists.get(watchlist_id='some_watchlist_id')

```

--------------------------------

### get_page

Source: https://developer.code42.com/sdk/clients/watchlists

Get a page of watchlists. Filter results by passing appropriate parameters.

```APIDOC
## get_page

### Description
Get a page of watchlists.

### Method
GET

### Endpoint
/v2/watchlists

### Parameters
#### Query Parameters
- **page_num** (int) - Optional - Page number for results, starting at 1.
- **page_size** (int) - Optional - Max number of results to return for a page.
- **actor_id** (str) - Optional - Matches watchlists where the actor is a member.

### Response
#### Success Response (200)
- **watchlists** (WatchlistsPage) - A `WatchlistsPage` object.
```

--------------------------------

### Create Org Command Usage

Source: https://developer.code42.com/cli/cmds/orgs

Details the usage for creating a new organization, requiring a name and allowing optional parameters.

```bash
orgs create [OPTIONS] NAME
```

--------------------------------

### Get a Single Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details for a specific watchlist using its ID.

```python
>>> client.watchlists.v2.get('your_watchlist_id')
```

--------------------------------

### Show Risk Profile Command Options

Source: https://developer.code42.com/cli/cmds/risk_profiles

Lists the options available for the 'show' command, including output formatting and logging preferences. The 'USER' argument is mandatory.

```bash
  -f, --format SINGLEFORMAT  Format to print result. One of 'rich', 'json-
                             pretty', or 'json-lines'. If environment has
                             INCYDR_USE_RICH=false set, defaults to 'json-
                             lines', else defaults to 'rich'.
  --log-stderr               Enable logging to stderr.
  --log-file TEXT            Specify file path to write log output to.
  --log-level TEXT           Set level for Incydr client logging.
  --help                     Show this message and exit.
```

--------------------------------

### Client Initialization

Source: https://developer.code42.com/sdk/client

Initializes the Incydr Client with authentication details and optional settings.

```APIDOC
## Client Initialization

### Description
Initializes the Incydr Client with authentication details and optional settings.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **url** (`str`) - The url of your Incydr API gateway. See the developer getting started guide to find your API domain based on your console login URL.
* **api_client_id** (`str`) - The ID of your Incydr API Client
* **api_client_secret** (`str`) - The Secret for your Incydr API Client.
* **skip_auth** (`bool`) - Whether to skip authentication.
* **settings_kwargs** - Additional keyword arguments for settings.

### Usage Example
```python
>>> import incydr
>>> client = incydr.Client(url="<api_domain>", api_client_id="<client_id>", api_client_secret="<client_secret>")
```
```

--------------------------------

### Executing Alert Queries and Pagination

Source: https://developer.code42.com/sdk/clients/alert_queries

Explains how to execute alert queries using `client.alerts.v1.search()` and how to handle pagination manually by incrementing `page_num` or automatically using `client.alerts.v1.iter_all()`.

```APIDOC
## Executing Alert Queries and Pagination

### Description
Execute constructed alert queries using the `client.alerts.v1.search()` method. If the query returns more results than the `page_size` (maximum 500), you can manually paginate by incrementing the `query.page_num` attribute and re-running `client.alerts.v1.search()`. For a simpler approach, the `client.alerts.v1.iter_all()` method handles pagination automatically, yielding each alert individually.

### Method
- **`client.alerts.v1.search(query_object)`**: Executes the search query and returns the results for the current page.
- **`client.alerts.v1.iter_all(query_object)`**: Iterates through all pages of results, yielding each alert one by one.

### Pagination
- **Manual Pagination**: 
  1. Execute `client.alerts.v1.search(query)`.
  2. Check `first_page.total_count` against `query.page_size`.
  3. If more results exist, increment `query.page_num` (`query.page_num += 1`).
  4. Re-run `client.alerts.v1.search(query)` to fetch the next page.
  5. Repeat until all results are retrieved.
- **Automatic Pagination**: Use `client.alerts.v1.iter_all(query)` for seamless iteration over all results without manual page management.

### Usage Examples
#### Manual Pagination
```python
from datetime import timedelta
from incydr import Client, AlertQuery

client = Client(**kwargs)
query = AlertQuery(start_date=timedelta(days=10))

first_page = client.alerts.v1.search(query)
if first_page.total_count > query.page_size:
    query.page_num += 1
    second_page = client.alerts.v1.search(query)
    # ... continue fetching pages as needed
```

#### Automatic Pagination
```python
from datetime import timedelta
import incydr

client = incydr.Client(**kwargs)
query = incydr.AlertQuery(start_date=timedelta(days=10))

for alert in client.alerts.v1.iter_all(query):
    # process each alert individually
    pass
```
```

--------------------------------

### Alerts Search Filter by State

Source: https://developer.code42.com/cli/cmds/alerts

Example of filtering alerts by their current state.

```bash
alerts search --state OPEN

```

--------------------------------

### create

Source: https://developer.code42.com/sdk/clients/watchlists

Create a new watchlist.

```APIDOC
## create

### Description
Create a new watchlist.

### Method
POST

### Endpoint
/v2/watchlists

### Parameters
#### Request Body
- **watchlist_type** (WatchlistType) - Required - Type of the watchlist to create.
- **title** (str) - Optional - The required title for a custom watchlist.
- **description** (str) - Optional - The optional description for a custom watchlist.

### Response
#### Success Response (200)
- **watchlist** (Watchlist) - A `Watchlist` object.
```

--------------------------------

### Move User to Organization

Source: https://developer.code42.com/sdk/clients/users

Moves a user to a different organization, identified by its GUID.

```python
client.users.v1.move(user_id, org_guid)
```

--------------------------------

### Get an included user from a watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific user included in a watchlist.

```APIDOC
## Get Included User from Watchlist

### Description
Retrieves details of a specific user included in a watchlist.

### Method
GET

### Endpoint
/v1/watchlists/{watchlist_id}/users/included/{user_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **user_id** (str) - Required - The user ID to retrieve.

### Response
#### Success Response (200)
- **id** (str) - The user ID.
- **username** (str) - The username.

#### Response Example
```json
{
  "id": "user-456",
  "username": "another_user"
}
```
```

--------------------------------

### Create a Case

Source: https://developer.code42.com/sdk/client

Utilize the `cases` client to create a new case with a specified name and description.

```python
>>> client.cases.v1.create(name="Test", description="My Description")

```

--------------------------------

### Get an excluded user from a watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific user excluded from a watchlist.

```APIDOC
## Get Excluded User from Watchlist

### Description
Retrieves details of a specific user excluded from a watchlist.

### Method
GET

### Endpoint
/v1/watchlists/{watchlist_id}/users/excluded/{user_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **user_id** (str) - Required - The user ID to retrieve.

### Response
#### Success Response (200)
- **id** (str) - The user ID.
- **username** (str) - The username.

#### Response Example
```json
{
  "id": "user-123",
  "username": "example_user"
}
```
```

--------------------------------

### List All Available Roles

Source: https://developer.code42.com/cli/cmds/users

Use this command to list all roles that can be assigned by the current user. The output format can be controlled using the --format option.

```bash
users roles list [OPTIONS]
```

--------------------------------

### Get an included department from a watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific department included in a watchlist.

```APIDOC
## Get Included Department from Watchlist

### Description
Retrieves details of a specific department included in a watchlist.

### Method
GET

### Endpoint
/v1/watchlists/{watchlist_id}/departments/{department}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **department** (str) - Required - The department to retrieve.

### Response
#### Success Response (200)
- **id** (str) - The department ID.
- **name** (str) - The department name.

#### Response Example
```json
{
  "id": "department-abc",
  "name": "Example Department"
}
```
```

--------------------------------

### Get Included User from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific user included on a watchlist.

```python
client.watchlists.get_included_user(watchlist_id='some_watchlist_id', user_id='user_id')

```

--------------------------------

### Initialize Actors Client

Source: https://developer.code42.com/sdk/clients/actors

Instantiate the ActorsV1 client to interact with the /v1/actors endpoints. Requires Incydr client initialization with necessary credentials.

```python
>>> import incydr
>>> client = incydr.Client(**kwargs)
>>> client.actors.v1.get_page()
```

--------------------------------

### Get Excluded User from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific user excluded from a watchlist.

```python
client.watchlists.get_excluded_user(watchlist_id='some_watchlist_id', user_id='user_id')

```

--------------------------------

### Cases Create Usage

Source: https://developer.code42.com/cli/cmds/cases

Create a new case by providing a name and optional details like description, subject, assignee, and findings.

```bash
cases create [OPTIONS] NAME
```

--------------------------------

### Get Included Department from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific department included on a watchlist.

```python
>>> client.watchlists.v2.get_department('your_watchlist_id', 'department_id_1')
```

--------------------------------

### Get Excluded Actor from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific actor excluded from a watchlist.

```python
>>> client.watchlists.v2.get_excluded_actor('your_watchlist_id', 'actor_id_1')
```

--------------------------------

### Create a New Watchlist

Source: https://developer.code42.com/cli/cmds/watchlists

Use this command to create a new watchlist. Specify the WATCHLIST_TYPE. For CUSTOM watchlists, --title is required and --description is optional.

```bash
watchlists create [OPTIONS] WATCHLIST_TYPE

```

--------------------------------

### Get Included Actor from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific actor included on a watchlist.

```python
>>> client.watchlists.v2.get_included_actor('your_watchlist_id', 'actor_id_1')
```

--------------------------------

### Search File Events with EventQuery

Source: https://developer.code42.com/sdk/clients/file_events

Demonstrates how to initialize the Code42 client, create an EventQuery to filter file events by category and date, and then search for these events using the file_events.v2.search method. Handles pagination automatically.

```python
import incydr
from incydr import EventQuery

client = incydr.Client(**kwargs)
query = EventQuery(start_date='P30D').equals('file.category', ['Document', 'SourceCode'])
client.file_events.v2.search(query)
```

--------------------------------

### Get Case

Source: https://developer.code42.com/sdk/clients/cases

Retrieves details for a single case using its unique case number.

```APIDOC
## GET /cases/{case_number}

### Description
Get a single case.

### Method
GET

### Endpoint
/cases/{case_number}

### Parameters
#### Path Parameters
- **case_number** (int) - Required - Unique numeric identifier for the case.

### Returns
- A `Case` object representing the case.
```

--------------------------------

### create

Source: https://developer.code42.com/sdk/clients/orgs

Creates a new organization with the provided details.

```APIDOC
## create

### Description
Creates a new organization with the provided details.

### Method
POST

### Endpoint
/v1/orgs

### Parameters
#### Request Body
- **org_name** (str) - Required - The name of the org to create.
- **org_ext_ref** (str) - Optional - The external reference of the org to create.
- **parent_org_guid** (str) - Optional - The parent ID of the org to create.
- **notes** (str) - Optional - The notes of the org to create.

### Returns
#### Success Response (201)
- An `Org` object representing the created org.

### Request Example
```json
{
  "org_name": "New Org Name",
  "org_ext_ref": "external-ref-123",
  "parent_org_guid": "parent-guid-456",
  "notes": "Some important notes"
}
```

### Response Example
```json
{
  "orgGuid": "new-org-guid-789",
  "orgName": "New Org Name",
  "orgExtRef": "external-ref-123",
  "parentOrgGuid": "parent-guid-456",
  "notes": "Some important notes",
  "created": "2023-10-27T10:00:00Z",
  "lastUpdated": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Get Page of Watchlists

Source: https://developer.code42.com/sdk/client

Fetch a paginated list of watchlists using the `watchlists` client.

```python
>>> client.watchlists.v1.get_page()

```

--------------------------------

### Get Page of Departments

Source: https://developer.code42.com/sdk/client

Fetch a paginated list of departments using the `departments` client.

```python
>>> client.departments.v1.get_page()

```

--------------------------------

### List Devices Command Options

Source: https://developer.code42.com/cli/cmds/devices

Details the options available for filtering and formatting the output of the 'devices list' command. Defaults are applied if no filter options are specified.

```bash
--active / --inactive     Filter by active or inactive devices. Defaults to
                            returning both when when neither option is passed.
  --blocked / --unblocked   Filter by blocked or unblocked devices. Defaults
                            to returning both when when neither option is
                            passed.
  -f, --format TABLEFORMAT  Format to print result. One of 'table', 'json-
                            pretty', 'json-lines', or 'csv. If environment has
                            INCYDR_USE_RICH=false set, defaults to 'json-
                            lines', else defaults to 'table'.
  --columns TEXT            Comma-delimited string of column names. Nested
                            values should be specified in dot-notation. Limits
                            output to contain only the specified columns in
                            CSV or Table format.  Ignored for JSON output
                            formats.
  --log-stderr              Enable logging to stderr.
  --log-file TEXT           Specify file path to write log output to.
  --log-level TEXT          Set level for Incydr client logging.
  --help                    Show this message and exit.
```

--------------------------------

### Users Bulk Activate Usage

Source: https://developer.code42.com/cli/cmds/users

Usage for bulk activating users from a file.

```bash
users bulk-activate [OPTIONS] FILE
```

--------------------------------

### Get Single Agent

Source: https://developer.code42.com/sdk/clients/agents

Retrieves details for a specific agent using its unique ID.

```python
client.agents.v1.get_agent(agent_id='agent-id-1')

```

--------------------------------

### Alerts Search Filter by Severity

Source: https://developer.code42.com/cli/cmds/alerts

Example of filtering alerts by a specific severity level.

```bash
alerts search --alert-severity HIGH

```

--------------------------------

### Show User Details in Rich Format

Source: https://developer.code42.com/cli/getting_started

Display a single user's details using the rich output format for human-readable display.

```bash
$ incydr users show foo.bar@gmail.com --format rich
```

--------------------------------

### Deactivate Org Command Usage

Source: https://developer.code42.com/cli/cmds/orgs

Provides the usage for deactivating an organization using its GUID.

```bash
orgs deactivate [OPTIONS] ORG_GUID
```

--------------------------------

### Initialize Client with INFO Log Level

Source: https://developer.code42.com/sdk/logging

Initialize the Incydr client and set the log level to INFO to capture basic request details for every HTTP request. This is useful for monitoring general activity.

```python
import incydr
client = incydr.Client(log_level="INFO")
client.cases.v1.get_case(21)
```

--------------------------------

### Displaying Help Message

Source: https://developer.code42.com/cli/cmds/watchlists

Use the --help option to display the help message for the 'watchlists remove' command, showing all available options and usage information.

```bash
--help                         Show this message and exit.
```

--------------------------------

### Show User Details in JSON Pretty Format

Source: https://developer.code42.com/cli/getting_started

Display a single user's details using the json-pretty output format for structured, readable JSON.

```bash
$ incydr users show foo.bar@gmail.com --format json-pretty
```

--------------------------------

### Get Watchlists Page

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves a paginated list of watchlists. Results can be filtered by user ID.

```APIDOC
## Get Watchlists Page

### Description
Get a page of watchlists. Filter results by passing appropriate parameters.

### Parameters
#### Query Parameters
* **page_num** (int) - Optional - Page number for results, starting at 1.
* **page_size** (int) - Optional - Max number of results to return for a page.
* **user_id** (str) - Optional - Matches watchlists where the user is a member.

### Returns
A `WatchlistsPage` object.
```

--------------------------------

### Users Activate Usage

Source: https://developer.code42.com/cli/cmds/users

Usage for activating a single user.

```bash
users activate [OPTIONS] USER
```

--------------------------------

### Get Included Directory Group from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves a specific directory group included on a watchlist.

```python
client.watchlists.get_directory_group(watchlist_id='some_watchlist_id', group_id='group_id')

```

--------------------------------

### Get Role Details

Source: https://developer.code42.com/sdk/clients/users

Retrieves detailed information for a specific role, identified by its ID or name.

```python
client.users.v1.get_role(role)
```

--------------------------------

### Get Session Details

Source: https://developer.code42.com/sdk/clients/sessions

Fetches detailed information for a specific session using its unique ID.

```python
>>> client.sessions.v1.get_session_details("<session_id>")

```

--------------------------------

### Manual Pagination for Alert Search

Source: https://developer.code42.com/sdk/clients/alert_queries

Demonstrates how to manually paginate through search results when the total count exceeds the page size. Requires importing Client and AlertQuery, and using timedelta.

```python
from datetime import timedelta
from incydr import Client, AlertQuery

client = Client(**kwargs)

query = AlertQuery(start_date=timedelta(days=10))
first_page = client.alerts.v1.search(query)
if first_page.total_count > query.page_size:
    query.page_num += 1
    second_page = client.alerts.v1.search(query)
    ...  # continue until all alerts are retrieved
```

--------------------------------

### Get a Single User

Source: https://developer.code42.com/sdk/clients/users

Retrieves details for a specific user using their unique ID or username.

```python
client.users.v1.get_user(user)
```

--------------------------------

### Add Trusted Domain with File Upload and Cloud Sync Services

Source: https://developer.code42.com/cli/cmds/trusted_activities

Example of creating a trusted domain that trusts file uploads and specific cloud sync services (Box, iCloud).

```bash
trusted-activities add domain --file-upload --cloud-sync-services BOX --cloud-sync-services ICLOUD
```

--------------------------------

### Get Single Case

Source: https://developer.code42.com/sdk/clients/cases

Retrieves a single case object using its unique numeric identifier.

```python
client.cases.v1.get_case(case_number)
```

--------------------------------

### Get a single risk profile

Source: https://developer.code42.com/sdk/clients/risk_profiles

Retrieves a specific risk profile for a given user ID.

```APIDOC
## get_risk_profile(user_id)

### Description
Get a single risk profile.

### Method
GET

### Endpoint
/v1/user-risk-profiles/{user_id}

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The unique ID for the user.

### Returns
A `RiskProfile` object representing the risk profile.
```

--------------------------------

### Initialize Incydr Client with Custom Page Size

Source: https://developer.code42.com/sdk/settings

Demonstrates how to initialize the Incydr client with a custom page size. This is useful for controlling the number of items returned in paginated requests.

```python
import incydr
>>> client = incydr.Client(page_size = 10)

```

--------------------------------

### Initialize Incydr Client and Change Alert State

Source: https://developer.code42.com/sdk/clients/alerts

Example of initializing the Incydr client and changing the state of a specific alert to 'RESOLVED'. Requires importing the AlertState enum.

```python
import incydr
from incydr.enums.alerts import AlertState

client = incydr.Client(**kwargs)
client.alerts.v1.change_state("<alert_id>", AlertState.RESOLVED)
```

--------------------------------

### Alerts Search Filter by Rule ID

Source: https://developer.code42.com/cli/cmds/alerts

Example of filtering alerts by the ID of the rule that triggered them.

```bash
alerts search --rule-id "<rule-id>"

```

--------------------------------

### Import EventQuery Class

Source: https://developer.code42.com/sdk/clients/file_event_queries

Import the `EventQuery` class from the `incydr` module to begin building queries.

```python
from incydr import EventQuery
```

--------------------------------

### Alerts Search with Custom Columns

Source: https://developer.code42.com/cli/cmds/alerts

Example of filtering search results to include only specified columns.

```bash
alerts search --columns "column1,nested.column2"

```

--------------------------------

### Automatic Pagination with iter_all

Source: https://developer.code42.com/sdk/clients/alert_queries

Utilizes the `client.alerts.v1.iter_all()` method for automatic, simplified retrieval of all alerts matching a query, eliminating manual pagination logic. Requires importing Client and AlertQuery, and using timedelta.

```python
from datetime import timedelta
import incydr
client = incydr.Client(**kwargs)

query = incydr.AlertQuery(start_date=timedelta(days=10))
for alert in client.alerts.v1.iter_all(query):
    ... # process alert here
```

--------------------------------

### List Legal Hold Policies CLI Command

Source: https://developer.code42.com/cli/cmds/legal_hold

Lists all legal hold policies. Output format can be customized.

```bash
legal-hold list-policies [OPTIONS]
```

--------------------------------

### Get an included directory group from a watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific directory group included in a watchlist.

```APIDOC
## Get Included Directory Group from Watchlist

### Description
Retrieves details of a specific directory group included in a watchlist.

### Method
GET

### Endpoint
/v1/watchlists/{watchlist_id}/directory-groups/{group_id}

### Parameters
#### Path Parameters
- **watchlist_id** (str) - Required - Watchlist ID.
- **group_id** (str) - Required - The directory group ID to retrieve.

### Response
#### Success Response (200)
- **id** (str) - The group ID.
- **name** (str) - The group name.

#### Response Example
```json
{
  "id": "group-xyz",
  "name": "Example Group"
}
```
```

--------------------------------

### List Users with Specific Columns

Source: https://developer.code42.com/cli/getting_started

Use the --columns option to specify which columns to display when listing users in a table format.

```bash
incydr users list --columns username,first_name,last_name
```

--------------------------------

### get_id_by_name

Source: https://developer.code42.com/sdk/clients/watchlists

Get a watchlist ID by either its type (ex: `DEPARTING_EMPLOYEE`) or its title in the case of `CUSTOM` watchlists.

```APIDOC
## get_id_by_name

### Description
Get a watchlist ID by its type or title.

### Method
GET

### Endpoint
/v2/watchlists/id/{name}

### Parameters
#### Path Parameters
- **name** (str, WatchlistType) - Required - A `WatchlistType` or the watchlist `title` for `CUSTOM` watchlists.

### Response
#### Success Response (200)
- **id** (str) - The watchlist ID.
```

--------------------------------

### Initialize Incydr Client

Source: https://developer.code42.com/sdk

Initialize the Incydr client with your Incydr API credentials. The API domain must be updated for your specific environment. Arguments can also be loaded from environment variables or .env files.

```python
import incydr

client = incydr.Client(
    url="api_domain",
    api_client_id="my_id",
    api_client_secret="my_secret" # (1)
)
```

--------------------------------

### Get Included Directory Group from Watchlist

Source: https://developer.code42.com/sdk/clients/watchlists

Retrieves details of a specific directory group included on a watchlist.

```python
>>> client.watchlists.v2.get_directory_group('your_watchlist_id', 'group_id_1')
```

--------------------------------

### Get Specific Policy

Source: https://developer.code42.com/sdk/clients/legal_hold

Retrieve details for a specific legal hold policy using its unique ID.

```python
client.legal_hold.v1.get_policy(policy_id="policy_id")
```