# Platform API

The <u>**Redox Platform API**</u> is an API tool you can use to manage your Redox configuration. With the Platform API, you can:

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

> **Interactive UI option**
>
> If you _do_ want a UI option for managing your Redox organization, you can use our interactive dashboard. [Learn about the Redox dashboard](/basics/using-the-redox-dashboard).

In more technical terms, the <u>**Redox Platform API**</u> 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](https://docs.redoxengine.com/permalink/platform-api-landing-page).

> **What are endpoints and destinations?**
>
> An endpoint or a destination is the receiving side of an API data exchange, but they have slightly different meanings in a Redox context.  
>
> - Sending to a <u>**destination**</u> means sending an API request to an external endpoint—whether a standard URL or cloud—owned by one of your connections.
> - Calling a Redox Platform API <u>**endpoint**</u> means sending an API request to a Redox Platform endpoint URL to achieve a certain goal within your Redox organization. 

## Where to send a Platform API request

All Platform API requests should be sent to `https://api.redoxengine.com/platform/{endpoint}`. For the `{endpoint}` segment, [check out each endpoint ](https://docs.redoxengine.com/permalink/platform-api-landing-page)for the specific endpoint URL.

You authenticate a Platform API request with a <u>**user-level API key**</u>. 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](/api-reference/platform-api/authenticate-a-user-level-api-key).

![Access user API keys from the user menu](https://images.ctfassets.net/cl3wt5ehhnlv/4C0OemtbCuqv3JuNa5RXZ/8a062a9f679e2c5a1a1cd1229353f0f0/User-menu_user-api-keys.png)

*Access user API keys from the user menu*

> **No logs for the Platform API**
>
> <u>Logs</u> visualize how traffic moves between you and your connection, specifically to exchange healthcare data. [Learn about logs](/basics/data-exchange-with-redox/logs-for-data-exchange).
>
> Since Platform API requests are for managing your Redox configuration or performing administrative functions, we don’t generate logs for these API calls. However, if you want to track how users are operating within your Redox organization, you might be interested in <u>**audit events**</u>. [Learn about auditing your Redox platform](/basics/managing-access-for-your-redox-organization/auditing-your-redox-platform).

## What a Platform API request looks like

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

- <u>**Path parameters**</u>: 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
curl 'https://api.redoxengine.com/platform/v1/organizations/{organizationId}/logs/{logId}' \

```


- <u>**Query parameters**</u>: 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
curl 'https://api.redoxengine.com/platform/v1/dry-run/logs/{logId}?inlineOperationTemplates=true&serviceRegion=US_EAST_1'
```


- <u>**Request parameters**</u>: 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
curl 'https://api.redoxengine.com/platform/v1/environments/{environmentId}/logs/search/metadata' \
--request POST \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
  "facilityCode": "2.16.840.1.113883.3.6147.458",
  "dataMode": "realtime",
  "serviceRegion": "AWS_USA_EAST_1",
  "dataModel": "PatientAdmin",
  "eventType": "Transfer",
  "createdAfter": "2023-01-01T00:00:00.000Z",
  "createdBefore": "2023-01-31T23:59:59.999Z",
  "updatedAfter": "2023-01-01T00:00:00.000Z",
  "updatedBefore": "2023-01-31T23:59:59.999Z",
  "sourceId": "797f5a94-3689-4ac8-82fd-d749511ea2b2",
  "destinationId": "d0a0ebc7-d6b4-4f3c-a5af-5761a8148e3a",
  "type": "receive",
  "status": "succeeded"
}'
```



### Path parameters

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

| **Path parameter** | **Type** | **Description** |
| --- | --- | --- |
| `:version` | string | This is the version of the Platform API endpoint, which you can find in the endpoint spec. |
| `organizationID` | string | Some endpoints require you to specify which Redox organization you’re making the request for. You can locate your organization ID on the <u>Organization Profile</u> page of the Redox dashboard. |
| `environmentID` | string | Some endpoints require you to specify which environment you’re making the request for (e.g., development, staging, production). For example, traffic alert rules only apply to specific environments, so you’d need to identify which environment in the endpoint path. |

## What a Platform API response looks like

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:

- <u>`meta`</u> <u>object</u>: Contains metadata about your request.
- <u>`payload`</u> <u>object</u>: Contains the results related to your request. These fields return a single result (singular field name) or an array of results (plural field name).

**Example: Platform API response format**

```json
{
  "meta": {
    "version": "1.1.0",
  },
  "payload": {
    "record": {
            // ...single record
    },
     //OR
    "records": [{
            // ...first record
        },{
        //...second record
      }]
  }
}
```

### Paginated results

<u>**Pagination**</u> 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 <u>**query parameters**</u> 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.

**Example: Pagination links**

```json
{
  "meta": {
    "version": "3.1.3",  // Required, the version of this payload
    "page": {
      "links": {
        "first": "<path-to-first-page>",
        "prev": "<path-to-first-page>", 
        "self": "<path-to-this-returned-page>",
        "next": "<path-to-page-after-returned-page>"
      },
     // ... other metadata about pagination ...
    },
    // ... other metadata about the request/operation/response ...
  },
  "payload": {
    "records": [{
      // ... first record here ... 
    }]
  }
}
```

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.

## Handling timeouts

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`

## Troubleshooting errors

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

**Example: Platform API error**

```json
{
  "meta": {
    "version": "1.2.3",  // Required, the version of this payload
    // ... other metadata about the request/operation/response
  },          
  "payload": {
    "error": {
      "id": "failure-instance-identifier",  // Optional, unique ID for this error
      "code": "failure.type.code",  // Required
      "title": "Failure Type Title String",  // Required
      "detail": "Specific failure message",  // Required
      "transient": true,  // Required, true implies error might resolve and the request should be retried
      "status": 401,  // Optional, response status code
      "meta": {}  // Optional, error metadata
    },
    "errors": [{}]  // Returned if multiple errors
  }
}
```

Here are a couple of common Platform API status errors: 

| **Error code** | **Notes** |
| --- | --- |
| `200` | A Platform API request references a <u>collection of objects</u> (e.g., `/resources`) but there aren’t results for that resource, or asset. The `200` code is returned with an empty results array. |
| `404` | A Platform API request references a <u>specific object</u> (e.g., `/<resource>/:id`), but that resource, or asset, doesn’t exist. |

[Check out other possible HTTP status codes](/api-reference/error-handling-and-responses).

## Endpoint categories

Each of these categories contains Platform endpoints that allow you to manage different parts of your Redox organization via API:

- [Access control](https://docs.redoxengine.com/permalink/c5916b35-060e-5a01-bc33-924b4f516397-get-org-roles)
- [Alerts](https://docs.redoxengine.com/permalink/e5beac77-1041-54ff-bcf5-39c16db55d66-get-alerts-v-2)
- [Audit events](https://docs.redoxengine.com/permalink/6ef881e7-9e37-5e4a-9688-4411444891a5-get-audit-events)
- [Configs](https://docs.redoxengine.com/permalink/3ac4953e-3da2-5d88-83eb-7988804a8b17-get-configs)
- [Config modifiers](https://docs.redoxengine.com/permalink/c8f6dc2f-b7d9-5c46-b952-a9d974f26765-get-config-modifiers-by-environment)
- [Credentials](https://docs.redoxengine.com/permalink/a61bdf29-4d00-5edf-9b92-1e2cd981745a-get-auth-strategies)
- [Destinations](https://docs.redoxengine.com/permalink/c39153e8-32e2-56b7-ba79-1de926c01387-get-destinations)
- [Environments](https://docs.redoxengine.com/permalink/a2a88cbf-3b12-52ab-9d4d-979be5a0ba7a-get-environments)
- [Filters](https://docs.redoxengine.com/api-reference/platform-api/platform-api-reference/filters/get-env-filters/)
- [Logs](https://docs.redoxengine.com/permalink/51b1bce8-37f9-5367-8bf9-427e42e2f5ac-get-log-by-id)
- [OAuth API keys](https://docs.redoxengine.com/permalink/94ed0609-6ab4-565c-8e68-558333ad5e1d-get-oauth-keys)
- [Promotions](https://docs.redoxengine.com/permalink/00e540fd-52b8-5bcd-8b56-e392e9db575e-promote-asset)
- [Sources](https://docs.redoxengine.com/permalink/e7d2a75e-db15-5c0b-9690-dd785b4cfd1e-get-sources)
- [Subscriptions](https://docs.redoxengine.com/permalink/3437bdce-37ef-57aa-96b6-04b92db75b08-create-subscription)
- [Transaction usage](https://docs.redoxengine.com/permalink/4ae6bb1b-f2ed-5b21-9a60-7c9952817c64-get-org-products)
- [Translation sets](https://docs.redoxengine.com/permalink/ce6bd0a8-065e-58ba-82a9-cf3bf4237dcb-get-value-sets)
- [VPNs](https://docs.redoxengine.com/permalink/7f5f408a-b4bf-58b1-9d09-ab54c02d2530-get-org-vpns)

## Authenticate Platform APIs

Learn how to authenticate your Redox Platform API requests with user-level API keys.

[Learn more](/api-reference/platform-api/authenticate-a-user-level-api-key)

## Articles in this section

- [Authenticate a user-level API key](/api-reference/platform-api/authenticate-a-user-level-api-key)
