API Reference

REST API endpoints for cognitive scoring, event ingestion, and NBA recommendations.

Base URL

https://api.dicornerusa.com/v1

All API requests require an API key in the Authorization header: Bearer YOUR_API_KEY

Authentication

Request Header

Authorization: Bearer dc_live_abc123...

Get your API key from the Get API Key page. Builder tier keys are prefixed with dc_free_, Growth/Enterprise with dc_live_.

Ingest Events

POST/v1/events

Send behavioral events for cognitive scoring. Events are processed and scored within 300ms (p95).

Request Body (JSON)

{
  "user_id": "usr_12345",
  "session_id": "sess_abc",
  "events": [
    {
      "type": "page_view",
      "page": "pricing",
      "timestamp": "2026-02-13T10:30:00Z",
      "properties": {
        "dwell_time_ms": 45000,
        "scroll_depth": 0.85
      }
    }
  ]
}

Response (200 OK)

{
  "status": "accepted",
  "events_processed": 1,
  "scoring_available_in_ms": 300
}

Get Cognitive Scores

GET/v1/scores/:user_id

Retrieve the latest cognitive scores for a user across all five metrics.

Response (200 OK)

{
  "user_id": "usr_12345",
  "scores": {
    "decision_fatigue_index": { "value": 85, "level": "critical", "confidence": 0.89 },
    "trust_health": { "value": 72, "level": "moderate", "confidence": 0.91 },
    "drop_off_intent": { "value": 64, "level": "elevated", "confidence": 0.78 },
    "engagement_readiness": { "value": 45, "level": "low", "confidence": 0.82 },
    "conversion_likelihood": { "value": 31, "level": "at_risk", "confidence": 0.85 }
  },
  "scored_at": "2026-02-13T10:30:00.300Z",
  "model_version": "v2.4.1",
  "explainability": {
    "summary": "User experiencing decision fatigue from comparison paralysis. Trust intact but engagement declining.",
    "key_signals": ["pricing_view x4 in 10min", "feature_compare x3", "no_action 10min"]
  }
}

Get NBA Recommendations

GET/v1/nba/:user_id

Response (200 OK)

{
  "user_id": "usr_12345",
  "recommendations": [
    {
      "tier": "do_now",
      "action": "Simplify pricing comparison—reduce from 4 tiers to 2",
      "confidence": 0.87,
      "expected_impact": "+12% conversion",
      "effort": "medium",
      "time_to_effect": "<24 hours",
      "justification": "User stuck in comparison paralysis (DFI: 85). Reducing options lowers cognitive load.",
      "trace_id": "nba_trace_xyz789"
    }
  ]
}

Rate Limits

Plan	Requests/Hour	Events/Month
Builder (Free)	100	10,000
Growth	10,000	Up to 2M+
Enterprise	Unlimited	Custom

Error Codes

Code	Meaning
400	Bad Request. Invalid event schema or missing required fields
401	Unauthorized. Invalid or missing API key
403	Forbidden. Plan does not support this endpoint
404	Not Found. User or resource does not exist
429	Rate Limited. Exceeded plan rate limit
500	Server Error. Contact support with the trace_id

Ready to start integrating?

Get Your Free API Key