The Token Company Documentation Audit

The docs are short and clean on the surface, but the machine-readable artifacts that agents and SDK generators rely on are broken or contradictory: the published OpenAPI spec is the Mintlify Plant Store demo, intra-doc links 404, the free-tier token allowance disagrees with itself by 20×, and two of the three advertised models are never mentioned in the docs.

1. Published OpenAPI spec is the Mintlify Plant Store demo (critical)

Location: https://thetokencompany.com/docs/api-reference/openapi.json (linked from /docs/llms.txt as the official "OpenAPI Specs")

Problem: The openapi.json advertised in llms.txt is not the Token Company API at all — it is the default Mintlify demo spec describing GET /plants, POST /plants, DELETE /plants/{id}, a /plant/webhook, and Plant/NewPlant/Error schemas. Nothing about /v1/compress, aggressiveness, bear-1.2, or ttc_safe appears.

Consequence: This is the single most damaging defect in the audit. Any agent (Claude Code, Cursor, Copilot) or code generator (openapi-generator, swagger-codegen, Stainless, Speakeasy) pointed at this URL will silently produce a "Plant Store" client. Because llms.txt declares it as the API spec, agents will trust it. The actual compression API has zero machine-readable description.

The fix: Replace openapi.json with a real spec for POST /v1/compress (and any other endpoints), including compression_settings.aggressiveness, model, request/response schemas, the Content-Encoding: gzip behavior, all error response shapes, and the bearer-auth scheme. Add CI to fail if the file still contains "plant".

2. gzip docs page links to /python-sdk, which 404s (critical)

Location: /docs/gzip.md (verbatim) → /python-sdk (404)

Problem: The gzip page contains the literal text "If you're using the Python SDK or the [npm package]…" — a root-relative link to /python-sdk. The Python SDK actually lives at /docs/python-sdk. A probe of /python-sdk returns HTTP 404, as do /gzip and /protect-text (likely-parallel intra-doc paths that were probed and confirmed dead).

Consequence: A developer reading the gzip recommendation and clicking through to the Python SDK install instructions hits a 404. Agents following hyperlinks from llms.txt-listed pages lose the SDK install/usage docs.

The fix: Rewrite the link to /docs/python-sdk (or whatever the Mintlify route prefix actually is), audit every other intra-doc link for the same /docs/ prefix bug, and add a link-checker to CI against the rendered site.

3. SDK exception lists disagree across docs pages and GitHub READMEs (significant)

Location: /docs/python-sdk.md, /docs/npm-sdk.md, github.com/TheTokenCompany/tokenc-python-sdk README, github.com/TheTokenCompany/tokenc-npm-sdk README

Problem: Verbatim-verified: both GitHub READMEs document exactly 3 exception types — AuthenticationError, RateLimitError, APIError. The npm README's "Error Handling" line is explicit: "Supports AuthenticationError, RateLimitError, and APIError exception types." The Python README's "Exception Types" section is the same three. The docs-site pages for both SDKs cover the same error-handling surface but with different counts (the Python docs page lists 4 exception types and the npm docs page lists more), creating a drift between what pip install/npm install actually ships and what the hosted docs page advertises.

Consequence: A developer who writes try/except InvalidRequestError (or equivalent) based on the docs page may hit an AttributeError if the installed package only exports the three the README documents. Agents generating defensive error-handling code from the docs page will guess wrong about what symbols exist.

The fix: Pick one canonical exception list, generate it from the SDK source, and reuse the same list in both docs pages, both READMEs, and any example snippets. If the docs page lists symbols the package doesn't export, either ship them or remove them.

4. Free-tier token allowance contradicts itself by 20× (significant)

Location: /pricing vs / (homepage)

Problem: The pricing page describes the Free Tier as "First 50M input tokens free." The homepage states "Free tier provides up to 1 billion monthly processed tokens with access to select models." That is a 20× discrepancy in a customer-facing entitlement, on two of the most-visited pages on the site.

Consequence: A developer evaluating Token Company for a workload sized around the free quota cannot tell whether they get 50M or 1B tokens. In enterprise procurement, a contradictory free-tier limit on the public site is a credibility red flag and an immediate question on any security/legal review.

The fix: Pick one number, fix the other page, and add a single source-of-truth (e.g. a pricing component or constants file) so the marketing and pricing surfaces cannot drift again.

5. Two of three advertised models are never documented (significant)

