The website, the HTTP API and the [MCP server](/docs/mcp) 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](/docs/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.