Getting Started

Base URL

• https://www.relationalmanager.com/api/

Auth Headers

• Authorization: Bearer <API_KEY>
• X-API-Key: <API_KEY>
• X-Request-Id: <REQUEST_ID> (optional)

First Call

1. Send POST /v1/score with a message payload.
2. Use a supported channel_type.
3. Set include_prediction=true only when you need SNMP forecast output.

Example Request

{
  "lenses": [1, 4],
  "persist": false,
  "include_prediction": true,
  "snmp_token": null,
  "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"
  }
}

Example Response

{
  "request_id": "req_123",
  "persisted": false,
  "lenses_used": [1, 4],
  "fallback_lens_used": true,
  "messages": [],
  "warnings": [],
  "prediction": {
    "forecast": {
      "1_hour": { "date": "2026-02-03", "score": 0.12 },
      "1_day": { "date": "2026-02-04", "score": 0.11 },
      "1_week": { "date": "2026-02-10", "score": 0.09 },
      "1_month": { "date": "2026-03-05", "score": 0.07 },
      "6_months": { "date": "2026-08-02", "score": 0.04 },
      "1_year": { "date": "2027-02-03", "score": 0.02 }
    },
    "cluster_scores": {
      "clarity": 0.22,
      "emotional_impact": 0.13,
      "engagement": 0.04,
      "trust_integrity": 0.03
    },
    "rim_analysis": {
      "current_state": "neutral"
    }
  },
  "snmp_token": "<opaque-token>",
  "results": [
    {
      "lens_id": 1,
      "lens_name": "Support Empathy",
      "score": 0.25,
      "classification": 1,
      "traffic_light": "yellow",
      "traffic_light_ranges": {
        "red": {"min": -1.0, "max": -0.2},
        "yellow": {"min": -0.2, "max": 0.4},
        "green": {"min": 0.4, "max": 1.0}
      },
      "traffic_light_ranges_source": "organization",
      "scoring_coverage": 0.8,
      "questions_total": 5,
      "questions_scored": 4,
      "prescriptions": [
        "Acknowledge the customer's concern before proposing a solution."
      ],
      "questions": [
        {
          "question_id": 101,
          "question": "Does the customer experience the response as empathetic?",
          "goal": "Determine whether the response acknowledges the customer's concern.",
          "indicator_name": "Customer Acknowledgement",
          "score": 0.72,
          "classification": 1,
          "scoring_status": "scored",
          "traffic_light": "green",
          "prescriptions": [
            "Example prescription text."
          ]
        }
      ]
    }
  ]
}

Next Steps

1. Use GET /v1/lenses to see selected and default lenses for the API key.
2. Import the Postman collection for quick testing.
3. To maintain emotional-state continuity across calls: store the snmp_token from each prediction response and pass it back as snmp_token in the next request. Omit it (or pass null) to start fresh.
4. Use GET /v1/lenses/{lens_id}/traffic-light-ranges to inspect the effective bands.
5. Use PUT /v1/lenses/{lens_id}/traffic-light-ranges with an org:write key to set organization-specific bands.

scoring_coverage is the proportion of lens questions that produced scores. Unconfigured or unavailable questions reduce coverage but do not reduce the aggregate score. Always inspect scoring_status; legacy-compatible score: 0.0 does not by itself mean that a question was scored.

Use each question's indicator_name, goal, score, and traffic_light for UI dials and indicator popovers. The question text is the interpretive form of the same lens-specific public measure, and the signal uses the parent lens ranges. Metric names, components, weights, and formulas remain private.

Warnings are non-fatal. For example, an invalid internal frame-component formula falls back to average scoring and appears in the top-level warnings array so integrators can report the configuration issue without dropping the score response.

Question prescriptions use configured guidance when available and otherwise select the authored low, medium, or high question prescription from the classification. Older neutral/adverse questions without tiered content use their authored goal. Lens prescriptions are prioritized summaries: none for green, up to two for yellow, and up to three for red.