Location: / (homepage) vs /docs/*

Problem: The homepage names three compression models — bear-1 (November 2025), bear-1.1 (February 2026), bear-1.2 (latest) — with launch dates and stated differences. Inside /docs/, only bear-1.2 is used (in /docs/index.md quickstart and /docs/examples.md provider snippets). There is no model reference page enumerating which model: strings are valid, what each does, which is default, or which bear-1.1-specific accuracy/speed claims apply to which workloads.

Consequence: Developers cannot tell whether bear-1 or bear-1.1 are still callable, whether bear-1.2 is the default if model is omitted, or which model to pin in production. Agents generating SDK calls have one example string (bear-1.2) and no schema to validate against, especially since the OpenAPI spec is the Plant Store.

The fix: Add a /docs/models page listing each model: string, its status (GA / deprecated / removed), launch date, behavior, and recommended use case. Reference it from the API Reference and from the OpenAPI spec's enum for the model field.

6. No documented error reference — status codes, retry headers, and rate-limit shape are absent (significant)

Location: site-wide; no /docs/errors or equivalent page exists

Problem: A GET to https://api.thetokencompany.com/v1/compress returns 405 Method Not Allowed with no documented Allow: contract. The docs never enumerate HTTP status codes, error response bodies, rate-limit headers (the pricing page advertises "10 requests per minute" free / "60 requests per minute" pro but nothing documents the response when you exceed them), or retry semantics. The SDK exception list is the only hint that RateLimitError / AuthenticationError / APIError are even possible.

Consequence: Developers writing production retry logic have no contract to code against — they must reverse-engineer status codes by triggering them, and agents generating error-handling code have nothing structured to read. Rate-limit backoff is impossible without knowing whether a Retry-After header is sent.

The fix: Add an "Errors" reference page enumerating every status code, the JSON error envelope, every error code string, and which SDK exception each maps to. Document Retry-After (or whatever header is used) and the rate-limit headers on rate-limited responses.

7. Authentication is never documented end-to-end (significant)

Location: site-wide; no /docs/authentication page exists

Problem: The only authentication-related content in the docs is the quickstart line "Get your API key by [creating an account]" linking to accounts.thetokencompany.com/sign-up. No /docs/ page documents the header name, scheme (Bearer? X-API-Key?), key format, key rotation, scopes, expiration, or how to revoke a key. The OpenAPI spec that should carry the securitySchemes block is the Plant Store demo (see Finding 1), so even the machine-readable surface is silent. The SDK READMEs show new TokenClient({ apiKey: "your-api-key" }) but never show the underlying HTTP call.

Consequence: A developer using cURL or any non-SDK HTTP client cannot tell from the docs what header to send. Agents generating raw HTTP calls (e.g. from a Postman collection or a curl snippet) have no contract for the auth header. Enterprise security reviews that ask "how is the API authenticated and how are keys rotated?" have no doc page to cite.

The fix: Add a /docs/authentication page covering the header name, scheme, where to create/revoke keys, rotation policy, and whether keys expire. Mirror the scheme in openapi.json's securitySchemes once that file is fixed.

8. Two different official contact emails for the same support flow (significant)

Location: /docs/data-retention.md vs /contact

Problem: The data-retention doc instructs users to enable zero data retention by emailing rasmus@thetokencompany.com. The site's public Contact page lists the support email as otso@thetokencompany.com. No page reconciles the two.

Consequence: A customer with a compliance requirement (the actual reason they're reading the data-retention page) emails an address that may not be monitored, or wonders whether the docs are stale. For enterprise procurement reviews where data-handling guarantees matter, inconsistent contacts are a red flag.

The fix: Use a role-based address (e.g. support@ or privacy@) on both pages, or pick one human and use it consistently. Surface the same address on the contact page, data-retention doc, and Trust Center.

9. "Tokens saved" billing unit is never defined (significant)

Location: /pricing; no /docs/billing page exists

Problem: The pricing page charges "$0.30 per 1M tokens saved" with the parenthetical "Token counts use the Gemma 2 tokenizer," and a worked example ("$18.80 net savings on 10M tokens compressed to 6M"). Nothing in /docs/ defines what "saved" means computationally: is it input_tokens − output_tokens for the compression call? Is it aggregated per billing period or per call? Is the Gemma 2 tokenizer applied to both sides? How is rounding handled?

Consequence: This is a usage-priced API and "tokens saved" is the billing unit — a developer cannot reconcile their bill, build a cost model, or set a budget alert without the formula. Finance and procurement teams cannot sign off on a unit-priced contract without a definition.

The fix: Add a /docs/billing page (or a "Billing" section in the API Reference) defining tokens_saved, the tokenizer used on each side of the equation, the aggregation/rounding rule, and ideally exposing the per-request value in the API response.

10. No changelog or release-notes surface for a product on its third model release (significant)

Location: /docs/changelog → HTTP 404

Problem: /docs/changelog returns 404. There is no /changelog, no /releases, and no equivalent page anywhere on the site. The homepage advertises three model releases (bear-1 in November 2025, bear-1.1 in February 2026, bear-1.2) within six months, but no doc page records what changed, what was deprecated, or whether older models remain callable.

Consequence: Developers pinning a model in production cannot tell when behavior changed under them. Agents have no canonical document to read when asked "what's new in bear-1.2." Enterprise customers cannot audit version history for compliance.

The fix: Publish /docs/changelog (or /changelog) with dated entries for each model release, API change, and pricing change. Link it from the docs nav and from llms.txt.

11. Most docs pages are missing from sitemap.xml (significant)

Location: /sitemap.xml

Problem: The sitemap contains only /docs and /docs/examples from the docs tree (plus /llms.txt and /llms-full.txt). /docs/python-sdk, /docs/npm-sdk, /docs/gzip, /docs/protect-text, /docs/data-retention, and /docs/api-reference/openapi.json are not listed. They are, however, in llms.txt.

Consequence: Search engines and crawlers that rely on the sitemap will not index the SDK or feature pages. Discovery for human developers via Google is degraded; only the LLM-readable index sees the full surface.

The fix: Generate the sitemap from the same source-of-truth that builds llms.txt, or have Mintlify emit it automatically. Ensure every published /docs/** page is present.

12. "Experimental" Protect Text feature has no version, scope, or stability contract (minor)

Location: /docs/protect-text.md

Problem: The Protect Text page carries a single <Warning>This feature is experimental.</Warning> banner with no further detail — no API version where it landed, no list of known limitations, no statement about whether ttc_safe tags inside compressed output are guaranteed to round-trip, no removal/stability timeline.

Consequence: Developers cannot judge whether to depend on ttc_safe in production. Compliance use cases (e.g. PII redaction) need to know whether the tag is guaranteed to be preserved verbatim or merely best-effort.

The fix: Add a "Stability" subsection: what version it shipped in, what guarantees Token Company makes, what could change, and the recommended fallback if the tag is dropped.

13. Default aggressiveness is inconsistent across docs and SDK README (minor)

Location: /docs/index.md (API Reference quickstart) vs github.com/TheTokenCompany/tokenc-npm-sdk README

Problem: Every snippet in the API Reference quickstart uses "compression_settings": {"aggressiveness": 0.1}. The npm SDK README's basic-usage example uses aggressiveness: 0.5. Nothing in either page tells the reader which is the API default if the field is omitted, or which value the docs author considers "recommended."

Consequence: A developer copying the quickstart gets one compression behavior; a developer copying the npm README gets noticeably more aggressive compression with potentially different accuracy characteristics. With pricing tied to tokens saved, the choice matters financially.

The fix: State the server-side default explicitly in the API Reference, pick a single recommended value, and align all quickstart snippets across the docs site and both SDK READMEs.

14. Root llms-full.txt is a marketing summary, not the concatenated docs (minor)

Location: /llms-full.txt

Problem: The site publishes /llms-full.txt at the root, but its body is a paragraph of marketing summary ("Reduce tokens by 66%, cut AI costs by 3x…"), not the concatenated content of every .md doc page that the llms-full.txt convention implies. The per-page .md files referenced from /docs/llms.txt carry the actual content.

Consequence: Agents following the llms-full.txt convention to grab the full doc dump in one fetch will instead receive marketing copy and think they have the complete documentation. They then either skip the docs entirely or follow the llms.txt index for individual pages — defeating the point of the -full file.

The fix: Make /llms-full.txt contain the concatenated body of every .md doc page (which is what the convention exists for) and keep the marketing summary elsewhere.

15. Benchmarks page is orphaned from the docs (minor)

Location: /benchmarks (site) vs /docs/* (docs)

Problem: /benchmarks hosts five concrete results (Pax Historia, financial QA, latency, SQuAD 2.0, CoQA) with specific numbers, but no page under /docs/ links to it, and it isn't in llms.txt. The docs' only quantitative claims (throughput tables in /docs/gzip.md) live elsewhere.

Consequence: Agents indexing the docs miss the strongest evidence that compression doesn't hurt accuracy — exactly the question a buyer asks. Developers evaluating the product have to find the benchmarks via the marketing nav.

The fix: Cross-link /benchmarks from the API Reference and from a new "Accuracy & Benchmarks" doc page, and add it to llms.txt.

What they do well

• llms.txt exists and enumerates every doc page as a .md URL — agent-friendly in principle, even if the surface it points to has the issues above.
• Code examples cover three providers (OpenAI, Claude, OpenRouter) in both Python and TypeScript with realistic SDK usage.
• The data-retention page is unusually specific (3600-second cache window, exact retained fields table) — the kind of detail enterprise procurement actually asks for.

Top 3 recommendations

1. Replace the Plant Store openapi.json with a real spec for /v1/compress and gate it in CI. This is the single highest-leverage fix for agent consumption.
2. Reconcile the free-tier token allowance (50M vs 1B) and publish an authoritative model reference covering bear-1, bear-1.1, and bear-1.2 — these are the two contradictions a procurement reviewer will catch first.
3. Document authentication, errors, and "tokens saved" end-to-end in /docs/, so developers can write production retry/budget logic without reverse-engineering the API.