Coveo

Coveo Documentation Audit

The reference content is deep and broadly accurate, but the agent-facing layer is where it breaks: the advertised .md exports either 404 or silently corrupt the endpoints they're supposed to make machine-readable, and the docs' own front door has a missing step.

1. The .md agent export strips endpoint placeholders to empty strings (critical)

Location: https://docs.coveo.com/en/mcc80216.md (Organization endpoints)

Problem: The .md export — the format the docs explicitly advertise to AI agents — drops the org-ID (and region) placeholder tokens instead of preserving them, producing structurally broken endpoint strings. The export renders the generic platform endpoint as platform-.cloud.coveo.com (region segment missing), the search endpoints as .org.coveo.com/rest/search and .orghipaa.coveo.com/rest/search (leading org-ID segment missing), and the user-actions path as /rest/organizations//machinelearning/user/actions — note the doubled slash where the org ID should sit. These artifacts are quoted verbatim from the scraped .md body. The doubled slash and the empty leading subdomain are self-evidently missing path/host segments, not valid endpoints. The org-ID stripping is attested across four-plus endpoint strings; the region stripping is attested by the single platform-.cloud.coveo.com artifact.

Consequence: AI coding agents are the stated audience for the .md export, and they cannot use judgment to infer a stripped token. An agent ingesting this page will construct endpoints with no org ID (https://.org.coveo.com/rest/search) and produce code that fails at runtime with DNS or auth errors that trace back to a value the docs never showed. The machine-readable copy is strictly worse than the human-rendered one.

The fix: Fix the HTML→Markdown conversion to preserve placeholder tokens (<ORG_ID>, and the region segment in platform-<REGION>.cloud.coveo.com) as literal text, and verify code fences survive the conversion. Add a pipeline test that diffs placeholder/segment counts between the rendered HTML and the .md output for every exported page.

2. The advertised .md affordance 404s on the API-reference pages agents need most (critical)

Location: https://docs.coveo.com/en/13/api-reference/search-api

Problem: The Search API page is a JS-rendered Redocly SPA — a raw (non-JS) fetch returns only the AI-agent banner, no endpoint content. That banner promises: "A markdown version of this page is also available by appending .md to this page URL." But https://docs.coveo.com/en/13/api-reference/search-api.md returns HTTP 404, and the slug form https://docs.coveo.com/en/13.md also returns 404. Scoping caveat: the endpoint content itself is present and fully reachable in a normal JS browser (the rendered Redocly content was captured); the dead end is specific to non-JS / agent clients that follow the banner's own advertised .md affordance.

Consequence: An agent (or any non-JS HTTP client) following the page's own advertised affordance gets nothing: the HTML is a JS shell, and the promised .md fallback 404s. For the audience the banner explicitly addresses, there is no plain-text path to the Search API reference — the single most important reference page for anyone integrating Coveo. The affordance is broken precisely where it's most needed.

The fix: Generate .md exports for the Redocly/API-reference routes too, or — if those pages can't be exported — remove the "append .md" promise from the banner on pages where it doesn't resolve, so agents don't chase a dead URL. Server-render or provide a static fallback for the API reference so non-JS clients receive endpoint content.

3. The docs homepage's "Implement Coveo" sequence is missing Step 4 entirely (significant)

Location: https://docs.coveo.com/ (landing page, "Implement Coveo" section)

Problem: The onboarding sequence runs "Step 1: Index content," "Step 2: Build a search UI," "Step 3: Tune relevance," then an unlabeled item ("Monitor your solution with Coveo Analytics and keep track of your data"), then jumps to "Step 5: Leverage AI and ML." There is no "Step 4:" label, and the Step 4 heading text is missing — the Analytics item that should occupy that slot has no step number or title.

Consequence: The first thing a new developer reads on the documentation front door is a numbered implementation path with a hole in it. A reader who sees Step 3 → (blank) → Step 5 reasonably assumes a step is missing or that content failed to load, and can't tell whether monitoring is part of the official sequence. It undermines confidence at the exact moment first impressions form.

The fix: Label the Analytics item as "Step 4: Monitor your solution with Coveo Analytics" with proper heading text, and add a render/regression check that the step labels on the landing page are contiguous (1…N).

4. The REST APIs overview hub has empty link columns and no inline endpoint detail (significant)

Location: https://docs.coveo.com/en/143/ (Coveo REST APIs overview)

Problem: In the hub's table, every "Reference documentation" cell renders empty, and the Guide column is empty across rows except for the Activity row, which shows "N/A." The six rows actually present are Activity, Authorization Server, Push, Search, Usage Analytics Read, and Usage Analytics Write. The page references a Swagger UI (with region links platform-ca | platform-eu | platform-au) but gives no inline base URL or endpoint detail — it defers entirely to "See Organization endpoints," the page whose .md export is corrupted (finding #1).

Consequence: The page meant to be the entry point for discovering Coveo's REST APIs surfaces no usable links from its own table: the "Reference documentation" column is blank for every API, so a link-extracting tool or screen reader gets a table of API names with no destinations. The Activity row additionally advertises no guide ("N/A"). An agent parsing this hub cannot resolve any reference link from it.

The fix: Give every reference/guide cell descriptive link text ("Activity API reference," "Push API guide"), fill or remove the "N/A" guide cell, and surface the Swagger base URLs / organization-endpoint patterns inline on the hub instead of only linking out to a page whose machine-readable copy is broken.

5. The hub's own case-sensitivity guidance cites a Commerce API that isn't in the API table (significant)

Location: https://docs.coveo.com/en/143/ (Coveo REST APIs overview)

Problem: The case-sensitivity guidance on this page reads: "if the unique product identifier, such as ec_product_id, is passed to the Commerce API in lowercase, then it should also be passed to the Usage Analytics Write API in lowercase." But the "Coveo REST APIs" table on the same page lists only six APIs — Activity, Authorization Server, Push, Search, Usage Analytics Read, Usage Analytics Write — with no Commerce API row at all.

Consequence: A developer building a commerce integration reads on-page guidance that assumes a Commerce API, then finds no Commerce API entry, reference link, or guide anywhere in the overview table that is supposed to enumerate Coveo's REST surface. They can't tell whether "Commerce API" is a real distinct API, an alias for one of the listed APIs, or documented elsewhere. The hub contradicts its own prose.

The fix: Add a Commerce API row (with reference and guide links) to the overview table, or — if ec_product_id is actually handled by an already-listed API — correct the case-sensitivity example to name that API instead of an "API" the hub never lists.

6. Tense error inside the endpoint-deprecation notice (minor)

Location: https://docs.coveo.com/en/mcc80216.md (Organization endpoints, "Important" banner)

Problem: The deprecation notice reads: "On June 3, 2025, Coveo deprecated older endpoints and make other endpoint-related changes." "make" should be "made."

Consequence: Low functional impact, but it sits in the one banner warning developers that their existing integrations may have broken — the place where a reader is most likely to be parsing carefully. A visible slip in a breaking-change notice reads as carelessness exactly where trust matters.

The fix: Change "make" to "made," and proofread the deprecation banner since it's both high-traffic and high-stakes.

What they do well

• The reference scope is broad — the REST APIs overview enumerates the major API surface (Search, Push, Authorization Server, Usage Analytics Read/Write, Activity) with clear per-API usage descriptions, even if the Commerce API referenced in its own guidance is missing from the table (finding #5).
• Good cross-cutting guidance that prevents real bugs, e.g., the explicit note that all REST API string fields are case-sensitive and the same value must be passed with consistent case across APIs (ec_product_id).
• The platform is forward-thinking in trying to serve AI agents at all — an /llms.txt index, .md exports, and an explicit "AI agent context" banner show the right instinct, even where the execution currently breaks.

Top 3 recommendations

1. Fix the .md conversion pipeline so org-ID and region placeholder segments and code fences survive — the agent-facing export is currently the most broken copy of the most important page (endpoints).
2. Make the API reference reachable without JS: generate working .md for the Redocly pages or drop the "append .md" promise where it 404s, so the affordance the banner advertises actually resolves for the agents it targets.
3. Repair the navigation and consistency surfaces: restore Step 4 on the homepage onboarding sequence, give the REST APIs hub real reference/guide link text, and reconcile the Commerce API reference so the hub stops contradicting its own guidance.