--- title: "Getting Started with the Red Canary REST API" slug: "red-canary-rest-api" updated: 2026-10-01T19:09:40Z published: 2026-10-01T19:09:40Z canonical: "docs.redcanary.com/red-canary-rest-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.redcanary.com/llms.txt > Use this file to discover all available pages before exploring further. # Getting Started with the Zscaler MDR REST API With an extensive collection of endpoints, our REST API allows you to access most of the Zscaler MDR 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 Zscaler MDR portal, click your user icon at the top right, then click **API**. ![](https://cdn.document360.io/75147bee-bf0d-444c-8afb-6e83b11ec0ef/Images/Documentation/rest-api_01.png?sv=2026-02-06&spr=https&st=2026-10-27T16%3A29%3A56Z&se=2026-10-27T17%3A29%3A56Z&sr=c&sp=r&sig=zMhDbjc2IOapyJN8ueWE2kYGcM48qv8KGLADIPf1mnQ%3D) The Swagger documentation describes every endpoint available in the API, along with the relevant HTTP methods and any optional parameters. ![](https://cdn.document360.io/75147bee-bf0d-444c-8afb-6e83b11ec0ef/Images/Documentation/rest-api_02.png?sv=2026-02-06&spr=https&st=2026-10-27T16%3A29%3A56Z&se=2026-10-27T17%3A29%3A56Z&sr=c&sp=r&sig=zMhDbjc2IOapyJN8ueWE2kYGcM48qv8KGLADIPf1mnQ%3D) ## API Authentication All calls made to the Zscaler MDR REST API must include an authentication token to identity the user/application and grant access to the appropriate API resources. > [!NOTE] > Rather than being set globally, Zscaler MDR 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](/doc/docs/understand-and-assign-roles). ### Generating an API Token 1. Click your user icon at the top right and select **View profile**. ![](https://cdn.document360.io/75147bee-bf0d-444c-8afb-6e83b11ec0ef/Images/Documentation/rest-api_03.png?sv=2026-02-06&spr=https&st=2026-10-27T16%3A29%3A56Z&se=2026-10-27T17%3A29%3A56Z&sr=c&sp=r&sig=zMhDbjc2IOapyJN8ueWE2kYGcM48qv8KGLADIPf1mnQ%3D) 2. Go to **Generate API Authentication Token** in the **Security Settings** section. 3. Click **Generate**. 4. Copy the generated token and save it in a secure location. ![](https://cdn.document360.io/75147bee-bf0d-444c-8afb-6e83b11ec0ef/Images/Documentation/rest-api_04.png?sv=2026-02-06&spr=https&st=2026-10-27T16%3A29%3A56Z&se=2026-10-27T17%3A29%3A56Z&sr=c&sp=r&sig=zMhDbjc2IOapyJN8ueWE2kYGcM48qv8KGLADIPf1mnQ%3D) > [!TIP] > 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: <myZscalerMDRToken>'` 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. ![](https://cdn.document360.io/75147bee-bf0d-444c-8afb-6e83b11ec0ef/Images/Documentation/rest-api_05.png?sv=2026-02-06&spr=https&st=2026-10-27T16%3A29%3A56Z&se=2026-10-27T17%3A29%3A56Z&sr=c&sp=r&sig=zMhDbjc2IOapyJN8ueWE2kYGcM48qv8KGLADIPf1mnQ%3D) ## Building the Request URL Request URLs for the Zscaler MDR 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: ```Custom https://canariacorp.my.redcanary.co/openapi/v3/detections?page=1&per_page=10&direction=desc&state=new ``` ## Sending 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](https://curl.se/) command executes a GET on the `detections` endpoint and passes in the required authorization token in the header: ```Custom 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: ```Custom "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: ```Custom "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 Zscaler MDR 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: ```Custom "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 Zscaler MDR API token, or else the token doesn’t grant the necessary permissions. See [API Authentication](/doc/docs/red-canary-rest-api#generate-an-api-key) 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](/doc/docs/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, Zscaler MDR 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 Zscaler MDR Support. **500 Internal Server Error** An unexpected error occurred within Zscaler MDR. Make sure any parameters match the expected value type (integer, string, etc.). Check our [Status Page](https://status.redcanary.com/) for any degraded services. Reach out to Zscaler MDR Support if the issue persists. **503 Unavailable** The endpoint or service is temporarily unavailable. Check our [Status Page](https://status.redcanary.com/) for any degraded services and try again later. Please reach out to Zscaler MDR Support if the issue persists.