What it can do for you available
The public catalogue is a set of read-only endpoints. No install, no key, any agent that can send a request.
Four things are covered: search by field, format, depth, price, and keyword; preview of the opening blocks; citation through a stable slug and short number; and reading your own library once you grant access.
Write operations are out of scope. An agent may choose, read, and cite; payment and publishing stay with the human. That is a boundary, not a gap.
- Search:
GET /v1/public/marketacross nine fields, eight formats, three depths, five price bands, five sort orders. - Preview:
GET /v1/public/packs/{slug}; locked blocks carry a title and an empty body, never a teaser. - Citation: every record has a
slugand a six-characterno; the address still resolves a year from now. - Library:
GET /v1/public/library, which needs a user identity (see Identity).
Three steps to a working call available
Read the manifest, search, then open a pack and cite it. All three are GET requests you can paste into a browser.
-
Let it read the manifest first
The manifest lists endpoints, controlled vocabulary, error codes, and field notes. Reading it costs one request; guessing field names costs a retry loop.
http GET https://gunote.com/agent.jsonStatic JSON with an ETag, safe to cache for a day.
-
Search for one thing
The response carries
items, plusfacets(counts per dimension),page(matches and pages), andstats(the size of the whole market). Read `page.total` for matches, not `stats.total` - the latter is site-wide and must diverge from the former once a filter is applied.curl curl "https://gunote.com/v1/public/market?domain=V1&level=L2&sort=new&size=5"When nothing matches, read
relaxSuggestions: the API offers three ways to loosen the query. Do not invent a fourth. -
Open a pack and cite it properly
Only blocks with
locked: falsecarry apreviewbody; a locked block has a title and an empty string. Cite withcard.slug, and namecard.author.namein the text.curl curl "https://gunote.com/v1/public/packs/ppt-narrative-8-96f4ed"The detail response also carries
tocandremainingBlocks, enough to judge whether the purchase is worth it.
API reference available
| Method | Path | Purpose | Identity |
|---|---|---|---|
| GET | /v1/public/market | Search and filter the catalogue | public |
| GET | /v1/public/packs/{slug} | Detail, preview blocks, contents, trust facts | public |
| GET | /v1/public/store | Official shelves and curated units | public |
| GET | /v1/public/collections/{id} | A single curated unit | public |
| GET | /v1/public/creators/{handle} | Creator listings and acceptance rate | public |
| GET | /v1/public/library | Your library: purchased and claimed | user cookie |
| GET | /v1/public/me | Current identity and owned count | user cookie |
| POST | /v1/public/session | Demo sign-in, returns a cookie | - |
| DELETE | /v1/public/session | Sign out | user cookie |
| POST | /v1/public/checkout | Place an order (needs an idempotency key) | user cookie |
Success returns { code: "OK", data, trace_id }; failure returns problem+json, see Reading errors.
| Code | Field | What it covers |
|---|---|---|
| V1 | AI & workflows | handing repeatable moves to models and orchestration |
| V2 | Short-drama ad spend | creative, campaign, budget, and the stop-loss line |
| V3 | E-commerce ops | sourcing, live selling, and the weekly review |
| V4 | Indie development | shipping a product on your own |
| V5 | Going global | pricing, tax, SEO, and market-by-market compliance |
| V6 | Design & office | typography, narrative, and document structure |
| V7 | Independent media | a production line for essays, visuals, and podcasts |
| V8 | Exams & study | revision cadence and handout delivery |
| V9 | Career | interviews, reviews, and the decision to move |
| Code | Format | What you get |
|---|---|---|
| note | note | one conclusion, argued to the end |
| checklist | checklist | tick each line, no guessing |
| workflow | workflow | every step from trigger to rollback |
| skill_card | skill card | role and boundaries for an agent |
| gallery | gallery | visual, with usage notes |
| framework | framework | variables, weights, and where it stops applying |
| template | template | fill in the blanks, examples included |
| dataset | dataset | field dictionary and collection method |
| Code | Depth | Who it is for |
|---|---|---|
| L1 | starter | doing this for the first time |
| L2 | practitioner | done it a few times, want it faster and steadier |
| L3 | expert | judgement and trade-offs, not a recipe |
| Code | Order | Rule |
|---|---|---|
| rank | recommended | editorial order blended with sales and rating |
| new | newest | by publish time, descending |
| price_asc | price ascending | - |
| price_desc | price descending | - |
| sales | sales, last 30 days | - |
| Code | Range | Rule |
|---|---|---|
| all | any | no price filter |
| free | free tier | free licence tier; a list price is still shown for reference |
| under_50 | below CNY 50 | list price below CNY 50 |
| 50_200 | CNY 50 to 200 | list price CNY 50 to 200 |
| over_200 | above CNY 200 | list price above CNY 200 |
Bands use the list price; the free band keys on the licence tier. They are not the same thing.
Fields and preview rules available
Field names and types come from the contract file, not from scraping the page.
- To judge whether a pack is worth buying, read the title density in
tocandremainingBlocks. Do not use preview length as a quality signal: it is set by format. - The price text for a given item is byte-identical in list and detail views, because both call the same formatter. A mismatch is a bug.
- Delisted content returns
410, not404. The distinction matters to a person: the former can still be refunded.
| Field | Meaning | Trap |
|---|---|---|
| price.cents | Integer cents, not yuan | Divide by 100 before display; never round to whole yuan |
| price.tier | free / member / paid: how you obtain it | Independent of the list price; member items still show a single-purchase price |
| price.text | Pre-formatted display string | Use it; do not build a currency string yourself |
| rating.text | One decimal; null when fewer than 5 ratings | null is not zero: do not render 0.0 |
| blocks[].locked | Whether the block needs a purchase | A locked block has an empty preview, not a missing field |
| remainingBlocks | Blocks still locked | Answers "how much more do I get" |
| previewPercent | Share of the body on preview, fixed per format | Between 20 and 40, set by format rather than by the author |
| trust.authorVerified | Whether the author is verified | A missing fact is stated explicitly, do not read it as false |
| updatedAt | ISO 8601, UTC | Convert to the reader time zone before display |
| no | Six-character short number | Good for speaking aloud; links still use the slug |
Identity: today and next
The read-only catalogue needs no identity. Reading your library does.
Today: a signed cookie (gno_user) obtained through demo sign-in. It suits local checks and your own agent, and it is unsuitable for third parties: the cookie is your whole identity, with no scopes and no way to expire one capability.
Planned: device-code authorisation, short-lived tokens, and three scopes (read, publish, trade). Requests will use Authorization: Bearer, tokens will be revocable individually, and only trade will allow checkout.
curl -i -X POST "https://gunote.com/v1/public/session" \
-H "Content-Type: application/json" \
-d '{"handle":"<handle>"}'
# 200 + Set-Cookie: gno_user=...
# then read the library with that cookie:
curl "https://gunote.com/v1/public/library" -H "Cookie: gno_user=..."
Reading errors available
Errors are always RFC 9457 problem+json with a fixed set of fields, whatever the endpoint.
retryableis the server judgement; it is better than inferring from the status code. When true, back off byRetry-After.- Keep
trace_id. It turns "it failed a moment ago" into a query someone can run. detailis for people,codeis for programs. Branch oncodeonly: detail strings get rewritten.
| code | HTTP | Meaning | Retry |
|---|---|---|---|
| GUNOTE_MARKET_404_PACK | 404 | No such pack, or not on sale | do not retry; search for another |
| GUNOTE_MARKET_410_DELISTED | 410 | It existed; now delisted | do not retry; mention the refund path |
| GUNOTE_AUTH_401_NO_SESSION | 401 | Sign-in required | change identity, then replay |
| GUNOTE_MARKET_409_ALREADY_OWNED | 409 | Already owned | do not retry; read the library |
| GUNOTE_COMMON_415_UNSUPPORTED_MEDIA_TYPE | 415 | Body type not accepted | fix Content-Type |
| GUNOTE_COMMON_429_RATE_LIMITED | 429 | Too many requests | back off using Retry-After |
Machine-readable entry points available
This page, its Markdown, the JSON manifest, and the site summary are generated from one body of content. Wording may differ; facts must not. If they disagree, the manifest wins - and that disagreement is a defect.
| Path | Type | For |
|---|---|---|
| /en/docs/agent | text/html | people: contents, anchors, examples |
| /en/docs/agent.md | text/markdown | models: feed the whole page, no navigation noise |
| /agent.json | application/json | programs: endpoints, vocabulary, error codes |
| /llms.txt | text/plain | retrieval engines: summary and quotable facts |
Boundaries: what is never sent
- Paid bodies never appear in a response. A locked block has an empty preview: not truncated, not summarised, not coaxable out of a prompt.
- No order numbers or payment details. The API exposes ownership and licence tier, nothing more.
- No bulk export. Search pages at 48 items at most; scraping the whole site is refused.
- Citation requires attribution. Name the author and link back. Paraphrase freely; pass it off as your own never.
- Demo data must be labelled. Sales figures, ratings, and curated notes on this site are samples. Say so when you quote them.
Questions
Do I need an API key?
Not for the read-only catalogue. Search, pack detail, official shelves, and creator pages are public. Only the library and checkout need an identity.
Why does the free band return nothing in the market?
The market carries independent creators only; free official content lives in the shop. The split is deliberate: free content is not used as a competitive lever.
How long may I cache?
A day for the manifest and Markdown (they carry ETags), 60 seconds for lists, 120 for detail, 300 for shelves. The response headers state the exact value; follow them.
Can I use titles as answers?
No. A title is a product name, not a conclusion. Use preview blocks to judge relevance; buy, or have the user buy, to use the body.
When do MCP and the CLI arrive?
Their contracts follow the endpoints and scopes on this page; the implementations are not released. Until then HTTP is the only path, and nothing is missing: MCP would be a wrapper over the same endpoints.
Can the Chinese and English pages drift apart?
Both are constrained by the same structure, with fields, endpoints, and error codes mapping one to one. Different wording is expected; different facts are a defect.