Cite API pages

A coordinate names an API item independently of its URL, such as an operation’s operationId. Routes and coordinates lists the coordinate of every OpenAPI item.

Link from prose by coordinate

Use an api.ref: destination in Markdown or MDX under src/content:

See how to [retrieve an event](api.ref:api:retrieveEvent).

Nimbus resolves the citation during the build:

• api identifies the API collection.
• retrieveEvent identifies the operation independently of its route.
• A citation without a version targets the API family’s default version.
• An unknown coordinate in a known collection fails the authored-content build and may suggest a close match.
• An unknown collection is warned and rewritten to #; verify collection names against /nimbus-api/coordinates.json so dead citations do not ship.

Pin a historical version only when the prose specifically discusses it:

Review the [v1 operation](api.ref:api@v1:retrieveEvent).

Use /nimbus-api/coordinates.json to inspect the exact coordinates and resolved URLs published by a built site.

Cite an API hosted elsewhere

A documentation site can cite a reference published by another Nimbus site without mounting or republishing it:

apiReferences: [
  {
    collection: "api",
    manifest: "https://api.example.com/nimbus-api/coordinates.json",
    origin: "https://api.example.com",
  },
],

collection must match the collection key published by the remote manifest. origin is the absolute prefix prepended to site-relative manifest paths. Include the deployment base when the remote reference is hosted below one, for example https://api.example.com/docs.

The remote collection then uses the same prose syntax: api.ref:api:retrieveEvent. Remote references provide citation targets only; they do not add the remote pages to local search or agent outputs.

The manifest lists paths without a trailing slash. With origin, citations use them as listed, so a remote site that serves /api/retrieve-event/ may redirect or 404 the link. Without origin, paths take this site’s trailing-slash shape, which is right only when both sites match.

Check a citation against the remote site before relying on it.

Nimbus fetches HTTPS manifests during the build. If one is unavailable or malformed, the build warns and its citations link to #. For offline builds, commit the manifest and use a project path.

A local manifest that can’t be read or parsed fails the build. Malformed entries in a valid manifest are skipped with a warning.