REST API Documentation FAQ

Are Create, Retrieve, Update and Delete operations available in the APIs or are they Read-Only?

API operations include (for certain endpoints): GET, POST, DELETE, PATCH. 

Do the API Retrieve operations allow for retrieval of records that have changed within a specific interval?

Retrieve operations for specific intervals are available for supported endpoints.  

If multiple changes have occurred to a record does the API allow retrieval of each of those records or just the most recent record? Do the records include timestamps of when the change occurred?

No. A single record (the most recent) is available. Changes are not reflected in the API, but audit log information is available via the API.

Do the APIs enforce pre-set data validation rules during Create and Update operations to ensure data integrity?

Yes. Pre-set data validation rules on Create and Update operations exist. 

How do back-end (server) applications authenticate to the API? How do front-end (user) applications authenticate to the API? 

Red Canary has one API. Authentication is completed using a per-Red Canary account API token. 

Do you supply any SDKs for your API? (.net SDK, javascript SDK, etc.)

No. Red Canary does not provide an SDK for the API.  

What are the API Rate Limits?

Per second rate limits are placed on the number of API requests you make per IP. To avoid rate limits, we recommend that you do not exceed both 20 requests per minute and 10 requests in one second.

If your IP address exceeds the rate limits, you will receive a response with an HTTP status code of 429 (Too Many Requests).

How do I reset an API key?

If you suspect your key has been compromised, reset it immediately in Red Canary. This will revoke any existing key you've used before.

1. From Red Canary, click your profile icon, and then click View profile.

2. Scroll to Generate API Authentication Token in the Security Settings section.

3. Click Generate.

Note: Red Canary API keys are not set globally. API keys are generated and linked only to the individual user profile. Your API key will work with all Red Canary subdomains that are linked to your profile. Similarly, if you reset your API key, the key is no longer valid across subdomains you are linked to.

Bulk assign reporting tags to Endpoints via API?

If there are multiple endpoints that need reporting tags assigned, use the Red Canary API to apply them in bulk.

1. Ensure you have the full list of endpoints by ID.

2. Enumerate the IDs.

3. Make a call to PUT /openapi/v3/endpoints/{id}/reporting_tags/{reporting_tag_name}?value={value} with the desired reporting tag name and value.

Example

PUT /openapi/v3/endpoints/20/reporting_tags/Hotel?value=Hilton

This results in the following Reporting tag and value.

Note: You will need to update the URL above with the {subdomain}, {reporting_tag_name}, and {value}. 

Please click Red Canary API for more information.