---
title: API and generation
description: api, snippets, mcp, skill and capabilityIdentity.
---

Five optional blocks configure OpenAPI-derived output. Only `api` and `snippets` affect
the rendered site — the other three configure generators you invoke explicitly.

## `api`

<ParamField name="api.specs" type="Record<string, path>" required>
  Named OpenAPI specs, by local file path. `api`'s only permitted key, and it must
  declare at least one entry.
</ParamField>

```json
{ "api": { "specs": { "ingestion": "openapi/ingestion.yaml" } } }
```

Spec names match `^[A-Za-z0-9_-]+$` and must be unique **case-insensitively**: each name
becomes an `openapi/<name><ext>` output path, and two names differing only in case would
collide unpredictably on macOS or Windows.

Reference a spec from `navigation` with an `{ "api": true, "spec": "ingestion" }` entry —
see [Navigation](/docs/authoring/navigation).

## `snippets`

<ParamField name="snippets.languages" type="string[]" default="all five">
  Which HTTP snippet languages render on generated API pages. Choose from `curl`,
  `fetch`, `python-requests`, `python-httpx`, `go-nethttp`.
</ParamField>

<ParamField name="snippets.default" type="string" default="curl">
  Which language starts selected. Must be a member of `languages` when both are set.
</ParamField>

Snippets are derived from the spec and injected into a **derived copy** — your spec file
on disk is never modified. Author-written `x-codeSamples` always win and are never
overwritten.

## `mcp`

Keyed by spec name. Every key must name a declared `api.specs` entry.

<ParamField name="mcp.<spec>.output" type="path" required>
  Where the generated MCP server source tree is written, inside your repository.
</ParamField>

<ParamField name="mcp.<spec>.name" type="string">
  Package name for the generated server. Must satisfy npm's package-name grammar —
  lowercase, optionally scoped.
</ParamField>

<ParamField name="mcp.<spec>.version" type="string">
  A valid SemVer 2.0.0 version, e.g. `"1.4.0"`.
</ParamField>

<ParamField name="mcp.<spec>.baseUrl" type="string">
  Absolute URL with a scheme, e.g. `"https://api.example.com"`.
</ParamField>

## `skill`

Keyed by spec name, same rule.

<ParamField name="skill.<spec>.output" type="path" required>
  Where the generated Skill pack is written.
</ParamField>

<ParamField name="skill.<spec>.name" type="string">
  Pack name, 1–64 characters, matching `^[a-z0-9]+(-[a-z0-9]+)*$` — the Agent Skills
  format's own constraint.
</ParamField>

<ParamField name="skill.<spec>.concepts" type="string[]">
  Page references bundled verbatim into the pack. Duplicates within the array are a
  schema error; whether each reference resolves to real content is checked later, against
  your actual content directory.
</ParamField>

## `capabilityIdentity`

Keyed by spec name.

<ParamField name="capabilityIdentity.<spec>.methodOverrides" type="Record<string, string>">
  Renames derived capability methods.
</ParamField>

## These never change the site

`mcp`, `skill` and `capabilityIdentity` are generation-only. They affect what
`reed mcp generate` and `reed skill generate` write, and nothing about the rendered
documentation. A project can configure them and never notice a visual difference.