Marketplace / Docs / Search & Discovery

Search & Discovery

Find packages by searching, filtering, sorting, and tapping into trending and recommendation endpoints.

Jump to section

How to find packages on the Singularity Marketplace — searching, filtering, sorting, and the discovery endpoints that power trending, recommendations, and similar-package surfaces.

Overview

Every published package in the marketplace is indexed by name, description, tags, category, and package type. Two surfaces let you query that index:

  • The web /search page — what most users use, with URL-driven filters and pagination.
  • The CLI snippbot marketplace search — same backend, optimized for scripting.

Beyond keyword search, the registry exposes three discovery endpoints — Trending, Recommendations, and Similar Packages — that surface relevant packages without an explicit query.

Searching from the Web

Visit /search. The page reads its state from the URL, so every filter, sort, and page number is shareable as a link.

URL parameters:

  • q — search query string.
  • category — restrict to a specific category.
  • type — restrict to a specific package type (e.g. tool, agent_profile).
  • sort — one of trending, newest, most-installed, name (the four shown in the sort bar).
  • pricing — free or paid. Omit for all.
  • page — page number, defaults to 1.

Example: /search?q=docs&type=tool&sort=newest&pricing=free

The results grid shows 24 packages per page (server-side default) with a paginator. The search box is a React island that updates the URL as you type.

Sort Options

The four sort orders exposed in the UI sort bar are also accepted by the registry search endpoint:

  • trending — default. A weighted score balancing recent installs, activity, and rating.
  • newest — most recently created packages first.
  • most-installed — highest lifetime install count first.
  • name — alphabetical by package name.

The registry also accepts rating as a valid sort value at the API level, though the web UI's filter bar does not expose it. Pass it via ?sort=rating in the URL if you want highest-rated first.

Invalid sort values return a 400 Bad Request listing the allowed set.

Filters

Three filters compose orthogonally — you can combine any or all:

Filter Values Where it appears
category Free-form (e.g. development, productivity, data-tools). See /categories for the canonical list. URL only today
type One of the package types: agent_profile, agent, tool, mcp_server, workflow, hook, scheduled_job, shared_asset, sandbox_preset, channel. URL only
pricing free or paid (empty = all) UI bar

Active non-default filters render as removable chips next to the sort bar so you always know what's narrowing your results.

Pagination

Results are paginated. The response from GET /api/v1/search includes:

  • total — total matching package count.
  • page — current page (1-indexed).
  • per_page — requested page size (default 20 from the API, 24 from the /search page, capped at 100).
  • total_pages — ceiling of total / per_page.

The web UI renders a numbered paginator beneath the results grid; the CLI prints (page X/Y) in the header.

Autocomplete Suggestions

The registry exposes a lightweight autocomplete endpoint used by the search bar:

GET /api/v1/search/suggest?q=foo&limit=10

Returns { "suggestions": [...] } — typically a small set of package names that start with or contain the query. The minimum query length is 2 characters (shorter queries return an empty list immediately). Limit is capped at 20.

GET /api/v1/discover/trending

Returns a curated trending list assembled by the registry. The /trending page in the web UI is the canonical surface for this. Trending is unauthenticated; results are the same for everyone.

Recommendations

Personalized recommendations are computed from a list of packages you already have installed:

POST /api/v1/discover/recommendations
Content-Type: application/json

{
  "installed_package_ids": ["<uuid1>", "<uuid2>", "..."]
}

The caller passes the installed package IDs explicitly (up to 100). The endpoint is unauthenticated — there's no per-user personalization on the server side; the "personalization" comes from whatever IDs you supply. Response: { "packages": [...] }.

Similar Packages

GET /api/v1/packages/{publisher_name}/{package_name}/similar
GET /api/v1/packages/{publisher_name}/{package_name}/similar?limit=8

Returns packages that share tags, category, or co-install patterns with the given package. Path-parameterized by publisher and package name — pass the package via its handle, not a UUID. The limit query param defaults to 8 and is capped at 20. Useful for "you might also like" surfaces — designed to be embedded on package detail pages.

Searching from the CLI

The CLI search command takes the same parameters as the web URL:

snippbot marketplace search                            # browse, no query
snippbot marketplace search "web scraping"             # full-text query
snippbot marketplace search --type tool --sort newest  # filter + sort
snippbot marketplace search "agent" --category development --limit 50
snippbot marketplace search foo --json                 # JSON output for scripts

Flags:

  • --category, -c — restrict to a category.
  • --type, -t — restrict to a package type.
  • --sort, -s — trending (default), newest, most-installed, name.
  • --page — page number (default 1).
  • --limit — results per page (default 20).
  • --json — machine-readable JSON output.

The text output renders a table with name, type, version, install count, and a truncated description. Use --json in scripts to get the full PackageResponse shape including id, tags, description, and timestamps.

Tips for Discoverability

For publishers who want their packages to surface in search and trending:

  • Lead the description with the use case. "Scrape data from JavaScript-rendered websites" beats "A package built on Playwright". The first 50 characters become the search-result preview.
  • Tag with concrete tools and frameworks. Tags are matched verbatim — playwright, puppeteer, selenium are useful; automation is too broad.
  • Pick the right package_type. Filtering by type is one of the most common search refinements; an agent_profile mistagged as tool gets filtered out of the wrong searches.
  • Watch the trend. If your install count is climbing, trending placement amplifies that — keep momentum with frequent (but meaningful) releases rather than long quiet gaps.
  • Title and display name matter. Auto-complete suggestions match on name. A clear, searchable display name (@you/jira-search, not @you/jstool) is its own SEO.

CLI Reference

For the full set of flags and subcommands, see the Snippbot CLI reference.

Search and discovery commands:

  • snippbot marketplace search [QUERY] [--category C] [--type T] [--sort S] [--page N] [--limit N] [--json] — search and filter.
  • snippbot marketplace info @publisher/package — detailed info for one package.
  • snippbot marketplace install @publisher/package[@version] — install a search result.