---
title: "LEARN glossary catalog (PG-backed, Phase 1 structural)"
method: GET
path: "/api/learn/glossary"
tags: ["Education"]
---

# LEARN glossary catalog (PG-backed, Phase 1 structural)

`GET /api/learn/glossary`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/learn/glossary`
- Auth: none declared

Return the glossary catalog as
`{terms: [...], total: N, source: "pg"|"empty"}`.

Behavior:
  - PG-populated: returns rows from v114 learn_glossary via
    `pg_get_glossary_terms(tier, category)`. `source` = "pg".
  - PG empty / unavailable: returns `{terms: [], total: 0,
    source: "empty"}`. The in-app renderer falls back to
    `window.GLOSSARY` so an empty response is a graceful "use
    client-side dict" signal, not an error.

No JSON fallback at the route layer — the source-of-truth IS
static/js/glossary.ts (already in the page as `window.GLOSSARY`).
Adding a server-side JSON fallback would couple two source
families to a third (PG, JS, JSON) for no behavioral gain.

## Query parameters

- `tier` string, nullable: Optional tier filter — 'beginner', 'basic', 'detail', or 'core'. Omit to return the full 1,391-entry catalog.
- `category` string, nullable: Optional category slug filter (e.g. 'personal-finance', 'valuation'). Matches the GLOSSARY_CATEGORY mapping.

## Response `200`

Successful Response

- LearnGlossaryResponse: `GET /api/learn/glossary` response. Top-level shape: `{terms: [...], total: N, source: "pg"|"empty"}`. `terms` is required; FE renderer iterates without a null-check (CLAUDE.md §"Contract tests" defect-class anchor).
  - `terms` unknown[], required
    - unknown
  - `total` integer, nullable
  - `source` string, nullable

## Other responses

- `422`: Validation Error
- `500`: Internal Server Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)