Public API

The website, the HTTP API and the MCP server are separate interfaces over the same catalogue services. They share publication rules, variant defaults, dependency rules and error codes, so the same question gets the same answer from each of them.

All URLs below are relative to https://pagesugar.com.

Choose an endpoint #

Discover with categories, filtered component listings or search. Inspect a component by ID, then pin its version and palette. Retrieve its manifest, individual files or ZIP from the artifact URLs returned. Search results are bounded; use paginated listings to enumerate the catalogue.

Routes #

Method and route	Purpose
`GET /`	Product introduction and catalogue entry points.
`GET /components`	Browse or search published components.
`GET /categories`	Grouped and A to Z category discovery.
`GET /categories/[slug]`	Browse one category.
`GET /components/[slug]`	Component detail for the current or a requested version and variant.
`GET /components/[slug].md`	Agent-readable component information in Markdown.
`GET /preview/[slug]`	Standalone preview of the current release.
`GET /blog`, `GET /blog/[slug]`	Articles.
`GET /docs/[...slug]`	Documentation, including `/docs/mcp`.
`GET /docs/[...slug].md`	Documentation as Markdown.
`GET /api/v1/categories`	Public category summaries.
`GET /api/v1/components`	Deterministic filtered browsing. No natural-language query.
`GET /api/v1/search`	Bounded natural-language best matches.
`GET /api/v1/components/[id]`	Current component metadata and version listing.
`GET /api/v1/components/[id]/versions/[version]`	Pinned release metadata with variant and artifact references.
`GET /artifacts/[id]/[version]/[variant]/[digest]/manifest.json`	Content-addressed distribution receipt.
`GET /artifacts/[id]/[version]/[variant]/[digest]/source/[...path]`	One exported file from the release allowlist.
`GET /artifacts/[id]/[version]/[variant]/[digest]/bundle.zip`	Complete source bundle for the selection.
`GET /mcp`	The MCP page, for a request that asks for HTML.
`GET /mcp.md`	The MCP page as Markdown, with setup steps for each client.
`POST /mcp`	MCP protocol requests.
`GET /llms.txt`	Navigation guide for agents.
`GET /sitemap.xml`, `GET /robots.txt`, `GET /rss.xml`	Search engine and feed discovery.

Artifact URLs are content-addressed by the artifact digest. If the digest does not match the published artifact for that component, version and variant, the response is NOT_FOUND. The current build serves only each component's current release; older releases are not yet retained, so a URL for a superseded release stops resolving once a newer release is published. A receipt's publishedInRevision is currently the catalogue revision that produced the build, because release history is not yet retained. Receipt and bundle formats are described in distribution.

Identifiers #

Component ids look like cmp_pricing_grid_001: cmp_ followed by lowercase letters and digits in underscore-separated groups.
Slugs are lowercase letters and digits separated by single hyphens.
Versions are exact MAJOR.MINOR.PATCH numbers.

Filters #

Browsing, search and the MCP tools share one filter vocabulary. Values within one filter combine with OR; different filters combine with AND. Each filter accepts at most 20 values.

Filter (MCP field)	Query parameter	Values
`categoryIds`	`category`	Category ids.
`partIds`	`part`	Taxonomy part ids.
`kinds`	`kind`	`section`, `control`, `composition`, `integration-recipe`
`runtimes`	`runtime`	`svelte`, `sveltekit`
`integrationLevels`	`integration`	`presentational`, `local-interaction`, `service-required`, `kit-recipe`
`dependencyProfiles`	`dependency`	`none`, `third-party`, `external-service`
`capabilities`	`capability`	`dark-mode`
`tags`	`tag`	Tag slugs.

HTTP endpoints take the query parameter names; repeat a parameter or separate values with commas, for example ?category=pricing&dependency=none. MCP tools take the field names inside a filters object.

Unknown filter names are rejected rather than ignored.

Browse sorts are editorial, newest, updated and title.

Limits #

Operation	Default	Maximum
Browsing	24	50
`GET /api/v1/search`	12	24
`GET /components?q=` search page	24	24
Website search dialog	6	6
MCP `list_components`	20	50
MCP `search_components`	8	20

The search page shows up to 24 best matches, and the search dialog requests 6. Search queries are limited to 500 characters.

/api/v1/* endpoints reject unknown query parameters and repeated single-value parameters (such as q, limit, sort and cursor) with INVALID_ARGUMENT.

Search results #

Search returns best matches, not an exhaustive list. A search result says which engine answered (exact, upstash-search, lexical or lexical-fallback), whether it was degraded, and always reports isExhaustive: false with total: null. Use browsing when you need a complete, counted list.

Browsing results report an exact total for the catalogue revision and filters, and a nextCursor. A cursor is bound to its catalogue revision, filters and sort.

Errors #

REST endpoints (/api/v1/* and /artifacts/*) return errors as a JSON body of the form { "error": { "code", "message", "details" } }: a code, a human-readable message and, where useful, safe public details such as the valid variant ids or available versions. details is omitted when there is nothing to add. HTML pages show a readable error page with the same meaning instead, and Markdown routes return the code and message as plain text.

Code	HTTP status	Meaning
`INVALID_ARGUMENT`	400	An input is invalid.
`NOT_FOUND`	404	No public resource matches.
`VERSION_NOT_FOUND`	404	The requested release is unavailable. Latest is never substituted.
`UNKNOWN_VARIANT`	400	The variant does not exist for the release.
`WITHDRAWN`	410	The release was deliberately withdrawn.
`FILE_NOT_FOUND`	404	The path is not in the published file allowlist.
`RESPONSE_TOO_LARGE`	413	The response would exceed its budget.
`RATE_LIMITED`	429	Too many requests.
`SEARCH_UNAVAILABLE`	503	Search cannot answer and no fallback applies.
`REVISION_EXPIRED`	410	The pagination snapshot is no longer retained.
`ARTIFACT_UNAVAILABLE`	503	A known artifact cannot be delivered right now.

The HTTP statuses apply to REST responses only. The MCP server uses the same codes but maps them to MCP results separately; it does not use this status table.

Media types #

Markdown routes respond with text/markdown, JSON with application/json, feeds with application/rss+xml, and bundles with a ZIP archive media type. Source files are served with the media type recorded for them in the receipt, except that HTML- and XML-like types are served as text/plain so a source file can never render as a page. SVG files are served as image/svg+xml; every artifact response carries Content-Security-Policy: default-src 'none'; sandbox, so an SVG opened directly cannot run scripts or load resources.

CORS and caching #

API and artifact responses, including errors and 304 Not Modified, carry Access-Control-Allow-Origin: *. The data is public and read-only and no credentials are involved, so any origin may read it.

Source files under /artifacts/.../source/ are fully covered by the artifact digest and are cached as immutable for a year. The receipt (manifest.json) and the bundle (bundle.zip) also embed the build revision and a generated README, which the digest does not cover, so they are cached for 5 minutes and then revalidated with their ETag. API listings and metadata are cached briefly; errors are never cached.