GuNote Docs

Dossier 01 / Agent integration

Agent integration

Wire the GuNote catalogue into your agent. It can search, preview, and cite, and it can read your own library once you grant access. This page keeps "works today" and "on the way" apart, so nothing planned is described as shipped.

Versions an agent can read directly

One body of content, four ways to read it: people get HTML, models get Markdown and JSON, retrieval engines get plain text.

Four carriers, one capability

The same catalogue, four ways in. Take the one that works now instead of waiting for the last one.

  1. available

    Public HTTP API

    Any agent that can send a GET request, nothing to install

    Read-only, no key, cacheable. The rest of this page describes this path.

  2. planned

    MCP server

    One endpoint in your host configuration

    Tool names and parameters follow the API on this page; the server is not released yet.

  3. planned

    Command line

    npx gunote handles auth and search

    Device-code auth and token scopes are described under Identity.

  4. planned

    Skill text (SKILL.md)

    Feed the agent a role and boundary brief

    It will cite the API and citation rules here rather than improvising.

Status reflects the code, not intent: available means callable today; planned means the contract is fixed and the implementation is not shipped.

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/market across 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 slug and a six-character no; 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.

  1. 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.json

    Static JSON with an ETag, safe to cache for a day.

  2. Search for one thing

    The response carries items, plus facets (counts per dimension), page (matches and pages), and stats (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.

  3. Open a pack and cite it properly

    Only blocks with locked: false carry a preview body; a locked block has a title and an empty string. Cite with card.slug, and name card.author.name in the text.

    curl
    curl "https://gunote.com/v1/public/packs/ppt-narrative-8-96f4ed"

    The detail response also carries toc and remainingBlocks, enough to judge whether the purchase is worth it.

API reference available

Endpoints
MethodPathPurposeIdentity
GET/v1/public/marketSearch and filter the cataloguepublic
GET/v1/public/packs/{slug}Detail, preview blocks, contents, trust factspublic
GET/v1/public/storeOfficial shelves and curated unitspublic
GET/v1/public/collections/{id}A single curated unitpublic
GET/v1/public/creators/{handle}Creator listings and acceptance ratepublic
GET/v1/public/libraryYour library: purchased and claimeduser cookie
GET/v1/public/meCurrent identity and owned countuser cookie
POST/v1/public/sessionDemo sign-in, returns a cookie-
DELETE/v1/public/sessionSign outuser cookie
POST/v1/public/checkoutPlace an order (needs an idempotency key)user cookie

Success returns { code: "OK", data, trace_id }; failure returns problem+json, see Reading errors.

Fields (domain)
CodeFieldWhat it covers
V1AI & workflowshanding repeatable moves to models and orchestration
V2Short-drama ad spendcreative, campaign, budget, and the stop-loss line
V3E-commerce opssourcing, live selling, and the weekly review
V4Indie developmentshipping a product on your own
V5Going globalpricing, tax, SEO, and market-by-market compliance
V6Design & officetypography, narrative, and document structure
V7Independent mediaa production line for essays, visuals, and podcasts
V8Exams & studyrevision cadence and handout delivery
V9Careerinterviews, reviews, and the decision to move
Formats (form)
CodeFormatWhat you get
notenoteone conclusion, argued to the end
checklistchecklisttick each line, no guessing
workflowworkflowevery step from trigger to rollback
skill_cardskill cardrole and boundaries for an agent
gallerygalleryvisual, with usage notes
frameworkframeworkvariables, weights, and where it stops applying
templatetemplatefill in the blanks, examples included
datasetdatasetfield dictionary and collection method
Depth (level)
CodeDepthWho it is for
L1starterdoing this for the first time
L2practitionerdone it a few times, want it faster and steadier
L3expertjudgement and trade-offs, not a recipe
Sort order (sort)
CodeOrderRule
rankrecommendededitorial order blended with sales and rating
newnewestby publish time, descending
price_ascprice ascending-
price_descprice descending-
salessales, last 30 days-
Price band (price)
CodeRangeRule
allanyno price filter
freefree tierfree licence tier; a list price is still shown for reference
under_50below CNY 50list price below CNY 50
50_200CNY 50 to 200list price CNY 50 to 200
over_200above CNY 200list 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 toc and remainingBlocks. 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, not 404. The distinction matters to a person: the former can still be refunded.
Fields that matter
FieldMeaningTrap
price.centsInteger cents, not yuanDivide by 100 before display; never round to whole yuan
price.tierfree / member / paid: how you obtain itIndependent of the list price; member items still show a single-purchase price
price.textPre-formatted display stringUse it; do not build a currency string yourself
rating.textOne decimal; null when fewer than 5 ratingsnull is not zero: do not render 0.0
blocks[].lockedWhether the block needs a purchaseA locked block has an empty preview, not a missing field
remainingBlocksBlocks still lockedAnswers "how much more do I get"
previewPercentShare of the body on preview, fixed per formatBetween 20 and 40, set by format rather than by the author
trust.authorVerifiedWhether the author is verifiedA missing fact is stated explicitly, do not read it as false
updatedAtISO 8601, UTCConvert to the reader time zone before display
noSix-character short numberGood 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
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.

  • retryable is the server judgement; it is better than inferring from the status code. When true, back off by Retry-After.
  • Keep trace_id. It turns "it failed a moment ago" into a query someone can run.
  • detail is for people, code is for programs. Branch on code only: detail strings get rewritten.
Common codes
codeHTTPMeaningRetry
GUNOTE_MARKET_404_PACK404No such pack, or not on saledo not retry; search for another
GUNOTE_MARKET_410_DELISTED410It existed; now delisteddo not retry; mention the refund path
GUNOTE_AUTH_401_NO_SESSION401Sign-in requiredchange identity, then replay
GUNOTE_MARKET_409_ALREADY_OWNED409Already owneddo not retry; read the library
GUNOTE_COMMON_415_UNSUPPORTED_MEDIA_TYPE415Body type not acceptedfix Content-Type
GUNOTE_COMMON_429_RATE_LIMITED429Too many requestsback 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.

Four entry points
PathTypeFor
/en/docs/agenttext/htmlpeople: contents, anchors, examples
/en/docs/agent.mdtext/markdownmodels: feed the whole page, no navigation noise
/agent.jsonapplication/jsonprograms: endpoints, vocabulary, error codes
/llms.txttext/plainretrieval 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.

Version and provenance

Contract
agent-manifest v1 (2026-11-22)
Scope
ten /v1/public/* endpoints
Languages
Simplified Chinese (source), English
Generated
one content model, three outputs: HTML, Markdown, JSON

This page and /agent.json come from one source. If a field or error code disagrees with reality, trust the manifest and file a defect: drift is more dangerous than absence.