---
title: "List catalog categories"
method: GET
path: "/public/v1/categories"
tags: ["Public Registry"]
---

# List catalog categories

`GET /public/v1/categories`

Flat, id-based list of category nodes (top groups, leaf categories, provider nodes) with live endpoint counts and the exact catalog total. Use the returned `id` values with `GET /public/v1/endpoints?category=…` (+ optional `q=`).

## Query parameters

- `category` string — Node id filter. A TOP id returns the top plus its member nodes; a leaf/provider id returns that single node. Omit for every node.
- `q` string — Optional free-text query — counts become per-node search hit counts (same BM25 semantics as `GET /public/v1/endpoints?q=`). Nodes with zero hits are omitted.

## Response `200`

Category nodes

- PublicCategoriesResponse
  - `items` PublicCategoryNode[], required — Flat node list: tops (priority order) then leaves/providers (alphabetical). Hidden, unlinked, and zero-count nodes omitted.
    - union
      - TopCategoryNode
        - `id` string, required — Stable node id (e.g. "social-media", "twitter", "apify").
        - `displayName` string, required — Display label — manifest copy for tops/leaves; resolved provider display name for provider nodes.
        - `description` string — Short blurb, when available.
        - `endpointCount` integer, required — Live endpoint count (with `q`: endpoints matching the query). Top counts are DISTINCT-document counts across their members.
        - `kind` 'top', required — System group node.
        - `children` string[], required — Ordered member node ids (linked leaves in display order, then provider nodes).
      - LeafCategoryNode
        - `id` string, required — Stable node id (e.g. "social-media", "twitter", "apify").
        - `displayName` string, required — Display label — manifest copy for tops/leaves; resolved provider display name for provider nodes.
        - `description` string — Short blurb, when available.
        - `endpointCount` integer, required — Live endpoint count (with `q`: endpoints matching the query). Top counts are DISTINCT-document counts across their members.
        - `kind` 'category', required — Leaf category node.
        - `parents` string[], required — Top ids this leaf is linked under (a leaf may have several parents).
      - ProviderCategoryNode
        - `id` string, required — Stable node id (e.g. "social-media", "twitter", "apify").
        - `displayName` string, required — Display label — manifest copy for tops/leaves; resolved provider display name for provider nodes.
        - `description` string — Short blurb, when available.
        - `endpointCount` integer, required — Live endpoint count (with `q`: endpoints matching the query). Top counts are DISTINCT-document counts across their members.
        - `kind` 'provider', required — Derived provider node.
        - `provider` string, required — Provider slug.
        - `url` string, uri — The provider's own public website, when it declares one (`ProviderInfo.url`). Absent otherwise — never null, never empty. Provider nodes only: a leaf/top category has no vendor to link to. This is display copy, NOT the endpoint-level documentation URL (`docUrl`), which stays private to `POST /v1/inspect`.
        - `parents` string[], required — Top ids this provider node is linked under (a node may have several parents).
  - `totalEndpointCount` integer, required — Exact number of catalog-visible endpoints (with `q`: matching the query) — drives the All rail count.

## Other responses

- `400` — Bad request — input failed validation
- `500` — Internal server error

## Changes

- **2026-08-16** `6a927c84fe15` — 1 info
  - added the optional property `items/items/oneOf[#/components/schemas/ProviderCategoryNode]/url` to the response with the `200` status

[Change history](https://skmtc.dev/monid/apis/monid-api/changes/public/v1/categories/get.md)

---

[API](https://skmtc.dev/monid/apis/monid-api.md) · [All operations](https://skmtc.dev/monid/apis/monid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monid/monid-api/revisions/6e720e7547e3/schema)