---
title: "Example API"
description: "A fictional API included to show what Duvlify renders from an OpenAPI document. It does not exist, and every page in this tab is an example."
canonical: "https://duvlify.dev/example-api/introduction"
updated: "2026-08-11"
---

# Example API

> **Warning: This API is not real**
>
> Duvlify documents a framework, not a service, so it has no API of its own.
> These pages describe a fictional API on `api.example.com`. They exist to show
> what the API reference layout renders. Do not send requests to it.

Every page in this tab is generated from one file:
[`src/openapi.config.ts`](https://github.com/DuvInc/duvlify/blob/main/src/openapi.config.ts).
The pages carry only the method and path of one operation. The build reads
everything else from the spec: the parameters, the request body, the response
shapes, the response tabs, and the request samples on the right.

To document your own API, replace that file and rewrite these pages. See
[API reference pages](/guides/api-reference) for the procedure.

## What this example shows

[**Query parameters and pagination**](/example-api/list-widgets)

An enum, an integer with bounds and a default, and a cursor.

[**A request body**](/example-api/create-widget)

Required and optional fields, with lengths and defaults.

[**A path parameter**](/example-api/get-widget)

The simplest shape, plus a 404 response.

[**The published spec**](/openapi.json)

The same document, served whole for anything writing code.

## Authentication

The spec declares one security scheme, and the build shows it on every endpoint
page. This example uses a bearer token:

```bash
curl https://api.example.com/v1/widgets \
  -H "Authorization: Bearer sk_example_..."
```

## Errors

Every error in this example returns the same shape. The `code` is stable, so a
caller branches on it. The `message` is one sentence for a person, and its
wording can change.

```json
{
  "error": {
    "code": "widget_not_found",
    "message": "No widget with this id exists."
  }
}
```

| Status | Meaning                                            |
| ------ | -------------------------------------------------- |
| `401`  | The API key is missing, malformed or revoked.      |
| `404`  | No widget with this id exists.                     |
| `422`  | A field failed validation. `error.field` names it. |