Redox Platform API

The Redox Platform API is an API tool you can use to manage your Redox configuration. With the Platform API, you can:

• Configure your setup: Create and manage your connectivity settings (i.e., sources, destination, authentication) in your Redox organization.
• Manage user access: Perform the administrative functions of assigning user roles to any users in your Redox organization.
• Set up data operations: Create and manage filters, config modifiers, and translation sets without having to switch contexts by logging into another UI.
• Monitor your traffic: Set up traffic alert rules to proactively monitor your traffic or search and export your logs.

In more technical terms, the Redox Platform API is a RESTful JSON utility that you can use to automate your Redox organization’s monitoring and workflows. Review a list of available Platform API endpoints.

All Platform API requests should be sent to https://api.redoxengine.com/platform/{endpoint}. For the {endpoint} segment, check out each endpoint for the specific endpoint URL.

You authenticate a Platform API request with a user-level API key. Find and manage them in the user menu on the bottom left of the Redox dashboard. Learn how to authenticate a user-level API key.

Depending on the Platform API endpoint, the request might include path, query, and/or request parameters:

• Path parameters: These are typically required parameters, like a log ID if querying for a specific log. These go directly into the endpoint URL. See path parameters in the table below.

  Example: Path parameters

  bash

  Copy

  1
  curl 'https://api.redoxengine.com/platform/v1/organizations/{organizationId}/logs/{logId}' \
• Query parameters: These are extra parameters for filtering, sorting, or controlling response output. These go in the query string (e.g., ?param=123).you can use in the URL to refine a query. Any datetime request parameters are in ISO 8601 format (e.g., 2023-01-10T19:46:40.081Z).

  Example: Query parameter

  bash

  Copy

  1
  curl 'https://api.redoxengine.com/platform/v1/dry-run/logs/{logId}?inlineOperationTemplates=true&serviceRegion=US_EAST_1'
• Request parameters: These are typically optional parameters to refine the query further or populate the settings for a new asset you’re creating. The --data header usually contains the request body with these types of parameters.

  Example: Request parameters

  bash

  Copy

  1
  curl 'https://api.redoxengine.com/platform/v1/environments/{environmentId}/logs/search/metadata' \
  2
  --request POST \
  3
  --header 'Authorization: Bearer $API_TOKEN' \
  4
  --header 'accept: application/json' \
  5
  --header 'content-type: application/json' \
  6
  --data '{
  7
    "facilityCode": "2.16.840.1.113883.3.6147.458",
  8
    "dataMode": "realtime",
  9
    "serviceRegion": "AWS_USA_EAST_1",
  10
    "dataModel": "PatientAdmin",
  11
    "eventType": "Transfer",
  12
    "createdAfter": "2023-01-01T00:00:00.000Z",
  13
    "createdBefore": "2023-01-31T23:59:59.999Z",
  14
    "updatedAfter": "2023-01-01T00:00:00.000Z",
  15
    "updatedBefore": "2023-01-31T23:59:59.999Z",
  16
    "sourceId": "797f5a94-3689-4ac8-82fd-d749511ea2b2",
  17
    "destinationId": "d0a0ebc7-d6b4-4f3c-a5af-5761a8148e3a",
  18
    "type": "receive",
  19
    "status": "succeeded"
  20
  }'

These common path parameters typically have to be included in the endpoint URL, depending on the endpoint you’re using:

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: Contains metadata about your request.
• payload object: Contains the results related to your request. These fields 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. 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 to paginate results. 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 might contain other properties or objects. For example, you might 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 time out after about 1 minute, at which point Redox returns a 504 Gateway Timeout. If a request continues timing out, we recommend defining a shorter time period for results by using these request parameters:

• updatedAfter and updatedBefore
• createdAfter and createdBefore

If there are any errors, they’re returned in a standard payload.

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
}

Here are a couple of common Platform API status errors:

Check out other possible HTTP status codes.