Integration API

Server-to-server JSON API for ConnectWare clusters. Base URL: https://cwtraceai.lovable.app

Authentication

Every request carries the cluster's key:

X-API-Key: <cluster api key>

Keys are issued per cluster on the Admin page, under "Clusters and API keys". An unknown key gets back 401 unauthorized. Browser calls are only accepted from the origin saved for that cluster; OPTIONS preflight is supported on every endpoint.

Typical flow

1. POST the raw trace to /api/public/diagnose.

2. POST the technician's thumbs up/down to /api/public/feedback.

If your cluster has a call-records API host and token saved on the Admin page, the diagnose call finds the audio-bearing legs in the trace and pulls their call-quality records for you — no separate step needed.

POST /api/public/diagnose

{
  "trace": "<raw nsflow SVG trace export>",
  "reported_issue": "caller hears one-way audio"
}

Only trace is required. Returns:

{
  "diagnosis": "markdown text for the technician",
  "diagnosis_id": "uuid",
  "pseudonymized_diagnosis": "same text with numbers and IPs tokenised",
  "media_analysis": [ { "call_id": "...", "verdict": "ok" } ],
  "qos_analysis":   [ { "call_id": "...", "verdict": "degraded" } ],
  "usage": {
    "model": "gemini-3.6-flash",
    "input_tokens": 18234,
    "output_tokens": 742,
    "estimated_cost_usd": 0.0165,
    "latency_s": 6.2
  }
}

Show diagnosis only. Hold onto diagnosis_id and pseudonymized_diagnosis and send them back with a bad rating. Phone numbers, names and IP addresses are replaced with tokens before the trace reaches the model, and restored only in the returned diagnosis.

POST /api/public/feedback

{
  "diagnosis_id": "uuid",
  "rating": "bad",
  "feedback_text": "missed the dial translation",
  "trace_url": "https://connectware.example.com/ns-api/?object=trace&action=export&k=...",
  "pseudonymized_diagnosis": "..."
}

On a bad rating both the trace link and the anonymized diagnosis are required so the case can be reviewed; the link is stored encrypted and deleted once a reviewer marks it done. On a good rating those two fields are ignored. Returns { "feedback_id": "uuid" }.

Example

curl -sS https://cwtraceai.lovable.app/api/public/diagnose \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $CW_TRACE_API_KEY" \
  -d '{ "trace": "<svg ...>", "reported_issue": "call drops after 30 seconds" }'