---
title: "content.handler()"
description: "Handle a web-standard Request and dispatch it by path to the Content instance data surface."
canonical_url: "https://content.comark.dev/reference/content/handler"
---
# content.handler()

> Handle a web-standard Request and dispatch it by path to the Content instance data surface.

## `content.handler(request)`

Handles a single web-standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), dispatching by request path. It powers the Vite middleware and is the endpoint that [`createContentClient`](https://content.comark.dev/reference/client/create-content-client) targets.

**Parameters:**

- `request`: a `Request`. The handler strips [`basePath`](https://content.comark.dev/reference/content/comark-content#options-basepath) (default `/api/content`) from the pathname, then dispatches the remaining path.

**Returns:** `Promise<Response>`, a JSON response for matched sections or a structured JSON error (see [Errors](#errors)) for unknown paths and failures.

The first path segment after `basePath` selects the section:

| Path                                                   | Dispatches to                                                                                                      | Response body                                                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `manifest` / `manifest.json`                           | [`manifest()`](https://content.comark.dev/reference/content/manifest)                                              | [`CacheArtifact`](https://content.comark.dev/reference/types/content#cacheartifact)            |
| `navigation` / `navigation.json`                       | [`navigation()`](https://content.comark.dev/reference/content/navigation)                                          | [`NavigationItem[]`](https://content.comark.dev/reference/types/content#navigationitem)        |
| `snapshot` / `snapshot/<name>` (with optional `.json`) | [`snapshot()`](https://content.comark.dev/reference/content/snapshot)                                              | [`CacheArtifact`](https://content.comark.dev/reference/types/content#cacheartifact)            |
| `get/<path>`                                           | [`get('/<path>', opts)`](https://content.comark.dev/reference/content/get)                                         | `ContentFile \| null`                                                                          |
| `list` / `list/<json-names>`                           | [`list()`](https://content.comark.dev/reference/content/list)                                                      | [`ContentListFile[]`](https://content.comark.dev/reference/types/content#contentlistfiletdata) |
| *custom*                                               | a serve handler registered via [`addServeHandler`](https://content.comark.dev/reference/content/add-serve-handler) | handler-defined                                                                                |

A `.json` suffix on the section is accepted everywhere, so `/manifest` and `/manifest.json` are the same route. `snapshot/<name>` must name this instance; any other name is a 404.

### Artifact routes are cached

`manifest` and `snapshot` answer with a checksummed [`CacheArtifact`](https://content.comark.dev/reference/types/content#cacheartifact). Producing one means serializing, compressing, and digesting the corpus, so the result is persisted and reused until the content changes:

- The first request after a change builds and stores the artifact.
- Later requests serve it with a single cache read.
- Any mutation ([`update`](https://content.comark.dev/reference/content/update), [`remove`](https://content.comark.dev/reference/content/remove), [`refresh`](https://content.comark.dev/reference/content/refresh), a fresh [`get`](https://content.comark.dev/reference/content/get), or an index rebuild) drops it.
- A stored artifact is verified before use, and a corrupt one is dropped and rebuilt.

That matters most for `snapshot`, whose payload carries every body: without it, each request would read one cache entry per document and rebuild the whole artifact.

```ts [server/api/content/[...path\\].ts]
import { toWebRequest } from 'h3'
import { content } from '~~/server/utils/content'

export default eventHandler((event) => content.handler(toWebRequest(event)))
```

## Errors

Failures return a JSON body of the shape `{ error, message? }` with an appropriate status code, so clients can react without parsing free-form text:

| Status | `error`          | When                                                                                                                                                                             |
| ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `bad_request`    | The optional `list` names parameter isn't a JSON-encoded array.                                                                                                                  |
| `404`  | `not_found`      | Unknown section, or an instance name that doesn't match this endpoint.                                                                                                           |
| `500`  | `internal_error` | An unexpected error while producing the response. The failure is also logged via [`content.logger`](https://content.comark.dev/reference/content/comark-content#options-logger). |

```json
{ "error": "bad_request", "message": "The list names parameter must be a JSON-encoded array." }
```

## Usage

```ts [server/api/content/[...path\\].ts]
export default eventHandler((event) => content.handler(toWebRequest(event)))
```


## Sitemap

See the full [sitemap](https://content.comark.dev/sitemap.md) for all pages.