Java (OkHttp) Integration

Example POST /v1/score using OkHttp.

Prereqs

• RI_API_KEY (string)
• BASE_URL (string), default https://www.relationalmanager.com/api
• OkHttp 4.x

import java.io.IOException;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class RiExample {
    public static void main(String[] args) throws IOException {
        String baseUrl = System.getenv().getOrDefault("BASE_URL", "https://www.relationalmanager.com/api");
        String apiKey = System.getenv("RI_API_KEY");

        String json = """
{
  "lenses": [1, 4],
  "persist": false,
  "message": {
    "message_id": "m2",
    "conversation_id": "c1",
    "text": "I'm not sure this will work.",
    "channel_type": "chat",
    "channel_id": "support",
    "sender_id": "u2",
    "sender_type": "user",
    "lang": "en",
    "timestamp": "1716561012"
  },
  "previous_message": {
    "message_id": "m1",
    "conversation_id": "c1",
    "text": "We can try a few options.",
    "channel_type": "chat",
    "channel_id": "support",
    "sender_id": "u1",
    "sender_type": "agent",
    "lang": "en",
    "timestamp": "1716560950"
  }
}
""";

        OkHttpClient client = new OkHttpClient();
        RequestBody body = RequestBody.create(json, MediaType.get("application/json"));
        Request request = new Request.Builder()
            .url(baseUrl + "/v1/score")
            .addHeader("Authorization", "Bearer " + apiKey)
            .addHeader("Content-Type", "application/json")
            .post(body)
            .build();

        try (Response response = client.newCall(request).execute()) {
            String responseBody = response.body() != null ? response.body().string() : "";
            System.out.println(response.code() + " " + response.header("X-Request-Id"));
            System.out.println(responseBody);
        }
    }
}

Lens Aggregates, Indicators and Traffic Lights

The score JSON now exposes lens_name, weighted score, scoring_coverage, traffic_light, full question text, and scoring_status.

Use each question's indicator_name, score, scoring_status, and traffic_light for UI dials. The signal uses the parent lens ranges, while internal metric details remain private.

The lens prescriptions array contains prioritized guidance for yellow/red signals and is empty for green.

RequestBody ranges = RequestBody.create(
    "{\"traffic_light_ranges\":{\"red\":{\"min\":-1.0,\"max\":-0.2},"
        + "\"yellow\":{\"min\":-0.2,\"max\":0.4},"
        + "\"green\":{\"min\":0.4,\"max\":1.0}}}",
    MediaType.get("application/json"));
Request update = new Request.Builder()
    .url(baseUrl + "/v1/lenses/1/traffic-light-ranges")
    .header("Authorization", "Bearer " + apiKey)
    .put(ranges)
    .build();

The update key requires org:write. Do not interpret a question's zero without its status.