Confluence search

Find the page that documents an endpoint with Confluence search. Apifolio indexes operation IDs, paths and summaries, and shows editors how much of the API search covers.

When you save the macro, Apifolio stores a short text digest of the API in it: the title, version, sections and endpoints. Confluence indexes it, so searching for createInvoice, /v1/orders or "refund a payment" finds the page that documents it. The Rovo agent's site-wide search uses the same index.

  • For most APIs, the digest has one line per endpoint: method, path, operation ID and summary.
  • For large APIs, the digest packs the words people search for into its 6,000 characters: the path words, the operation IDs and the summary words endpoints share.

The macro dialog shows how much of the API search can find, under the display filters. An endpoint counts as covered when its operation ID and the words of its path are all in the digest. For example, all 1,232 endpoints of GitHub's REST API are covered: "Confluence search covers 1,232 of 1,232 endpoints". Very large APIs with long operation IDs get less from one macro: Stripe's API, with 612 endpoints, gets 107 of 612. Split such an API over several macros (for example one per section): each macro indexes its own endpoints.

Keep the index up to date

The digest is built when the macro is saved. The documentation always shows the latest file, but the index doesn't change by itself when a new version of the spec is uploaded.

When the file changed after the macro was saved, editors see a note above the macro while editing the page: "The spec changed since this macro was saved (version 3 → 7)." Open the macro and click Save to update Confluence search and Rovo. Readers never see this note.

Apifolio doesn't refresh the index on its own because that would mean editing your pages, which needs a permission Apifolio does not ask for. See What Apifolio does not do, and why.

What the digest contains

The API title and version, the start of its summary or description (up to 300 characters), the section names and the endpoints' methods, paths, operation IDs and summaries: never examples or full descriptions. It is stored in the page like any other page content and follows the page's permissions.

View as Markdown