---
title: "Search public package listings on this deployment."
method: GET
path: "/v1/community/listings"
tags: ["community"]
---

# Search public package listings on this deployment.

`GET /v1/community/listings`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/community/listings`
- Auth: HTTP bearer

Search public package listings on this deployment. Default ranking is relevance and community ratings; pass sort=newest for last published first. Pass category to browse one closed listing category. Use `communityGet` for full detail before forking.

Org permission: `search:read`.

## Query parameters

- `query` string, required: Natural-language search query for public packages.
- `limit` integer: Maximum number of matches to return (default 10, max 50).
- `sort` 'best' | 'newest': best (default) ranks by relevance and ratings. newest orders matching listings by last community publish, including republishes.
- `category` 'integrations' | 'examples' | 'productivity' | 'apps' | 'utilities' | 'other': Optional browse category. integrations, examples, productivity, apps, and utilities come from package.json#kody.category (or tag inference). other is the uncategorized remainder.

## Response `200`

Success.

- object
  - `outcome` 'matches' | 'no_matches', required
  - `guidance` string, required
  - `matches` object[], required
    - `average_stars` number, nullable, required
    - `rating_count` integer, required
    - `average_adaptation_effort` number, nullable, required
    - `fork_count` integer, required
    - `listing_id` string, required
    - `name` string, required
    - `kody_id` string, required
    - `description` string, required
    - `tags` string[], required
    - `category` 'integrations' | 'examples' | 'productivity' | 'apps' | 'utilities' | 'other', required
    - `version` string, nullable, required: package.json#version from the pinned listing snapshot, or null when the author did not set a string version.
    - `owner_anonymous` true, required
    - `trusted` boolean, required: Always false. Catalog listings have no trusted-review mark.
    - `relevance` number, nullable, required: Blended lexical and vector query relevance from 0 to 1; null when browsing with an empty query.
    - `published_at` string, required: Last community publish time for this listing. Republishing updates this timestamp.
    - `public_url` string, required: Canonical shareable user URL ({base}/@{username}/{package-name-leaf}); share this URL with humans.

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

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