Respan Documentation Audit

Recently rebranded from Keywords AI (Feb 13, 2026 per the changelog), Respan's docs read like a platform mid-migration: confident reference material colliding with broken sidebar targets, dueling endpoint URLs, contradictory model counts, and an llms-full.txt that doesn't exist despite every page advertising it.

1. Marketed llms-full.txt returns 404 on both hosts (critical)

Location: Banner on every docs page; https://respan.ai/llms-full.txt and https://www.respan.ai/llms-full.txt

Problem: Every docs page renders the banner: "For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt." But fetching /llms-full.txt on either the apex or www host returns HTTP 404. Only /llms.txt (a brief marketing summary) exists.

Consequence: This is the file an AI coding agent is supposed to ingest to load the full corpus into context. Telling agents the file exists and 404'ing them is worse than not advertising it — Claude Code, Cursor, and Codex CLI integrations are all explicitly called out in the changelog, and the file they'd read is missing. Respan is itself a platform for AI agents; this is the equivalent of a CI provider's webhook URL going to a dead host.

The fix: Either generate /llms-full.txt (concatenate the rendered Markdown of every docs page, as the banner implies) or remove the banner reference until it exists. Given the banner also promises .md per page, audit that pattern works too.

2. Spans API endpoint contradicts itself across docs and reference (critical)

Location: /docs/documentation/features/tracing/spans vs /docs/apis/spans/create-span vs /docs/documentation/features/tracing/log-content-types

Problem: Three different docs pages disagree on the canonical Spans ingestion endpoint:

• The manual-ingestion guide posts to https://api.respan.ai/api/request-logs/create/
• The Spans API reference says the canonical URL is https://api.respan.ai/api/request-logs/ and explicitly labels /api/request-logs/create/ as a "legacy alias."
• The log-content-types page (tool-call example) also uses https://api.respan.ai/api/request-logs/.

Consequence: Developers (and agents) who follow the "Trace → Manual Ingestion → Spans API" learning path land on the legacy URL as the official one. Anyone who later hits the API reference sees the same call presented under a different URL with a "legacy" warning. There's no migration timeline or deprecation date, so users cannot tell whether their working code is on borrowed time.

The fix: Update /docs/documentation/features/tracing/spans to use /api/request-logs/ to match the API reference. If /create/ is being kept as an alias, say so explicitly with a deprecation date.

3. Model count contradicts itself: 250+ vs 500+ (significant)

Location: Homepage, /pricing, /docs overview

Problem: The homepage and pricing page both market the gateway as covering "500+ models" (/pricing lists "unified endpoint (500+ models)"; the homepage says "500+ models through one gateway"). The docs overview at /docs says: "route requests across 250+ models through one gateway." The gateway quickstart's "Browse available models" link doesn't reconcile this.

Consequence: A developer evaluating the gateway gets a different answer depending on whether they're reading marketing or docs. For a routing product, the supported-model count is a primary purchase signal — having it differ by 2x across surfaces erodes trust before sign-up.

The fix: Pick one number, ideally derived dynamically from the Models page, and use it across marketing, pricing, and docs.

4. Quickstart gpt-5.4 example is undisclosed and inconsistent with the rest of docs (significant)

Location: /docs/documentation/get-started/gateway, /docs/documentation/features/tracing/log-content-types (Videos example)

Problem: The very first curl call shown to a new user in the gateway quickstart uses "model": "gpt-5.4". The Videos example in the span types reference also uses gpt-5.4. Every other example throughout the docs (Spans API reference, gateway-advanced page, tool-call examples, BYO-credentials examples) uses gpt-4o or gpt-4o-mini. The docs nowhere disclose whether gpt-5.4 is OpenAI-issued or a Respan-internal alias — the changelog (March 20, 2026) just says "added gpt-5.4, gpt-5.4-mini, and gpt-5.4-nano models" with no provider attribution.

