Partner Literacy Suite API

4.1 List media for an employer

GET /api/integrations/v1/groups/{externalEmployerId}/media

Path: externalEmployerId — your employer id (mapped at onboarding).

Query: limit (default 25, max 50), cursor, kinds (default video,audio), locale (optional BCP 47).

{
  "externalEmployerId": "acme-corp-2026",
  "groupId": "WC0126",
  "items": [
    {
      "learningResourceId": 1042,
      "kind": "video",
      "title": "Your 2026 Medical Plan Overview",
      "subtitle": "Plain-language walkthrough",
      "category": "Medical",
      "locale": null,
      "updatedAt": "2026-06-15T18:22:11.000Z",
      "videoProjectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "audioVariants": []
    }
  ],
  "nextCursor": null
}

Catalog items never include deliveryUrl or long-lived CDN URLs.

4.2 Get a single media item

GET /api/integrations/v1/media/{learningResourceId}?externalEmployerId={externalEmployerId}

externalEmployerId is required for entitlement checks.

4.3 Mint a delivery URL

POST /api/integrations/v1/media/{learningResourceId}/delivery

{
  "externalEmployerId": "acme-corp-2026",
  "variant": "summary"
}

For audio, variant is summary or deep. Omit variant for video.

{
  "learningResourceId": 1042,
  "kind": "video",
  "variant": null,
  "deliveryUrl": "https://example.cdn/embed/…",
  "expiresAt": "2026-07-07T01:20:00.000Z",
  "contentType": "text/html",
  "deliveryMode": "embed"
}

• Default TTL is 300 seconds from mint time.
• Mint when the user starts playback — not when listing the catalog.
• Do not persist deliveryUrl; store learningResourceId + externalEmployerId instead.
• If expired, mint again with a new POST.

6.1 Ask a question

POST /api/integrations/v1/groups/{externalEmployerId}/chat
Idempotency-Key: <uuid>   (recommended)
X-Request-Id: <uuid>      (optional)

{
  "question": "What is my in-network deductible on the PPO?",
  "externalUserId": "partner-worker-abc123opaque",
  "disclaimerAccepted": true,
  "disclaimerVersion": "v1",
  "sessionId": "optional-uuid-for-multi-turn",
  "chatHistory": [
    { "role": "user", "content": "Do we have an HSA?" },
    { "role": "assistant", "content": "Yes — the HDHP option includes an HSA..." }
  ]
}

Sandbox (bi_test_): externalUserId may be omitted.

{
  "answer": "Based on your 2026 medical plan documents, the PPO in-network deductible is $1,500 per person...",
  "citations": [
    { "source": "2026 Medical SBC.pdf", "resourceId": 1042 }
  ],
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "disclaimer": "Educational summary based on employer-provided plan documents. Not legal, tax, or medical advice."
}

With Idempotency-Key, identical requests replay the cached response for 24 hours (X-Idempotency-Replay: true).

7.1 Get limits and usage

GET /api/integrations/v1/groups/{externalEmployerId}/chat-limits

{
  "externalEmployerId": "acme-corp-2026",
  "groupId": "WC0126",
  "limits": {
    "dailyQuestionCap": 500,
    "monthlyQuestionCap": 10000,
    "dailySpendUsdCap": 150,
    "monthlySpendUsdCap": 2000
  },
  "usage": {
    "today": { "questions": 42, "costUsd": 0.18 },
    "monthToDate": { "questions": 1203, "costUsd": 4.92 }
  }
}

7.2 Update per-employer limits

PUT /api/integrations/v1/groups/{externalEmployerId}/chat-limits

{
  "dailyQuestionCap": 750,
  "monthlyQuestionCap": 15000,
  "dailySpendUsdCap": 200,
  "monthlySpendUsdCap": 3000,
  "oeUpliftUntil": "2026-11-30T23:59:59.000Z",
  "oeDailyQuestionCap": 1500
}

All fields optional; omitted fields are unchanged. Open Enrollment uplift fields are optional.

7.3 Webhooks (Growth+ tier)

When configured, BI sends HMAC-signed HTTPS POSTs for usage alerts: chat.usage_warning, chat.cap_reached, chat.cap_reset.

Verify header X-BI-Signature: t={unix},v1={hmac} over {timestamp}.{body} using your webhook secret.