Redox Platform API

The Redox Platform API is a RESTful JSON utility that you can use to automate your Redox organization's monitoring and workflows. You can call Platform API endpoints to perform administrative functions (e.g., manage access control), manage your Redox assets (e.g., sources, destinations, filters), search and export log data, and more. Review a list of available Platform API endpoints.

The Platform API relies on user-level API keys to authenticate requests. User-level API keys are located in the user menu on the bottom left of the Redox dashboard. View user-level API keys in the dashboard or learn how to authenticate a user-level API key.

All requests via the Platform API should be sent to https://api.redoxengine.com/platform/{endpoint}. Check out our Platform API reference for more detailed endpoint specifications.

Depending on the Platform endpoint, you may need to include path and/or request parameters. Path parameters go directly into the endpoint URL while the request parameters go in the request body.

Typically, required parameters (e.g., log ID if querying for a specific log) should go in the URL path while optional parameters can be included in the request body.

Depending on the endpoint you're using, you may need to include some of these parameters:

Any optional parameters for filtering, sorting, or controlling response output can be included in the query string (e.g., ?param=123).

Any datetime request parameters are in ISO 8601 format (e.g., 2023-01-10T19:46:40.081Z).

Every response from the Platform API is contained in a wrapper object, even when the returned value is already an object. This payload wrapper contains a meta object, which contains metadata about your request, and a payload object, which contains the results related to your request.

The payload object may contain fields that return a single result (singular field name) or an array of results (plural field name).

1
{
2
  "meta": {
3
    "version": "1.1.0",
4
  },
5
  "payload": {
6
    "record": {
7
            // ...single record
8
    },
9
     //OR
10
    "records": [{
11
            // ...first record
12
        },{
13
        //...second record
14
      }]
15
  }
16
}

Pagination breaks up the results of a query into pages, or sets. So instead of returning all possible results at once, you can view a page at a time.

Refer to the supported query parameters in each endpoint schema to paginate results. Then you can query for pages of results using the URLs in the meta.page.links object in the paginated response.

1
{
2
  "meta": {
3
    "version": "3.1.3",  // Required, the version of this payload
4
    "page": {
5
      "links": {
6
        "first": "<path-to-first-page>",
7
        "prev": "<path-to-first-page>", 
8
        "self": "<path-to-this-returned-page>",
9
        "next": "<path-to-page-after-returned-page>"
10
      },
11
     // ... other metadata about pagination ...
12
    },
13
    // ... other metadata about the request/operation/response ...
14
  },
15
  "payload": {
16
    "records": [{
17
      // ... first record here ... 
18
    }]
19
  }
20
}

The URL values return the relevant page of results. Sometimes, only a subset of links are available. For example, a next property isn't populated on the last page of results. But you can always use the available URLs to fetch additional pages of results.

The meta.page object may contain other properties or objects. For example, you may see metadata counts, which display the total size of the result set, including totalRecords, totalPages, and pageSize. These may be useful for troubleshooting purposes, but shouldn't be functionally relied upon.

Platform API requests are limited to about 1 minute before timing out and returning a 504 Gateway Timeout. If your request keeps timing out, we recommend defining a shorter time period for results by using the updatedAfter and updatedBefore or createdAfter and createdBefore request parameters.

If there are any errors, they're returned in a standard payload. For reference, check out a list of possible error codes.

1
{
2
  "meta": {
3
    "version": "1.2.3",  // Required, the version of this payload
4
    // ... other metadata about the request/operation/response
5
  },          
6
  "payload": {
7
    "error": {
8
      "id": "failure-instance-identifier",  // Optional, unique ID for this error
9
      "code": "failure.type.code",  // Required
10
      "title": "Failure Type Title String",  // Required
11
      "detail": "Specific failure message",  // Required
12
      "transient": true,  // Required, true implies error might resolve and the request should be retried
13
      "status": 401,  // Optional, response status code
14
      "meta": {}  // Optional, error metadata
15
    },
16
    "errors": [{}]  // Returned if multiple errors
17
  }
18
}