Consequence: An agent (or human) copy-pasting the quickstart curl has no way to tell whether gpt-5.4 is a real upstream model, a Respan alias, or a placeholder. If the gateway routes on the slug, the request will fail or behave unexpectedly the first time the user hits the API. There's no "this is a placeholder — replace with a real model" callout, and no link to the Models page from the snippet itself.

The fix: Either replace gpt-5.4 in quickstart and span-type snippets with a model that's universally recognizable (gpt-4o, claude-sonnet-4-5-20250929), or — if gpt-5.4 is a Respan-managed alias for the latest GPT — call that out at the snippet, with a link to a "model aliases" reference.

5. Sidebar navigation links 404 across multiple sections (critical)

Location: Sidebar of every docs page

Problem: Several entries in the persistent docs sidebar lead to 404 pages:

• /docs/documentation/security/security ("Security & Support → Security") — 404
• /docs/documentation/help-and-community/support (the "Support center" CTA target) — 404, even though /docs/documentation/support works
• /docs/documentation/get-started/mcp-cli-agent ("Respan MCP, CLI & Agent" in Get Started) — 404
• /docs/documentation/features/users/customer-identifier ("Users → Customer identifier") — 404
• /docs/documentation/features/monitoring/automations-beta/monitoring (linked from the docs overview) — 404
• /docs/integrations/agent-frameworks/claude-agent-sdk (a featured integration in the Feb 27 changelog) — 404
• /docs/integrations/native/opentelemetry — 404
• /docs/integrations/native/respan-python — 404

Consequence: This isn't a single broken link — it's structural. Customer identifier is the central tracing primitive (it appears in every span schema). Security is an enterprise sales gate. The Claude Agent SDK is one of three Native integrations marketed in the rebrand changelog. Users (and agents crawling the sidebar) hit dead ends on first-class concepts.

