Python Example - RC DRAFT

Create the Script

Create a text file with the following contents and save as example.py in your working directory. Replace <myRedCanarySubdomain> with the name of your subdomain and <myRedCanaryToken> with your API token.

import requests

# Build a GET request.
url = 'https://<myRedCanarySubdomain>.my.redcanary.co/openapi/v3/endpoints'
headers = {'X-Api-Key': '<myRedCanaryToken>'}

# Send the request and save the response.
response = requests.get(url, headers=headers)

# Print the response body.
print(response.content)

Run the Script

Go to the command line and run your example:

python3 example.py

The script should print a JSON object containing the first page of endpoints associated with the subdomain.

Add Parameters to the Request

You can use HTTP parameters to customize the results of your request. See the Swagger documentation for the full list of supported parameters for each API method.

Example: Limit the number of endpoints returned

Use the per_page parameter to limit the number of endpoints returned.

1. Edit example.py and modify the GET request as follows:
   

   # Build a GET request.
   url = 'https://<myRedCanarySubdomain>.my.redcanary.co/openapi/v3/endpoints'
   headers = {'X-Api-Key': '<myRedCanaryToken>'}
   params = {'per_page': '1'}
   
   # Send the request and save the response.
   response = requests.get(url, headers=headers, params=params)

2. Save example.py and run it.
   The script prints a JSON object containing one endpoint.

   {
       "meta": {
           "api_version": "v3.0",
           "total_items": 273026
       },
       "links": {
           "self": "https://canariacorp.my.redcanary.co/openapi/v3/endpoints?page=1&per_page=1",
           "first": "https://canariacorp.my.redcanary.co/openapi/v3/endpoints?page=1&per_page=1",
           "prev": null,
           "next": "https://canariacorp.my.redcanary.co/openapi/v3/endpoints?page=2&per_page=1",
           "count": "https://canariacorp.my.redcanary.co/openapi/v3/endpoints?count_mode=true&per_page=1"
       },
       "data": [
           {
               "type": "Endpoint",
               "id": 100000205827745,
               "attributes": {
                   "display_identifier": "2229028802084652514",
                   "hostname": "2229028802084652514",
                   "endpoint_network_addresses": [],
                   "ip_addresses": [],
                   "mac_addresses": [],
                   "monitoring_status": null,
                   "endpoint_status": null,
                   "registration_time": "2025-10-18T12:48:10.014Z",
                   "last_checkin_time": null,
                   "last_activity_at": null,
                   "physical_memory_bytes": null,
                   "platform": null,
                   "operating_system": null,
                   "supports_response": null,
                   "supports_isolation": null,
                   "is_isolated": false,
                   "is_decommissioned": false,
                   "sensor": {
                       "type": "EndpointSensorMetadata",
                       "id": "",
                       "attributes": {
                           "version": null,
                           "last_checkin_time": null,
                           "registration_time": "2025-10-18T12:48:10.014Z",
                           "group": []
                       }
                   },
                   "source": {},
                   "cloud_provider": null,
                   "cloud_provider_prettified": null,
                   "cloud_provider_account_id": null,
                   "cloud_provider_instance_id": null,
                   "reporting_tags": {},
                   "sensor_groups": [],
                   "updated_at": "2025-10-18T12:48:16.872Z"
               },
               "relationships": {},
               "links": {
                   "self": {
                       "href": "https://canariacorp.my.redcanary.co/openapi/v3/endpoints/100000205827745"
                   },
                   "ui": {
                       "href": "https://canariacorp.my.redcanary.co/endpoints/100000205827745"
                   },
                   "detections": []
               }
           }
       ]
   }