Monitoring API (1.0)

The RELEX Monitoring API provides a way to access monitoring data for RELEX services. The API allows customers to retrieve information about events that have occurred in their environments, such as file processing events and job execution events.

• File and job execution events related to RELEX supply chain planning services.
• API for pull access to file and job execution events.

File events and statuses

See the Get File Events endpoint for example file event payload.

File events are grouped by the file name originally used when uploading the file to RELEX. The file events endpoint returns a list of file names along with the current status of the data contained in each file. The status of a file can be one of the following:

Note that currently, the events cover only file processing up until the data is ready for use in supply chain planning.

Along with the status, the file events endpoint returns a list of events that have occurred.

Integration direction

The API provides information about the direction of data integration. Two types of integration are supported: inbound and outbound.

• Inbound integration is used to upload data to RELEX.
• Outbound integration is used to download data from RELEX.

The integration direction is indicated in the file event payload via the direction field. It can also be specified as an optional direction query parameter in the file event endpoint. Additionally:

• For inbound integrations, the file event payload includes the input_url field, which defines the full path of the file on the file server.
• For outbound integrations, the corresponding field is output_url.

Possible values for the 'direction' field are:

File rows

⚠️ Functionality is available from Plan 10.6 and higher.

Events with 'File import started' and 'File import completed' statuses also include information about the number of total and skipped rows in the file. This information is provided in 'file_rows' object. The 'file_rows' object contains the following fields:

The API does not provide information on the reason for skipping. This functionality is for informational purposes only and does not indicate errors during file processing unless the event status is "Error."

File size

⚠️ Functionality is available for SFTP file uploads

Shows the size of the file in bytes. The file size is included in the file_size field of the file event object.

Errors

If an error occurs during file processing, the endpoint will return a list of errors and the overall status of the file is "Error". Each error consists of a title that describes at what stage the error occurred and a details field that provides more information about the error. Example:

