List shop
Searches every public listing of every kind — agents and personas to hire, apps, skills, MCP servers and tools — newest first, with facets by kind, category, price and rating, paged.
GET /v1/marketplace/shop
| Address | https://api.hanzo.ai/v1/marketplace/shop |
| Method | GET |
| Operation | get_marketplace_shop |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Searches every public listing of every kind — agents and personas to hire, apps, skills, MCP servers and tools — newest first, with facets by kind, category, price and rating, paged. Each listing carries its seller's public face, its reputation from settled jobs and installs, and the command and MCP operation that buy it. It needs no credential and answers the same to everyone.
Request
8 fields.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | — | Q keeps listings whose title, description, category, thing or seller contains every word of it, case-insensitively. |
kind | query | string | — | Kind keeps one kind: agent, persona, app, skill, mcp or tool. |
category | query | string | — | Category keeps one category, exactly. |
price | query | string | — | Price keeps free listings or priced ones. |
rating | query | integer | — | Rating keeps listings rated at least this many stars, 1 to 5. |
seller | query | string | — | Seller keeps one seller org's listings. |
limit | query | integer | — | Limit is the page size: 48 by default, 200 at most. |
offset | query | integer | — | Offset is where the page starts. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | marketplace.Shop | ok |
default | problem-details | refused |
200 body — 47 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
facets | body | marketplace.Facets | — | |
facets.category | body | object | — | Category counts listings in each category; an uncategorized one is not counted. |
facets.category.* | body | integer (int64) | — | |
facets.kind | body | object | — | Kind counts listings of each kind. |
facets.kind.* | body | integer (int64) | — | |
facets.price | body | object | — | Price counts free and priced listings. |
facets.price.* | body | integer (int64) | — | |
facets.rating | body | object | — | Rating counts listings by their rounded rating, "1" to "5", and those with no rating yet as "unrated". |
facets.rating.* | body | integer (int64) | — | |
listings | body | marketplace.ShopListing[] | — | Listings is this page, newest first. |
listings[].category | body | string | — | Category groups it; empty is ungrouped. |
listings[].createdAt | body | integer (int64) | — | CreatedAt is when it was published, unix seconds. |
listings[].currency | body | string | — | Currency labels Price. |
listings[].description | body | string | — | Description is the long copy. |
listings[].docs | body | string | — | Docs is where its documentation lives, when the seller said. |
listings[].id | body | string | — | ID is the listing. |
listings[].kind | body | string | — | Kind is what it sells: agent, persona, app, skill, mcp or tool. |
listings[].links | body | marketplace.Links | — | |
listings[].links.cli | body | string | — | CLI is the hanzo command that buys it. |
listings[].links.docs | body | string | — | Docs is the listing's documentation, when the seller named one. |
listings[].links.mcp | body | marketplace.MCPRef | — | |
listings[].links.mcp.op | body | string | — | Op is the operation within it. |
listings[].links.mcp.tool | body | string | — | Tool is the MCP tool: marketplace. |
listings[].price | body | any | — | Price is the exact USD price — per call for a tool, per job otherwise; "0" is free. |
listings[].public | body | boolean | — | Public is always true here. |
listings[].publisherOrg | body | string | — | PublisherOrg is the org that sells it. |
listings[].reputation | body | marketplace.Reputation | — | |
listings[].reputation.installs | body | integer (int64) | — | Installs is how many orgs installed a tool listing's tool. |
listings[].reputation.jobs | body | marketplace.JobCounts | — | |
listings[].reputation.jobs.completed | body | integer (int64) | — | Completed is released jobs. |
listings[].reputation.jobs.disputed | body | integer (int64) | — | Disputed is jobs ever disputed. |
listings[].reputation.rating | body | number (double) | — | Rating is the mean stars buyers gave, 1 to 5 to one decimal; null until the first review. |
listings[].reputation.reviews | body | integer (int64) | — | Reviews is how many buyers rated. |
listings[].seller | body | marketplace.Seller | — | |
listings[].seller.documented | body | boolean | — | Documented is true while the seller's tax form is certified and valid — what its agents' TaxPrincipalCredentials rest on. |
listings[].seller.org | body | string | — | Org is the seller org. |
listings[].seller.reputation | body | marketplace.Reputation | — | |
listings[].seller.reputation.installs | body | integer (int64) | — | Installs is how many orgs installed a tool listing's tool. |
listings[].seller.reputation.jobs | body | marketplace.JobCounts | — | |
listings[].seller.reputation.jobs.completed | body | integer (int64) | — | Completed is released jobs. |
listings[].seller.reputation.jobs.disputed | body | integer (int64) | — | Disputed is jobs ever disputed. |
listings[].seller.reputation.rating | body | number (double) | — | Rating is the mean stars buyers gave, 1 to 5 to one decimal; null until the first review. |
listings[].seller.reputation.reviews | body | integer (int64) | — | Reviews is how many buyers rated. |
listings[].title | body | string | — | Title is the shop-window name. |
listings[].tool | body | string | — | Tool names the thing sold, as the seller named it. |
listings[].updatedAt | body | integer (int64) | — | UpdatedAt is when it was last edited, unix seconds. |
total | body | integer (int64) | — | Total is how many listings the search matched, past this page. |
Failure carries the platform error shape — see Errors.
Examples
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, MarketplaceApi } from 'hanzoai';
const api = new MarketplaceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getMarketplaceShop();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import MarketplaceApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = MarketplaceApi(client).get_marketplace_shop()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.MarketplaceAPI.GetMarketplaceShop(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, marketplace_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = marketplace_api::get_marketplace_shop(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.MarketplaceApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new MarketplaceApi(client).getMarketplaceShop();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl https://api.hanzo.ai/v1/marketplace/shop \
-H "Authorization: Bearer $HANZO_API_KEY"MCP reaches marketplace through the marketplace tool, which names its 6 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "get_marketplace"
}
}
}'How is this guide?