Redox Platform API

The Redox Platform API is a RESTful JSON utility that you can use to automate your organization's monitoring and Redox configuration workflows. You can call Platform API endpoints to programmatically:

  • export log data;
  • create and manage traffic alert rules;
  • manage destinations (or endpoints) in your Redox dashboard organization;
  • review and export transaction usage data; or
  • manage custom endpoint authentication.

The Platform API is meant to be used by back-end servers accessing Platform API resources and FHIR® endpoints. It also allows you to use record locator service.

Platform API requests

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.

User API Keys menu option
User API Keys menu option

Endpoint URLs

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.

Parameters

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.

Path parameters

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

Path parameter
Type
Description
:version
string
Depending on the Platform endpoint you're using, you may need to include which version of the Platform API you're using. This only applies if the endpoint is available for both v0 and v1.
organizationID
string
If the Platform endpoint is specific to a Redox dashboard organization, then you must include the relevant organization ID. You can locate your organization ID on the Organization Profile page of the Redox dashboard.
environment
string
If the Platform endpoint is specific to an environment (e.g., development, staging, production), then you must identify the relevant environment. For example, traffic alert rules apply to specific environments, so you'd need to identify the environment in the endpoint path.
destinationID
string
If the Platform endpoint is specific to one of the destinations in your dashboard organization (i.e., one of your connection's configured endpoints that you want to send API requests to), then you must include the relevant destination ID.

Request parameters

Any optional parameters (e.g., for filtering, sorting, or controlling response output) can be included in the query string like this: ?param=123. Just a note, any datetime request parameters are in ISO 8601 format (e.g., 2023-01-10T19:46:40.081Z).

If you want to paginate or count results in the response, you can add these parameters:

Query parameter
Type
Description
_page
Integer
Include this if you want the response to return a specific page number from the results. 1 is the first page.
_count
Integer
Define the number of records to return per page. The maximum value per page is 50.

Responses

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).

Example: Platform API response format

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

You can page through results via the links provided in the meta.page object in the response. Specifically, you can page through a set of results using the next and prev paths indicated within the meta.page.links object. At the beginning or end of a set of results, the prev or next links are undefined.

You may also see metadata counts, which display the total size of the result set, including totalRecords, totalPages, and pageSize.

Example: Platform API pagination and count in 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>", // undefined on first page
8
"self": "<path-to-this-returned-page>",
9
"next": "<path-to-page-after-returned-page>" // undefined on last page
10
},
11
"currentPage": 1, // Required
12
"pageType": "offset", // Required
13
"pageSize": 20, // Optional, size of each page
14
"totalRecords": 124, // Optional
15
"totalPages": 7 // Optional
16
},
17
// ... other metadata about the request/operation/response ...
18
},
19
"payload": {
20
"records": [{
21
// ... first record here ...
22
}]
23
}
24
}

Timeouts and errors

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.

Example: Platform API error

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
}