// Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs
| name | update-api-docs |
| description | Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs |
This skill guides you through updating the API reference documentation from the production OpenAPI specification.
The API documentation is generated from an OpenAPI spec using docusaurus-plugin-openapi-docs. The workflow involves:
openapi.json from production| Purpose | Path |
|---|---|
| OpenAPI spec (source) | docs/docs/reference/openapi.json |
| Generated API docs | docs/docs/reference/api/*.api.mdx |
| Generated sidebar | docs/docs/reference/api/sidebar.ts |
| Docusaurus config | docs/docusaurus.config.ts |
The wrapper script at docs/scripts/update-api-docs.sh downloads the OpenAPI
spec, replaces the local file, and regenerates the docs in one step.
cd docs
# Default — fetch from production (live cloud API)
pnpm update-api-docs
# Explicit live cloud API
pnpm update-api-docs:live
# From a locally running API (http://localhost/api/openapi.json)
pnpm update-api-docs:local
# From an explicit local file
pnpm update-api-docs:file /path/to/openapi.json
The script writes the spec to docs/docs/reference/openapi.json and then
runs npm run clean-api-docs -- agenta followed by
npm run gen-api-docs -- agenta. The agenta argument refers to the OpenAPI
config ID defined in docusaurus.config.ts.
If this is a fresh clone or dependencies haven't been installed:
cd docs
npm install
This generates:
.api.mdx files for each endpoint.tag.mdx files for API categoriessidebar.ts for navigationOptionally, start the dev server to preview:
cd docs
npm run start
Then visit http://localhost:5000/docs/reference/api to verify the API docs render correctly.
When committing these changes:
First commit - API docs update:
docs(api): update OpenAPI spec from production
Include all changed files:
docs/docs/reference/openapi.jsondocs/docs/reference/api/*.api.mdxdocs/docs/reference/api/*.tag.mdxdocs/docs/reference/api/sidebar.tsThe clean and generate commands require the config ID. Use:
npm run clean-api-docs -- agenta
npm run gen-api-docs -- agenta
Run npm install in the docs/ directory first.
This is a known warning and can be safely ignored. It will be addressed in a future Docusaurus v4 migration.
The OpenAPI plugin is configured in docs/docusaurus.config.ts:
[
"docusaurus-plugin-openapi-docs",
{
id: "openapi",
docsPluginId: "classic",
config: {
agenta: {
specPath: "docs/reference/openapi.json",
outputDir: "docs/reference/api",
downloadUrl: "https://raw.githubusercontent.com/Agenta-AI/agenta/refs/heads/main/docs/docs/reference/openapi.json",
sidebarOptions: {
groupPathsBy: "tag",
categoryLinkSource: "tag",
},
},
},
},
],
Audit and update the supported LLM model list in assets.py against litellm's registry (models.litellm.ai). Use when adding new models, pruning outdated ones, or verifying the list is correct.
Sync the findings record against local review artifacts and optionally a GitHub PR. Accept optional `path` and GitHub PR `url`; when `url` is provided, sync against both remote PR state and local state, otherwise default to local-only sync. Default to `path=infer`. Confirm effective variables before starting.
Resolve findings by implementing the chosen fix path in code, tests, or docs. Accept optional `path` and a `priority` selector; by default resolve only the next highest remaining priority bucket, in order `P0`, `P1`, `P2`, `P3`. Also accept explicit levels or `all`. Default to `path=infer`. Confirm effective variables before starting.
Perform a fresh-context scan of code and docs that turns verification observations and missing-test gaps into findings. Accept optional `path` and `depth` parameters and default to `path=infer`, `depth=deep`. Confirm effective variables before starting.
Run or inspect the relevant validation paths and turn failures, regressions, or missing coverage into findings. Accept optional `path` and `depth` parameters and default to `path=infer`, `depth=deep`. Confirm effective variables before starting.
Coordinate findings work with the user, decide whether scan, test, or sync should run, and turn the current findings set into a ready plan. Accept optional `path` and GitHub PR `url`; default to `path=infer`. Confirm effective variables before starting.