The fix: Run a link checker against the rendered sidebar tree. The pattern (some /integrations/native/* URLs work, others 404; /docs/documentation/support works but the sidebar points to help-and-community/support) suggests stale link rewrites from the Keywords AI → Respan migration. Fix the routing rather than papering over with redirects.

6. Lingering keywordsai_* aliases without a deprecation policy (significant)

Location: /docs/documentation/features/gateway/gateway-quickstart

Problem: The gateway docs explicitly say:

• "The legacy key keywordsai_params is still accepted and merged into respan_params."
• "The legacy header X-Data-Keywordsai-Params is still accepted."

These are exposed brand artifacts from the previous company name. The changelog notes the rebrand on Feb 13, 2026 but provides no deprecation timeline, no migration guide, and no warning behavior described (no header response indicating use of the legacy alias).

Consequence: Existing customers writing new code against the docs may copy the Respan-prefixed names while production systems still send keywordsai_params; the next time these are removed silently, requests will start failing. Agents writing code for new projects might pick the legacy name from a stale Stack Overflow post and have no signal it's deprecated.

The fix: Publish a migration page with a sunset date for keywordsai_* keys/headers. Have the gateway emit a Deprecation HTTP header (RFC 8594) when a legacy alias is used, and document that header.

7. Free tier is named "Pro" — directly inverts industry convention (significant)

Location: /pricing

Problem: The free tier ($0/month) is labeled "Pro". The next tier up (the paid one at $199/mo) is called "Team". In nearly every SaaS pricing taxonomy, "Pro" is a paid tier above "Free" or "Hobby" — pricing tables across Stripe, Linear, Vercel, etc., all follow that pattern.

Consequence: Sales and support friction at the most consequential conversion surface. Internal references ("upgrade to Pro") invert their usual meaning, and developers comparing Respan to alternatives will momentarily mis-rank the tiers. The pricing page already adds "(Free)" in parentheses, which is a tell that the naming is fighting itself.

The fix: Rename the $0 tier to "Free" or "Hobby" and rename "Team" to "Pro." If "Pro" must stay on the free tier for legacy reasons (e.g., existing customers chose it in onboarding), document why, but the public pricing surface should match conventional ordering.

8. Live demo page renders empty (significant)

Location: /docs/documentation/get-started/live-demo

Problem: The page is referenced from the quickstart ("Or try it live without installing anything") and titled "Live demo." But the rendered content is essentially: "Add your Respan API key to see live traces." No interactive embed, no fallback iframe, no recorded demo video — just a sentence and a footer. Either the embed is failing to render in the scraped DOM or there is genuinely no demo content on this page.

Consequence: The "try it without installing" path in the official quickstart is a dead end. New users who aren't ready to install the SDK have no actual hands-on entry point.

The fix: Verify the embed renders for unauthenticated visitors and add a no-key fallback (e.g., a recorded trace replay or a screenshot tour). At minimum, gate this page behind authentication if it requires a key, rather than exposing a near-empty page.

9. Trace quickstart has no manual code path — only a CLI that drives a coding agent (significant)

Location: /docs/documentation/get-started/quickstart

Problem: The entire "Trace your first call" walkthrough has one instrumentation step: npx @respan/cli setup. The next sentence: "The CLI uses your preferred coding agent (Claude Code, Cursor, Codex, etc.) to detect your project language, install the Respan SDK, and instrument your code." There is no fallback "here's the Python snippet" or "here's the TS snippet" path on the same page. The "Or try it live without installing anything" link goes to the empty Live demo page (Finding 8).

Consequence: A developer who doesn't have or want a coding agent in the loop, or who is evaluating Respan in CI, has no copy-paste entry point in Get Started. The quickstart presumes the customer is already running an AI coding agent and is willing to let it edit their codebase. Combined with the empty live demo, there's literally no "trace one LLM call from a fresh REPL" path.

The fix: Add a "Manual setup" tab next to the CLI step with a 5-line Python and TS snippet, mirroring the framework integration pages. Keep the CLI as the recommended path, but don't make it the only path.

10. Python SDK ships with a "coming soon" API client (significant)

Location: /docs/sdks/python-sdk/overview

Problem: The headline Respan() facade is described as orchestrating three components, and the architecture diagram literally annotates one of them as not implemented:

├─ RespanTelemetry   ← OTEL tracing pipeline
├─ RespanAPI         ← REST API client (coming soon)
└─ Plugins           ← Activated instrumentations

The page never elaborates on what users can't do until that lands, what the workaround is in the meantime, or which Respan REST endpoints will eventually be wrapped.

Consequence: A developer reading the overview to scope SDK capabilities can't tell whether the SDK can call any of the dozens of REST endpoints documented in the API reference, or only emit traces. Anyone designing an integration around the assumption that Respan() is a full client will hit the silent gap when they try to programmatically create datasets, scores, or experiments.

The fix: Either remove the placeholder from the architecture diagram or document explicitly: which REST surface area is in scope, the target version, and the recommended pattern (raw requests.post(...)) until it ships.

11. TypeScript SDK requires three packages with no rationale (significant)

Location: /docs/sdks/typescript-sdk/overview

Problem: The TS install line is npm install @respan/respan @respan/respan-sdk @respan/tracing — three separate packages, all under the same scope, with no explanation on the page of what each package is for or why they aren't a single meta-package. The Python equivalent is one line: pip install respan-ai.

Consequence: A new TS user has to know all three package names exactly to onboard, and any of them being subtly out of date will produce inscrutable peer-dep errors. The asymmetry with the Python SDK isn't justified anywhere — and @respan/respan and @respan/respan-sdk are nearly identical names, which is the kind of footgun where a typo silently installs the wrong thing.

The fix: Ship a single meta-package that depends on the three (or merge them). Failing that, document on this page what each of the three provides and which combinations make sense for which use cases.

12. Prompt schema v2 is "recommended" but incompatible with the recommended SDK pattern (significant)

Location: /docs/documentation/features/prompt-management/advanced

Problem: The page says: "Set schema_version=2 for the recommended merge behavior." In the very next paragraph: "OpenAI SDKs strip fields like schema_version, patch, and prompt_slug during validation. Prompt schema v2 requires raw HTTP requests." Yet the rest of the docs (gateway quickstart, provider keys page) consistently demonstrate the OpenAI SDK pattern (from openai import OpenAI; client.chat.completions.create(...)).

Consequence: Customers following the gateway quickstart adopt the OpenAI SDK shape, then hit a paywall of incompatibility the moment they try to use the "recommended" prompt schema. There's no extra_body workaround documented for v2 fields, and no migration guide explaining when to switch from SDK to raw HTTP.

The fix: Either (a) make the OpenAI SDK pass schema_version/patch/prompt_slug through extra_body and document that pattern, or (b) stop calling v2 "recommended" while it requires abandoning the SDK pattern the rest of the docs teach. Add a top-of-page callout explaining the SDK trade-off.

13. Bearer token format in API reference uses sk_live_xxxxx not RESPAN_API_KEY pattern (significant)

Location: /docs/apis/spans/create-span vs the rest of the docs

Problem: The Spans API reference shows Authorization: Bearer sk_live_xxxxx while every other page (gateway quickstart, OTLP ingest, tracing SDK) uses Bearer YOUR_RESPAN_API_KEY. There's no explanation of whether sk_live_* is the actual issued format, a Stripe-derived placeholder, or just inconsistent template text.

Consequence: The API reference is the surface agents and integrators copy from most carefully. A Stripe-shaped sk_live_* placeholder will lead callers to write validation regex (/^sk_live_[a-zA-Z0-9]+$/) that may not match Respan's actual issued format, and may strip real keys in log redactors. There's no place in the docs that documents the canonical key prefix.

The fix: Standardize on one placeholder (YOUR_RESPAN_API_KEY or the real prefix if there is one). Document the actual issued key prefix once, near the top of the API keys admin page, so log-redaction and validation can be implemented correctly.

14. Auto-instrumentation matrix is uneven across runtimes with no rationale (minor)

Location: /docs/documentation/features/tracing/traces

Problem: The auto-instrumented SDK matrix lists Mistral, Ollama, and Groq as Python-only (✅ / —). No accompanying note explains whether TS support is planned, whether to use OpenTelemetry as a workaround, or whether extra_body parameters work cross-runtime.

Consequence: A TypeScript developer evaluating Respan for a Groq-backed app reads "Groq supported" elsewhere, then hits "—" here, and has no path forward in the docs.

The fix: Add a footnote per gap: link to the manual OTLP ingest path for unsupported runtimes, or a roadmap entry. The bare em-dash leaves users guessing.

15. API keys admin page never explains revocation or rotation (minor)

Location: /docs/documentation/admin/respan-api-keys

Problem: The page covers creation, environment tagging, expiration, rate/spend limits, and "markup percentage" — but contains no instructions for revoking a key, rotating keys, or what happens to in-flight requests when a key is revoked. There's no mention of programmatic key rotation either, despite the changelog adding "API key management" to MCP tools.

Consequence: Key rotation is the most common security operation a developer performs against an API-keys admin surface. Leaving it undocumented means leaked keys stay live longer (developers don't know whether deletion is immediate) and incident response is slower.

The fix: Add a "Rotate or revoke a key" section: how to revoke from the UI, what HTTP status callers see post-revocation, propagation delay if any, and a link to the MCP tool for programmatic rotation.

16. Provider keys docs lead with a typo and an unclear policy (minor)

Location: /docs/documentation/admin/llm-provider-keys

Problem: The page opens: "We current don't support LLM proxy users using Respan credentials, so you have to add your own credentials for each model you want to use." This has a typo ("current" → "currently"), and the phrase "LLM proxy users using Respan credentials" is opaque — it's unclear whether this means BYO-keys-required, no-shared-pool, or something else.

Consequence: First sentence on the page sets expectations for the entire BYO-keys flow. As written, a reader can't tell whether Respan ever plans to offer proxy-default credentials, or whether this is a permanent product position.

The fix: Rewrite to: "Respan requires you to bring your own provider credentials. There is no shared key pool — every model you call must have a credential added in your workspace." Then, if relevant, link to a roadmap entry.

17. Status doc page is wired to nothing despite a real status page existing (minor)

Location: /docs/documentation/status

Problem: The "Status" doc page contains the heading "Real-time status of Respan services" and nothing else — no link, no embed, no historical uptime. The Support page (/docs/documentation/support) explicitly lists a "Status Page" entry with the description "Real-time system status," meaning a real status page exists somewhere — the docs Status page just isn't pointed at it.

Consequence: The Team and Enterprise tiers commit to a 99.9% / 99.99% uptime SLA on the pricing page. A buyer doing diligence on those SLAs has no way to verify historical performance from inside the docs even though the Support page implies the data exists.

The fix: Wire this page to the actual status page URL referenced from the Support page (embed it, or replace with a link plus historical uptime summary). The fix is plumbing, not new content.

18. Evaluator condition operators undefined for non-numeric grader types (minor)

Location: /docs/documentation/features/evals/evaluators

Problem: Graders support four output data types: Number, Boolean, Categorical, and Comment. The Conditions block lists operators >, <, >=, <=, ==, !=. The page never explains how > or < apply when a grader's output type is Categorical or Comment, or how == matches against a Comment (substring? exact? case-sensitive?).

Consequence: A user building an evaluator that routes on a categorical grader (e.g., severity = "high") has to guess whether == does string match, exact-case match, or whether ordered operators work at all on enum-shaped graders. The visual builder will let them connect the blocks regardless, surfacing the failure at runtime.

The fix: Add an operator-by-data-type table to the evaluator builder reference: which operators are valid for each of the four grader output types, and the matching semantics (case-sensitive? substring vs equality?).

19. Inline-router example uses an older Claude version than the Pin-a-provider example on the same page (minor)

Location: /docs/documentation/features/gateway/advanced and /docs/documentation/features/gateway/gateway-quickstart

Problem: Within the gateway-advanced and gateway-quickstart pages, two adjacent examples use different Claude version strings: the inline-router example uses claude-sonnet-4-20250514, and the Pin-a-provider header example uses claude-sonnet-4-5-20250929. There's no commentary that one is older or that the user should pick a specific dated slug.

Consequence: A reader can't tell whether the difference matters. Customers may copy claude-sonnet-4-20250514 from one snippet, end up on a model their workspace doesn't have credentials for, and have no signal in the doc that newer dated slugs exist.

The fix: Standardize Claude examples to one current dated slug across the gateway pages, and reference the Models page once for "find the latest slug."

What they do well

• Concept model is genuinely clean. The "everything is a span; spans group into traces and threads" framing on /docs/.../tracing/concepts gives both humans and agents a consistent mental model that propagates through the rest of the docs.
• Eval quickstart is meaningfully deeper than the trace quickstart. The four-part walkthrough (prompt → dataset → evaluator → experiment) is one of the few quickstarts that tells you the why alongside the how.
• OpenAI compatibility is treated seriously. The gateway accepts top-level body fields, respan_params, and a base64-header alternative — this is the right surface area for a drop-in proxy.

Top 3 recommendations

1. Fix the rebrand fallout before anything else. Resolve the sidebar 404s (security, customer-identifier, mcp-cli-agent, claude-agent-sdk), make /llms-full.txt actually exist, and reconcile the Spans endpoint URL across the manual-ingestion page and the API reference.
2. Give the trace quickstart a manual code path. The CLI-driven-by-coding-agent flow is a fine A path; ship the bare 5-line Python/TS snippet as B. Right now the only escape hatch is the empty Live demo page.
3. Make SDK onboarding symmetric and honest. Collapse the three TS packages into one, or document why they're three. Drop the "coming soon" badge from the Python SDK overview architecture diagram or scope what it'll cover. And pick one model count (250+ vs 500+) and one tier-naming convention so the highest-traffic surfaces stop disagreeing.