search_projects
Search the notavibe catalog of open-source projects. The query matches project name, project description, and the category, ecosystem, kind, runtime, license_family and capabilities vocabulary facets; free-form repository topics are not matched. capabilities names what a project does, such as http-client, logging or database. Its values come from a fixed list kept by this catalog, and a project carries one only when a tag mapped to it is declared on the project's GitHub repository, or on an npm or PyPI package bound to that repository both ways: the repository's package.json names the npm package, or its root pyproject.toml names the PyPI package, and the package names the repository as its source. Most projects carry no capabilities. A query that is exactly a project's repository name, that name without a .js or .ts suffix or without its dots, or the name of an npm or PyPI package bound to the project, also matches that project. A facet match adds a project to the results and does not affect its position in them: results are ordered first by an exact match of the whole query to a bound npm or PyPI package name, then to one of those repository names, then by how closely the query matches name and description, then by published health signals. Every word of the query must match. A project's description is generated from its facets until its maintainer claims it and writes their own, so a query describing what a project does, such as "http router" or "date parsing", matches only where those words appear in a project name, in a claimed description, or among the words a facet value matches; a project name or a category, kind or ecosystem word is what a generated entry reliably matches. The catalog currently covers one ecosystem: javascript-typescript. Its coverage of that ecosystem is partial: it does not yet hold every JavaScript or TypeScript project published to npm. category, ecosystem, kind, runtime, license_family and capabilities are also exact filters. Every filter supplied is applied, and a filter combines with the query rather than replacing it: query with ecosystem returns only projects that match the text AND carry that ecosystem. A filter narrows the result set and never changes the order. category, ecosystem, kind, runtime, license_family and capabilities accept only values from this catalog's managed vocabulary; a value outside it is refused and the refusal names the accepted values, so it is never returned as an empty result. A capabilities filter takes one value and matches every project that carries it among its capabilities. topics is unavailable: this catalog does not populate the topics dimension, so a call carrying topics is refused as invalid arguments rather than answered with an empty result. The response echoes the filters that were applied. Search returns projects at or above this catalog's discovery floor — a repository whose measured activity is too low to be ranked is held out of search even though the catalog holds it and has signals for it. A repository with no ecosystem is held out of search the same way: a project's ecosystem comes from the package store its package is published to. A repository with no package keeps an ecosystem it already had from its main language only if it was already in the catalog when this rule took effect; the main language never gives a repository an ecosystem it did not already have. A call with a query also returns projects in the settling hold, a waiting period a new or changed entry serves before it can be ranked. A call with filters and no query lists ranked projects only, so it excludes projects in the settling hold. A call with filters and no query also carries held: held.count is the number of projects that match the same filters but are in the settling hold and so are not returned, and it is 0 when there are none. When held.count is above 0, held.first_rankable_on is the earliest date (YYYY-MM-DD, UTC) on which one of them is currently scheduled to become rankable. A held project is returned by a call that also carries a query it matches. A call with a query carries no held. held is absent from a call with filters and no query only when the count could not be read. An empty result therefore means that nothing matched among the projects that call can return, which is not the same as the catalog having no such project: a project known by name can still be retrieved by exact identity with get_project. At most limit results are returned, and at most 100 when limit is omitted; limit accepts an integer from 1 to 100, and any other value is refused as an invalid argument. The response field truncated is true when more matched and the list was cut at that size, and no total is reported. When truncated is true the response also carries next_cursor, an opaque string. A call with the same query and filters and with cursor set to that string returns the next results in the same order; while the catalog is unchanged, no result is repeated or skipped across calls. The last page carries no next_cursor. A cursor is accepted only with the query and filters it was issued for; any other cursor value is refused as an invalid argument. A cursor is accepted with any limit: the next results start after the last result of the response that issued it. Returns compact result rows: repository host and numeric id, slug, name, description, claim state, category, and the maintenance-rhythm and contribution-breadth health bands. What each band means, and its cut-point, is published on the catalog's methodology page (/methodology) and returned by get_methodology. Read-only. Serves catalog schema v1.
Schema valid · SHA-256 09dcdf51669b…
View input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Full-text query over project name, project description, and the category/ecosystem/kind/runtime/license_family/capabilities facets. A facet match scopes the result set and never orders it. Combines with any filter below."
},
"category": {
"type": "string",
"description": "Exact filter on the category dimension. Managed set: a value outside it is refused, and the refusal names the accepted values."
},
"ecosystem": {
"type": "string",
"description": "Exact filter on the ecosystem dimension. Managed set: a value outside it is refused, and the refusal names the accepted values."
},
"kind": {
"type": "string",
"description": "Exact filter on the kind dimension. Closed set: a value outside it is refused, and the refusal names the accepted values."
},
"runtime": {
"type": "string",
"description": "Exact filter on the runtime dimension. Closed set: a value outside it is refused, and the refusal names the accepted values."
},
"license_family": {
"type": "string",
"description": "Exact filter on the license-family dimension. Closed set: a value outside it is refused, and the refusal names the accepted values."
},
"topics": {
"type": "string",
"description": "Unavailable: this catalog does not populate the topics dimension, so a call carrying topics is refused as invalid arguments rather than answered with an empty result."
},
"capabilities": {
"type": "string",
"description": "Exact filter on one value of the capabilities dimension, which names what a project does. Managed set: a value outside it is refused, and the refusal names the accepted values. Matches every project that carries the value among its capabilities."
},
"cursor": {
"type": "string",
"description": "The next_cursor value from a previous response with the same query and filters. Selects the results after that response's last result. A value that is malformed or was issued for other arguments is refused."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"description": "The most results to return, from 1 to 100; 100 when omitted. A value outside that range is refused. A cursor is accepted with any limit."
}
},
"description": "All properties combine with AND. Filters narrow the result set and never affect the order. A call with every property omitted returns an empty result set.",
"additionalProperties": false
}