Hanzo
OpenapiCatalog

Browse searches AND browses the cross-org catalog: every project, app and site…

Browse searches AND browses the cross-org catalog: every project, app and site the fleet has built, whichever org built it.

GET /v1/catalog

Addresshttps://api.hanzo.ai/v1/catalog
MethodGET
Operationget_catalog
AuthAuthorization: Bearer $HANZO_API_KEY

Browse searches AND browses the cross-org catalog: every project, app and site the fleet has built, whichever org built it.

It reads TWO corpora and returns them as one page — the published, world-readable catalog that every caller sees, plus the caller's OWN org's private entries when the request carries a validated principal. Each row says which it came from in scope, so a client can warn before sharing a link. An anonymous caller simply gets the published one; no filter can ever widen a caller into another tenant's corpus, because the query that would return it is never run for them.

A request with no q is a browse rather than a search, and both answer the same shape: the page, the total before paging, and the facet counts over the whole matching set.

Request

10 fields.

FieldInTypeRequiredDescription
qquerystringQ is the free-text query the lexical index scores relevance on.
orgquerystringOrg narrows to one builder org: hanzo | lux | zoo.
kindquerystringKind narrows to repo | site.
originquerystringOrigin narrows to what a row IS to you: template | community | third-party | product.
archetypequerystringArchetype narrows to one project archetype.
languagequerystringLanguage narrows to one implementation language.
templatequerystringTemplate narrows a lane to ONE lineage: the id of the parent everything returned was forked from.
forkablequerystringForkable is tri-state: "true" selects the forkable rows, "false" selects the rest, and anything else — including absent — applies no filter at all.
limitquerystringLimit caps the page at 200, default 50.
offsetquerystringOffset is where the page starts, default 0, with the same tolerance.

Response

StatusBodyMeaning
200catalogPageok

200 body — 24 fields.

FieldInTypeAlwaysDescription
databodyEntry[]Data is the page of matching entries, most recently updated first.
data[].archetypebodystringArchetype is WHAT KIND OF THING this is, from a closed and ordered list — model | contract | chain | sdk | template | infra | site | app — derived from the…
data[].descriptionbodystringDescription is the repository's own one-line GitHub description, carried verbatim.
data[].forkablebodybooleanForkable is NOT omitempty: false is an answer here, not a missing field.
data[].idbodystringID is "<org>/<name>" and is the corpus's primary key: a re-published entry updates in place under it rather than accumulating duplicates, so it is the one…
data[].kindbodystringrepo | site
data[].languagebodystringLanguage is the repository's primary implementation language as GitHub computes it ("Go", "TypeScript"), and the case is GitHub's.
data[].licensebodystringLicense is the terms that upstream work carries, in whichever form the half that credited it had: an SPDX id ("MIT", "Apache-2.0") on a GitHub fork, free text…
data[].namebodystringName is the short identifier inside the org — the repository's name, or the site's slug — and is the half of ID after the slash.
data[].notebodystringNote is why a row is NOT in the published catalog, set by the admission gate (gate.go) on the sites it holds back.
data[].orgbodystringhanzo | lux | zoo
data[].originbodystringOrigin is WHAT THIS IS TO YOU: template | community | third-party | product (origin.go owns the four nouns and derives them).
data[].repobodystringsource
data[].scopebodystringScope is provenance, not storage: "public" for a row from the published corpus, "org" for one only this caller can see.
data[].starsbodyintegerStars is GitHub's stargazer count for the source repository, read at the last sync and never accumulated here.
data[].templatebodystringlineage, if forked from one
data[].titlebodystringTitle is what to SHOW. A site's human name wins where it has one; a repo row falls back to the repository name, so on a repo this usually just repeats Name.
data[].updatedbodystringUpdated is when the thing last MOVED, as RFC 3339 in UTC: a repository's last push, or a site's last deploy.
data[].upstreambodystringUpstream/License credit the third-party work an entry was published from: the difference between "this org built it" and "somebody else built it and we are…
data[].urlbodystringlive, if it is deployed
facetsbodyobjectFacets counts the whole matching set along every browse axis, so a rail a client renders is a rail that has results behind it.
facets.*bodyobject
facets.*.*bodyinteger
totalbodyintegerTotal is how many entries matched BEFORE paging — what a pager sizes itself on.

Failure carries the platform error shape — see Errors.

Examples

hanzo catalog get

Catalog API · All Hanzo APIs · Interactive reference

How is this guide?

On this page