With an extensive collection of endpoints, our REST API allows you to access most of the Red Canary portal UI functionality via your own applications.
The REST API is fully documented in standard OpenAPI Swagger UI format with interactive “Try it out” functionality. To access the Swagger documentation from the Red Canary portal, click your user icon at the top right, then click API.
The Swagger documentation describes every endpoint available in the API, along with the relevant HTTP methods and any optional parameters.
API Authentication
All calls made to the Red Canary REST API must include an authentication token to identity the user/application and grant access to the appropriate API resources.
Rather than being set globally, Red Canary API tokens are linked to the individual profile of the user who generates the token. As a result, the permissions available to the token are limited to the roles assigned to that user. For more information about User Roles, see Understand and Assign Roles.
Generating an API Token
Click your user icon at the top right and select View profile.
Go to Generate API Authentication Token in the Security Settings section.
Click Generate.
Copy the generated token and save it in a secure location.
You should change the token periodically as a precautionary security measure. Also, if you suspect your token has been compromised, generate a new one immediately. This will revoke any existing token linked to your user profile.
Using the API Token
To include the token in your API requests, pass it in via the X-API-Key custom header. For example:
--header 'X-API-Key: <myRedCanaryToken>'
If you’re using an API utility like Postman, select API Key as your Authorization method, use X-API-Key as the key name, and pass your API token as the key value.
Building the Request URL
Request URLs for the Red Canary REST API contain the following elements:
Base URL - https://<mySubdomain>.my.redcanary.co/
API Version - openapi/v3/
Endpoint - the specific endpoint from which to retrieve the data. For example, detections
Parameters - an optional ampersand-delimited set of parameters to further define the request
For example, this URL invokes the detections endpoint to return the ten most recent new threats in your environment:
https://canariacorp.my.redcanary.co/openapi/v3/detections?page=1&per_page=10&direction=desc&state=newSending the Request
The exact format for submitting the request will depend on the API client or utility you’re using, but the structure of the request follows typical REST API conventions:
HTTP Method - The action appropriate for the endpoint (GET, POST, PUT, PATCH, DELETE)
Location - The URL that identifies the resource (see above)
Headers - The required authentication token and (optionally) the expected content format
Request Body - JSON-formatted data needed for a POST, PUT, or PATCH request
For example, this simple curl command executes a GET on the detections endpoint and passes in the required authorization token in the header:
curl -X 'GET' \
'https://canariacorp.my.redcanary.co/openapi/v3/detections?page=1&per_page=10&direction=desc&state=new' \
-H 'accept: application/json' -H 'X-API-Key: abcdefg12345678'Interpreting the Response
For successful requests, the API returns a JSON response with the following structure:
meta
The meta object echoes back the API version and shows the total number of items found for this data type. For example:
"meta": {
"api_version": "v3.0",
"total_items": 496
},Note that for requests that can return multiple items, the actual number of items included in the response data will depend on the pagination parameters you specify in the request.
links
If the request returns multiple items, the response contains a links object with pre-populated URLs you can use to build pagination links in your application.
self - the URL that generated this response.
first - the URL for the first page of results.
prev - the URL for the previous page of results.
next - the URL for the next page of results.
count - the URL to retrieve the total count of items for this query.
For example:
"links": {
"self": "https://canariacorp.my.redcanary.co/openapi/v3/endpoint_users?direction=asc&page=3&per_page=5",
"first": "https://canariacorp.my.redcanary.co/openapi/v3/endpoint_users?direction=asc&page=1&per_page=5",
"prev": "https://canariacorp.my.redcanary.co/openapi/v3/endpoint_users?direction=asc&page=2&per_page=5",
"next": "https://canariacorp.my.redcanary.co/openapi/v3/endpoint_users?direction=asc&page=4&per_page=5",
"count": "https://canariacorp.my.redcanary.co/openapi/v3/endpoint_users?count_mode=true&direction=asc&page=3&per_page=5"
},data
Contains the full array/list of items (detections, endpoints, users, etc.). The contents of the data array depend on the item being returned, but typically include the following values and objects:
type - the category of item.
id - the unique ID assigned to this item in the Red Canary portal.
attributes - a collection of properties containing all the information available for this item. This might be as simple as a creation date, or can contain complex nested structures.
relationships - a list of other related items. For example, an Investigation will have relationships to one or more Events.
links - where relevant, provides URLs associated with this specific item. (As opposed to the top-level links object, which relates to the collection/list.) Typical categories of links are:
self - direct URL to the detail endpoint for this specific item
related - URLs to associated items (endpoints, users, events, etc.)
actions - URLs for operations on this item (acknowledge, escalate, etc.)
For example:
"data": [
{
"type": "Investigation",
"id": 16293,
"attributes": {
"created_at": "2026-05-13T20:59:16.006Z",
"updated_at": "2026-05-13T20:59:16.006Z"
},
"relationships": {
"originating_event": {
"links": {
"related": "https://canariacorp.my.redcanary.co/openapi/v3/events/18980"
},
"data": {
"type": "event",
"id": 18980
}
},
"events": [
{
"links": {
"related": "https://canariacorp.my.redcanary.co/openapi/v3/events/18980"
},
"data": {
"type": "event",
"id": 18980
}
}
],
"detections": [],
"endpoints": [],
"identities": []
},
"links": {
"self": {
"href": "https://canariacorp.my.redcanary.co/openapi/v3/investigations/16293"
}
}
}
]HTTP Response Codes
200 Success
The request completed successfully. Most responses will return a JSON object.
400 Bad Request
The request contains a malformed or invalid parameter.
403 Forbidden
Either the request header doesn’t contain a valid Red Canary API token, or else the token doesn’t grant the necessary permissions. See API Authentication and confirm the header format. If your headers are correct and the request still fails with a 403 error, verify that the user who owns the API token has an appropriate User Role assigned for the operation being performed. See Understand and Assign Roles.
404 Not Found
The API endpoint is malformed or not specified in the request URL, or the endpoint has been deprecated.
405 Not Allowed
The API endpoint doesn’t support this request method.
429 Too Many Requests/406 Not Accepted
To ensure the API remains performant and stable, Red Canary places a limit of 20 requests a minute and 10 requests per second on each incoming IP address. If you exceed the limit, you’ll receive HTTP response code 429 (Too Many Requests) or 406 (Not Accepted). If you reduce your request frequency below the limits and the issue persists, please reach out to Red Canary Support.
500 Internal Server Error
An unexpected error occurred within Red Canary. Make sure any parameters match the expected value type (integer, string, etc.). Check our Status Page for any degraded services. Reach out to Red Canary Support if the issue persists.
503 Unavailable
The endpoint or service is temporarily unavailable. Check our Status Page for any degraded services and try again later. Please reach out to Red Canary Support if the issue persists.