Endpoints — Marketplace

Marketplace discovery, cluster access, and credit-based query endpoints.

GET /api/marketplace/clusters

Browse marketplace clusters (free, no credit cost). Authentication: Required Authorization: Any authenticated user Credit Cost: None (discovery only)

Query Parameters

Response (200 OK)

{
  "data": [
    {
      "cluster_id": "Cigna

 IOP",
      "payer": "Cigna",
      "denial_type": "Frequency Limit",
      "loc": "IOP",
      "maturity_tier": "Mature",
      "precedent_count": 23,
      "contributor_count": 4,
      "win_rate": 0.739,
      "avg_resolution_days": 12.4,
      "most_recent_precedent_date": "2024-04-10",
      "preview": {
        "top_evidence_types": [
          "Psychiatric evaluation (92% of successful appeals)",
          "GAF assessment (89%)",
          "Clinical progress notes (78%)"
        ],
        "query_cost_credits": 1.75
      }
    }
  ],
  "total": 347,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

Visibility Rules

Marketplace Gate: Clusters only appear once they have:

2+ distinct tenants as contributors (MIN_CLUSTERS_FOR_MARKETPLACE)
At least 1 precedent per contributor

GET /api/marketplace/clusters/:clusterId/preview

Authentication:

Authorization:

Credit Cost:

Response (200 OK)

{
  "cluster_id": "Cigna

 IOP",
  "payer": "Cigna",
  "denial_type": "Frequency Limit",
  "loc": "IOP",
  "maturity_tier": "Mature",
  "precedent_count": 23,
  "contributor_count": 4,
  "win_rate": 0.739,
  "avg_resolution_days": 12.4,
  "evidence_kit_composite": {
    "required": ["Psychiatric evaluation", "GAF assessment", "Clinical progress notes"],
    "recommended": ["Collateral contact documentation"],
    "optional": ["Prior treatment records"]
  },
  "top_evidence_types": [
    { "description": "Psychiatric evaluation", "frequency": "92%" },
    { "description": "GAF assessment", "frequency": "89%" },
    { "description": "Clinical progress notes", "frequency": "78%" }
  ],
  "query_cost_credits": 1.75
}

GET /api/marketplace/clusters/:clusterId

Access full cluster details (paid query, deducts credits). Authentication: Required Authorization: Any authenticated user Credit Cost: Calculated as 1 + (precedent_count / 10 × 0.5) credits

Query Cost Formula

cost = 1 + (ipo_count / 10 × 0.5)

Examples:
10-precedent cluster   → 1.5 credits
20-precedent cluster   → 2 credits
50-precedent cluster   → 3.5 credits
100-precedent cluster  → 6 credits

Pre-Query Checks

Balance Check: If tenant balance < cost, returns 402 Payment Required

Cluster Exists: If cluster doesn't exist or has <2 contributors, returns 404

Access Granted: If checks pass, deducts credit from ledger and returns full cluster data

Response (200 OK)

{
  "data": {
    "cluster_id": "Cigna

 IOP",
    "payer": "Cigna",
    "denial_type": "Frequency Limit",
    "loc": "IOP",
    "maturity_tier": "Mature",
    "precedent_count": 23,
    "contributor_count": 4,
    "win_rate": 0.739,
    "avg_resolution_days": 12.4,
    "evidence_kit_composite": { ... },
    "top_evidence_types": [ ... ],
    "narrative_patterns": {
      "most_common_sections": [
        { "section": "Clinical Justification", "frequency": "100%" },
        { "section": "Evidence of Functional Impact", "frequency": "96%" }
      ],
      "persuasion_strategies": [
        "Cite GAF score as objective measure of functional impairment",
        "Reference payer's own policy requiring functional review, not duration-based limits"
      ]
    },
    "precedents": [
      {
        "id": "prec-uuid-1",
        "precedent_name": "Cigna IOP Frequency Limit Victory 2024",
        "outcome": "Won",
        "time_to_resolution_days": 14,
        "evidence_score": "Strong"
      }
    ]
  },
  "receipt": {
    "receipt_id": "receipt-uuid",
    "event_type": "query_burn",
    "amount": -1.75,
    "balance_after": 98.25,
    "timestamp": "2024-04-14T10:35:00Z",
    "receipt_hash": "sha256-hash"
  }
}

Errors

402 Payment Required — Insufficient credits

{
  "error": "INSUFFICIENT_CREDITS",
  "balance": 1.2,
  "cost": 1.75,
  "shortfall": 0.55,
  "message": "Purchase credits to access this cluster"
}

404 Not Found — Cluster doesn't exist or doesn't meet marketplace gate

{
  "error": "NOT_FOUND",
  "message": "Cluster not found or does not meet marketplace visibility requirements (requires 2+ contributors)"
}

GET /api/marketplace/profiles

List payer enforcement profiles (free, discovery only). Authentication: Required Authorization: Any authenticated user Credit Cost: None

Response (200 OK)

{
  "data": [
    {
      "payer": "Cigna",
      "cluster_count": 7,
      "precedent_count": 127,
      "avg_win_rate": 0.68,
      "enforcement_profile": {
        "denial_reason_codes": ["FREQ_LIMIT", "MED_NECESSITY", "AUTH_REQUIRED"],
        "appeal_overturn_rate": 0.42,
        "avg_days_to_decision": 12
      },
      "query_cost_credits": 3.5
    }
  ]
}

Profile Availability: Requires MIN_CLUSTERS_FOR_PROFILE (default: 3) clusters with that payer.

GET /api/marketplace/profiles/:payer

Access payer enforcement profile (paid query, deducts credits). Authentication: Required Authorization: Any authenticated user Credit Cost: Varies by profile maturity; typically 3–5 credits

Response (200 OK)

Full enforcement profile with all clusters for that payer:

{
  "data": {
    "payer": "Cigna",
    "profile_maturity": "Mature",
    "cluster_count": 7,
    "precedent_count": 127,
    "enforcement_profile": { ... },
    "clusters": [
      {
        "cluster_id": "Cigna

 IOP",
        "precedent_count": 23,
        "win_rate": 0.739
      }
    ]
  },
  "receipt": { ... }
}

Errors

402 Payment Required — Insufficient credits 404 Not Found — Payer doesn't have enough clusters for profile

GET /api/marketplace/contribution-scores

Leaderboard of top contributors across all clusters. Authentication: Required Authorization: Any authenticated user Credit Cost: None (read-only)

Query Parameters

Response (200 OK)

{
  "data": [
    {
      "tenant_id": "tenant-uuid-1",
      "overall_score": 1450,
      "total_precedents_contributed": 78,
      "clusters_active_in": 12,
      "top_cluster": {
        "cluster_id": "Cigna

 IOP",
        "cluster_score": 180
      }
    }
  ],
  "total": 34,
  "limit": 20,
  "offset": 0
}

GET /api/marketplace/contribution-scores/:clusterId

Contribution scores for a specific cluster. Authentication: Required Authorization: Any authenticated user Credit Cost: None

Response (200 OK)

{
  "data": [
    {
      "tenant_id": "tenant-uuid-1",
      "cluster_id": "Cigna

 IOP",
      "ipo_count": 10,
      "gap_score": 50,
      "outcome_bonus": 25,
      "total_score": 135
    },
    {
      "tenant_id": "tenant-uuid-2",
      "cluster_id": "Cigna

Parameter	Type	Default	Example
limit	integer	20	50
offset	integer	0	100
payer	string	(none)	Cigna
denial_type	string	(none)	Frequency Limit
loc	string	(none)	IOP
maturity_tier	string	(none)	Embryonic, Emerging, Mature, Canonical
min_precedent_count	integer	(none)	10
min_win_rate	float	(none)	0.5
Frequency Limit
Frequency Limit
Frequency Limit
Frequency Limit
Parameter	Type	Default
limit	integer	20
offset	integer	0
order_by	string	total_score
Frequency Limit
Frequency Limit
Frequency Limit

 IOP",
      "ipo_count": 10,
      "gap_score": 50,
      "outcome_bonus": 22,
      "total_score": 132
    }
  ]
}

Scoring Formula:

ipo_count — Number of precedents contributed

gap_score — (ipo_count / total_cluster_ipo_count) × 100

outcome_bonus — +5 for Won, +2 for Partial outcomes

total_score — (ipo_count × 10) + gap_score + outcome_bonus

Endpoints — Marketplace

GET /api/marketplace/clusters

Query Parameters

Response (200 OK)

Visibility Rules

GET /api/marketplace/clusters/:clusterId/preview

Response (200 OK)

GET /api/marketplace/clusters/:clusterId

Query Cost Formula

Pre-Query Checks

Response (200 OK)

Errors

GET /api/marketplace/profiles

Response (200 OK)

GET /api/marketplace/profiles/:payer

Response (200 OK)

Errors

GET /api/marketplace/contribution-scores

Query Parameters

Response (200 OK)

GET /api/marketplace/contribution-scores/:clusterId

Response (200 OK)

See Also