{
  "file": "Locations_2025-01-23.csv",
  "status": "Error",
  "timestamp": "2025-01-23T07:38:22Z",
  "file_size": 15,
  "events": [
    {
      "title": "File preparation started",
      "timestamp": "2025-01-23T07:38:16Z"
    }
  ],
  "errors": [
    {
      "title": "File preparation started",
      "details": "Validation failed: invalid value 'QTY' for column 'location_id'"
    }
  ]

The most typical errors involve file validation issues, such as missing required fields or incorrect data types. The following table lists the most common error messages:

Job events

See the Get Job Events endpoint for example job event payload.

The RELEX Monitoring API provides access to events linked to RELEX Plan job executions. By querying the job events endpoint, RELEX users can find out about the current state of scheduled jobs in RELEX Plan and whether or not they have completed successfully.

Jobs can have the following statuses:

Jobs can be filtered by a number of fields, including job name (job_name), the request will return jobs whose names contain the specified string.

RELEX customers can use the Monitoring API to:

• Monitor the progress of file processing events. Since the set of uploaded files is known, RELEX users can poll the Monitoring API to check the status of each file. If a file seems to be stuck in processing or has failed validation, the user can take action to correct the issue.
• Monitor the progress of job execution events. RELEX users can poll the Monitoring API to check the status of important jobs, such as supply chain planning calculation runs. A job failing to complete by a certain time can indicate a problem with the data or the RELEX service.

To start using the Monitoring API, ensure you have received your Client ID and Client Secret.

• Proceed to the Authentication section of this documentation, which covers how to get a valid token.
• Once you have a token, you can start using the API. Each request to any of the API endpoints should contain the token as described in Accessing the Monitoring API with tokens.
• All the available endpoints with their parameters are listed further below in this document.

A simple client code snippet in Python for reference is maintained in this repository:
https://github.com/relex/monitoring-api-demo

This section covers the data resources and technical details of the RELEX Monitoring API.

⚠️ All API requests must be made over HTTPS

Calls made over plain HTTP will fail and return an HTTP Status Code 400 Bad Request.

• A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. In practice, the resource most often maps to a corresponding database table, but not always.

The RELEX Monitoring API uses JSON as the format for data serialization. The JSON payload of the API has a root-level object that contains a meta-object and data array element.

All resources have a defined schema, and the details of each resource can be examined in the resource specifications in this document.

Date and time can be represented with a single field type expected to follow the ISO 8601 standard.

• date-time: With date and time combined. Format: yyyy-MM-ddThh:mm:ssZ, for example 2023-12-05T13:45:10Z.

The base URL for API requests depends on the region where the client is located. The following URLs should be used depending on the region:

Ensure that all API requests use the appropriate base URL for your region. For example, an API request for a customer in the EU would be:

GET https://eu.monitor.relexsolutions.com/api/v1/{customer_id}/events/file?env=test

For more examples, see the operations dropdown menu on the right side of the page.

Monitoring API resources respond to requests synchronously.

• Authentication is done synchronously and immediately when the client sends a request.
• The client receives a response with a 200 HTTP status code and the requested data if RELEX is able to accept the request successfully.
• If a non-2xx status code is returned, it indicates that RELEX's synchronous part has failed (500 status code) or the client's request is incorrect (4xx status code).

The RELEX Monitoring API uses standard HTTP response codes to indicate the various failures an API request can return. Codes in the 4xx range indicate an error on the client side, for example, the resource name was incorrect. Codes in the 5xx range indicate an error within RELEX services.

To convey details about errors to clients in JSON responses, the RELEX Monitoring API uses the RFC 7807 standard.

The RELEX Monitoring API imposes limits on incoming web requests to ensure performance, reliability, and efficiency. The API sets the following limits:

Overall limit

Overall limit is 100,000 requests per 5 minutes from a single customer IP address. Applies to all endpoints and requests to the API.

/api/v1/{customer}/events/job endpoint limits

The limit for the /api/v1/{customer}/events/job endpoint is 60 requests per minute from a single customer IP address.

/api/v1/{customer}/events/file endpoint limits

The limit for the /api/v1/{customer}/events/file endpoint is 60 requests per minute from a single customer IP address.

/health endpoint limits

The limit for the /health endpoint is 12 requests per minute from a single customer IP address.

If the limits are exceeded, an HTTP status code 429 is returned.

Exceeding limits

ℹ️ API limits are subject to change and appropriate values are determined during the implementation project.

The RELEX Monitoring API imposes no limits on return payloads. The payload size can be arbitrarily large.

This section describes the authentication methods and security-related requirements for the Monitoring API.

The Monitoring API utilizes OAuth 2.0 and OpenID Connect (OIDC) for authentication and authorization. OIDC is an authentication layer on top of OAuth 2.0 and JSON Web Tokens (JWT).

The API is secured via a JWT access token, which must be present in each request. The JWT is fetched from a token endpoint of RELEX Identity (an Identity Provider) using a Client ID and a Client Secret.

The Monitoring API implements authorization using the Client Credentials Grant. It is an authorization flow defined in the OAuth 2.0 specification, which is typically used for allowing access to resources in an automated context; that is, in a context with no human input.

The general steps involved are as follows:

1. Pre-requisites: Obtain the information the client needs to request an access token, and configure it in the client application. This is a one-time step.
2. Authorization: The client application requests an Access Token from RELEX Identity using the information provided in step 1.
3. Access: The client includes the provided Access Token in its requests, which allows it to access the Monitoring API endpoints.

Pre-requisites

To authenticate with RELEX Identity, the client needs:

• A Client ID
• A Client Secret
• A RELEX Identity token endpoint URL

These are provided by RELEX during the implementation process. After this information has been provided, it needs to be configured into the client application according to the application's specific needs.

Token endpoint based on region

The token endpoint URL for obtaining the JWT access token depends on the region. The following URLs should be used depending on the region where the client operates:

1. The client sends a POST request to the provided RELEX Identity token endpoint

• Content type needs to be set to application/x-www-form-urlencoded
• The Client ID, Client Secret, and client_credentials grant type must be included in the POST body as URL-encoded key-value pairs.

An example body:

client_id=my_client&client_secret=ZWFzdGVyZWdnCg&grant_type=client_credentials

2. RELEX Identity authenticates the client.
3. If authentication is successful, RELEX Identity authorizes the client by responding with a JSON object that contains:

• "access_token": the JWT token that needs to be used for accessing the Monitoring API
• "expires_in": the access token's time to live in seconds
• "token_type": information on how the token needs to be used, in this case, always set to "Bearer".
• "scope": The scope that the token grants access to.

Whenever the client accesses any Monitoring API endpoint, the client must provide the following:

• A valid access token in an Authorization -header, preceded by Bearer. An example header is Authorization: Bearer eyJ[...]jw.

When an Access Token expires, Monitoring API calls respond with 401 Unauthorized The client application has two options to keep it authenticated:

• The client may handle 401 responses and react by initiating a new Client Credentials grant, as described in the "Authorization steps" section.
• The client may monitor the token's expiry interval. When the grant is about to expire, the client fetches a new token.

Note: the Client Credentials grant type is not compatible with a construct such as refresh tokens, as mentioned in the protocol specification.

Client configuration

In our example flow, we have the following client-specific information:

• Client ID: customer_id-monitoring-api
• Client Secret: ZWFzdGVyZWdnCg
• Token endpoint URL(assuming that client is based in EU): https://identity.prod-eu.prod.cc.relexsolutions.com/monitoring_api_prod/connect/token

For demonstration purposes, we'll use curl as a client.

Authorization

1. We POST our authorization request to the token endpoint.

% curl -vd "grant_type=client_credentials&client_id=customer_id-monitoring-api&client_secret=ZWFzdGVyZWdnCg" https://identity.prod-eu.prod.cc.relexsolutions.com/monitoring_api_prod/connect/token
[...]
> POST /monitoring_api_prod/connect/token HTTP/1.1
> Host: identity.prod-eu.prod.cc.relexsolutions.com
> Accept: */*
> Content-Type: application/x-www-form-urlencoded
[...]
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=UTF-8
[...]

As a response body, we get the following:

{"access_token":"eyJ[...]jw","expires_in":3600,"token_type":"Bearer","scope":"example-scope"}

2. We extract the access token from the response field of the "access_token".
3. We use this token to access an API resource. In our case /api/v1/customer_id/events/file:

% curl -H "Authorization: Bearer eyJ[...]jw" https://eu.monitor.relexsolutions.com/api/v1/customer_id/events/file
> GET /api/1/customer_id/events/file HTTP/1.1
> Host: eu.monitor.relexsolutions.com
> Authorization: Bearer eyJ[...]jw
[...]
< HTTP/1.1 200 OK
[...]

As an additional layer of security, the Monitoring API can be configured to allow requests from only certain IP addresses or ranges. The recommendation is to always have an IP allowlist in place. The API does not support an explicit blocklist.

Endpoints for managing and retrieving customer-specific environment configurations.

Endpoints for fetching files and jobs event data.

Endpoints that report on the system's operational status and readiness for health checks or monitoring.