---
title: "Semantic search grouped into categories"
method: POST
path: "/v1/discover/categories"
tags: ["Discover"]
---

# Semantic search grouped into categories

`POST /v1/discover/categories`

The shared discover pipeline's match set aggregated into category nodes with per-node match counts — the semantic twin of `GET /public/v1/categories?q=` (same response shape; counts are within the bounded semantic match set).

## Request body

- DiscoverCategoriesRequest
  - `q` string, required — Natural-language search query.
  - `minScore` number — Per-call override for the post-rerank score floor — same semantics as the legacy POST /v1/discover body field.

## Response `200`

Category nodes with semantic match counts

- 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
- `401` — Unauthorized — missing or invalid credentials
- `403` — Forbidden — caller has no workspace or no access
- `500` — Internal server error

## Changes

> 9 revisions in range; 5 could not be searched.

- **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/v1/discover/categories/post.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)