The docs cover a broad API surface (brand data, web scraping, industry classification, Logo Link, no-code integrations) but suffer from systematic URL drift between the index, guides, and the API reference, several references to undocumented or unreleased features, API reference pages that are little more than auto-generated OpenAPI stubs, and undocumented gating on a recommended endpoint. Below are the concrete issues.
1. API reference URL paths are inconsistent across pages — many internal links 404-prone (critical)
Problem: The same endpoints are linked under at least two different /api-reference/... parents depending on which page you read.
Brand-by-domain: index links /api-reference/brand-intelligence/retrieve-brand-data-by-domain, but onboarding-flows and the EIC guide link /api-reference/retrieve-brand/retrieve-brand-data-by-domain.
Transaction enrichment: index links /api-reference/brand-intelligence/identify-brand-from-transaction-data, but the transaction-categorization guide links /api-reference/retrieve-brand/identify-brand-from-transaction-data.
NAICS: index links /api-reference/web-extraction/classify-naics-industries, but the industry-classification intro links /api-reference/industry-classification/retrieve-naics-code-for-any-brand.
SIC: index links /api-reference/web-extraction/classify-sic-industries, but the industry-classification intro links /api-reference/industry-classification/classify-sic-industries.
Consequence: At most one of each pair resolves; the other is a dead link. Worse, AI coding agents that follow internal hrefs to disambiguate endpoints will see contradictory canonical paths for the same operation and may fabricate either route in generated code. Humans clicking from the homepage land on the "wrong" reference path silently.
The fix: Pick one canonical taxonomy (the OpenAPI spec uses paths like /brand/retrieve, /web/naics, /web/sic, /brand/ai/products — let docs mirror that grouping) and run a link-check across the entire site. Add a redirect map for the deprecated paths so old links don't 404.
2. Prefetch-by-domain endpoint is referenced but only prefetch-by-email is documented (critical)
Problem: The brand-kits guide says "Use the prefetch endpoint to start fetching data early," but the only utility endpoint that appears in the scraped API reference is /api-reference/utility/prefetch-brand-data-by-email (POST /brand/prefetch-by-email). There is no prefetch-brand-data-for-a-domain page listed anywhere else.
Consequence: Developers building the documented brand-kit flow click the link, hit a 404, and have no way to know whether a domain-based prefetch endpoint exists, what method/path/credits it has, or whether they should fall back to the email variant. Agents will hallucinate a POST /brand/prefetch-by-domain based on the link slug.
The fix: Either ship the domain-prefetch endpoint reference page (with method, path, params, credits) or rewrite the guide to point at prefetch-by-email and explain the domain workaround.
3. The recommended prefetch-by-email endpoint is silently subscriber-gated (significant)
Location:/guides/use-cases/onboarding-flows vs. /api-reference/utility/prefetch-brand-data-by-email
Problem: The flagship onboarding guide makes prefetch the primary latency strategy: "If a user is signing in with email/password we recommend firing a prefetch request as soon as the email field passes input validation." The endpoint reference page, however, carries an Only for Subscribers badge alongside the 0 Credits badge. The onboarding guide never mentions this gating, and there is no link from the guide to a tier/eligibility page.
Consequence: Developers on lower tiers (or on free trials) will follow the recommended onboarding pattern, wire prefetch into their email-validation handler, and only discover at integration-test time that the call fails for them. They then have to refactor the onboarding flow they just built around the now-missing latency primitive.
The fix: Add a "Plan requirements" callout in the onboarding guide right where prefetch is recommended, and mirror the same note in automating-brand-kits. Link to a pricing/tier page from the badge.
4. Troubleshooting references an endpoint that isn't documented (/brand/retrieve-by-name) (significant)
Location:/guides/get-started/troubleshooting
Problem: The 400-error section says: "Company name must be 3-30 characters for /brand/retrieve-by-name." No retrieve-by-name endpoint appears in the index, the brand-intelligence reference list, the SDK examples, or the llms.txt summary. The documented brand lookups are by domain, by email, and the simplified-by-domain variant.
Consequence: Either the endpoint exists and is undocumented (developers can't discover its path, response schema, or credit cost), or it's stale documentation pointing at a removed endpoint. Agents that read this page will start emitting calls to a phantom URL.
The fix: If retrieve-by-name is real, add a full reference page under brand-intelligence with the same shape as the other three. If it's been removed, delete the troubleshooting entry.
5. n8n is listed as an "officially maintained" integration but is "Coming Soon" (significant)
Location:/integrations/introduction vs /integrations/n8n
Problem: The integrations overview states: "Context.dev officially maintains integrations for Zapier, Make and n8n." The same page's platform table marks n8n as "Coming Soon," and /integrations/n8n itself is just a one-line "Coming Soon" placeholder. The overview also recommends "we recommend using n8n or Make" — recommending an unreleased integration.
Consequence: A developer evaluating Context.dev for an n8n project will read the overview, choose Context.dev, then discover the integration doesn't exist. Mixed messaging undermines trust in the rest of the integration claims.
The fix: Remove n8n from the "officially maintains" sentence and from the recommendation until it ships, or add a clearly-labeled Beta/Preview status with an ETA.
6. Onboarding-flows guide is missing sections 2 and 3 (significant)
Location:/guides/use-cases/onboarding-flows
Problem: The numbered architecture jumps from "1. Collecting User Domain/Email" directly to "4. Image Selection." There is no step 2 or 3 in the scraped content, yet the surrounding prose ("we recommend firing a prefetch request as soon as the email field passes input validation") implies a multi-step flow.
Consequence: This is the docs' flagship onboarding use case (it's one of the three top-level Cards on the homepage). Developers following the guide hit a hole in the middle of the integration narrative — the actual brand-fetch and form-population steps are absent.
The fix: Restore the missing steps 2 (e.g., "Fetching brand data after sign-up") and 3 (e.g., "Populating the onboarding form") with code examples, or renumber so the visible steps are sequential.
7. API reference pages are auto-generated OpenAPI stubs with no examples or field-level prose (significant)
Location: every /api-reference/... page (e.g. retrieve-brand-data-by-domain, scrape-fonts, scrape-images, extract-products-from-a-brands-website, prefetch-brand-data-by-email)
Problem: Each reference page in the scraped content is one line ("Retrieve logos, backdrops, colors, industry, description, and more from any domain"), the source pointer to the Stainless OpenAPI spec, and a credit badge. There are no inline request bodies, no example responses, no field descriptions, and no code samples on the reference pages themselves. The SDK examples live only in the Quickstart accordion.
Consequence: Agents and humans relying on the reference pages — which is what reference pages are for — see almost nothing. They have to either dig into the Stainless-hosted OpenAPI spec or scrape the SDK example out of an unrelated quickstart accordion. Cross-language users (Ruby, Python, untyped HTTP) get no per-endpoint code at all.
The fix: Hydrate each reference page with a curl example, an SDK example for at least TS+Python, a sample 200 response, and the most common error responses. Mintlify supports rendering this directly from the OpenAPI spec — turn it on.
8. Base URL versioning is inconsistent — /v1/ appears in Make docs but nowhere in the API reference (significant)
Location:/integrations/make vs. all /api-reference/... stubs
Problem: The Make integration's HTTP-module setup hardcodes https://api.context.dev/v1/brand/retrieve as the URL. Every API reference stub instead lists the endpoint as get /brand/retrieve or post /brand/ai/products — no version segment, no base URL declared on the page. The Authentication page is also truncated and never states the base URL. The SDK quickstart hides it inside the client constructor.
Consequence: A developer building a raw HTTP client (e.g., from curl, from a non-supported language, from another no-code tool) has to guess whether to use https://api.context.dev/... or https://api.context.dev/v1/.... If the unversioned base is ever versioned later, every Make HTTP-module workflow built from these docs will silently keep working at /v1/ while reference-following clients break.
The fix: Declare the canonical base URL once in Authentication and once at the top of the API reference. Pick one of /v1/ or unversioned and align Make's example to it. If both work, document the equivalence explicitly.
9. Parameter casing is inconsistent across the API surface (significant)
Problem: Parameter casing flips between snake_case and camelCase: transaction enrichment documents country_gl (snake), troubleshooting documents timeoutMS (camel), and Logo Link documents publicClientId (camel). There is no documented convention.
Consequence: Developers (and agents auto-generating clients) will guess wrong half the time and get 400 errors with no obvious cause. With the API reference pages providing little prose, this convention drift isn't recoverable from a single page.
The fix: Pick one casing convention, document it in Core Concepts, and either alias or correct the off-pattern parameters. At minimum, add a "Parameter naming" note to Core Concepts that says explicitly which endpoints use which case.
10. Authentication and Core Concepts pages are essentially empty stubs (significant)
Problem: The Authentication page ends after "Include your API key in the Authorization header with the Bearer prefix:" — no example header value, no error responses, no key-rotation guidance, no rate-limit discussion, no information on what happens when a key is invalid or expired. The Core Concepts page consists of one heading ("API Response Structure") and a single sentence ("Every Context.dev API response follows a consistent structure:") with nothing after it.
Consequence: The two pages a developer (or agent) hits first to understand auth and the response envelope contain almost no usable information. Combined with the auto-generated API reference stubs (Issue #7), the entire "how do I actually call this thing" surface is missing. Agents indexing the docs cannot extract a single complete request example end-to-end.
The fix: Fill in Authentication with a concrete Authorization: Bearer sk_live_...-style example, the 401 response shape, key-rotation/revocation steps, and a link to rate limits. Fill in Core Concepts with the actual envelope (success vs. error fields, where brand lives, pagination/cursor behavior).
11. "AI Products Extraction" is still flagged Beta four months after release (minor)
Location:/guides/use-cases/ai-products-extraction and /api-reference/web-extraction/extract-products-from-a-brands-website
Problem: The guide says: "Beta Feature - The AI Products Extraction API was released in January 2026 and is currently in beta." Today is 2026-05-08. The API reference page also still carries the Beta badge with no GA date, no list of beta caveats, and no "things that may change" section.
Consequence: Developers don't know whether the response shape, pricing (10 credits), or endpoint path is stable enough to depend on in production. "Beta" without scope is functionally a warning sticker that says nothing.
The fix: Either announce GA, or document concretely what "beta" means here: which fields may change, whether breaking changes will be versioned, and a target GA date.
12. Logo Link "no caching allowed" contradicts its own 24-hour browser cache header (minor)
Location:/logolink/usage-restrictions
Problem: The page states "You are not allowed to store or cache logos retrieved from Logo Link" and immediately follows with "Logos are served with a 24-hour cache header which means that browsers will only request the logo once every 24 hours."
Consequence: A developer reading the first sentence may try to defeat browser caching to comply, defeating the billing model. A developer reading the second sentence may add a CDN in front and assume it's fine. The line between "browser cache OK, edge/server cache not OK" is never drawn explicitly.
The fix: Rewrite as: "End-user browser caching via the 24-hour Cache-Control header is permitted and expected. You may not cache or store logos in your own backend, CDN, database, or filesystem." Then clarify how this interacts with serverless/edge runtimes that proxy requests.
13. llms.txt is a short marketing summary, not a per-page index (minor)
Location:/llms.txt
Problem: The transaction-categorization page tells agents: "Fetch the complete documentation index at: https://docs.context.dev/llms.txt — Use this file to discover all available pages before exploring further." The actual file (per the fetched content) is a five-paragraph high-level summary of capability categories — it does not enumerate page URLs, titles, or descriptions in the per-link format llms.txt is meant to provide.
Consequence: Agents that follow the docs' own instruction to use llms.txt for discovery cannot discover anything from it — they get a paragraph of marketing copy.
The fix: Replace the current llms.txt with a proper per-link index (one bullet per page, each with title + URL + 1-line description). If a llms-full.txt is also published, link it from llms.txt for agents that want full content.
14. Make integration action names drift from API reference names (minor)
Location:/integrations/make vs. /api-reference/web-extraction/...
Problem: The Make integration's "Context.dev Actions" list uses names like "Screenshot Capture" and "Styleguide Extraction." The corresponding API reference uses "Scrape Screenshot" and (per the index) scrape-styleguide. There is no mapping table connecting Make action names to API endpoint names.
Consequence: A developer who prototypes in Make and then ports to a direct API call has to guess which endpoint each Make action wraps. Search across the docs for "Screenshot Capture" returns the Make page; search for "Scrape Screenshot" returns the API reference — same operation, two names.
The fix: Add a one-column mapping at the top of /integrations/make: each Make action name → the underlying API endpoint slug it calls. Use the API names as the canonical strings.
What they do well
The Logo Link vs. core Brand API comparison table is a genuinely clear product-boundary explainer — most vendors leave this fuzzy.
Industry classification intro (EIC vs. NAICS vs. SIC) is unusually well-scoped: it tells you which is inline on the brand response and which require separate calls.
The fact that they ship a prefetch endpoint at 0 credits, with explicit guidance on when to fire it during onboarding, is a thoughtful API-design decision and is documented as such (modulo the subscriber-gating gap in Issue #3).
Top 3 recommendations
Run a link-checker and unify /api-reference/... paths. The same endpoint should not live under two parents; today the homepage and the use-case guides point to different paths for the same API (Issue #1).
Hydrate the API reference, Authentication, and Core Concepts pages with concrete request/response examples and per-field descriptions. Right now those pages are thin shells over the OpenAPI spec or one-sentence stubs; everything useful lives in unrelated guide pages (Issues #7, #10).
Resolve the phantom and gated endpoints — ship docs for prefetch-brand-data-for-a-domain and retrieve-by-name or remove the references that promise them, and surface the Only for Subscribers gating wherever prefetch is recommended (Issues #2, #3, #4).
Verified the Context.dev public docs against the installed context.dev@1.17.0 JS SDK and live https://api.context.dev/v1 endpoints. The supplied API key ([REDACTED]) is rejected by the live API as error_code: DISABLED, so all live SDK / curl-with-key snippets are SKIPPED for unavailable credentials rather than FAILED. Six FAIL snippets are independent of the disabled key:
The curl example in Authentication (and re-used in Troubleshooting) is sent as POST with a JSON body, but /v1/brand/retrieve only accepts GET with query params. Both unauthenticated and authenticated POSTs return 403 "The API you have tried to access does not exist." — proof the route does not exist for POST. A keyless GET against the same path returns the proper 401 Unauthorized: No API key provided error, confirming the route exists for GET.
Four use‑case examples reference SDK methods/objects that do not exist on the published context.dev npm package: client.brand.identifyTransaction, client.utility.prefetchByDomain, client.styleguide.retrieve, and client.brand.ai.products. The actual SDK exposes client.brand.identifyFromTransaction, client.utility.prefetch, client.web.extractStyleguide, and client.ai.extractProducts respectively.
Python and Ruby snippets were skipped — neither pip nor ruby is available in this sandbox, so the runtime is unavailable. Spreadsheet IMAGE() formulas, Logo Link URL examples, MCP npx server-launch, Anthropic-SDK examples, and Make/Zapier scenario configs were skipped (placeholder IDs, external runtimes, or non-shell environments).
Required credentials
CONTEXT_DEV_API_KEY — provided as brand_…0367, but the live API reports it as DISABLED. Treated as unavailable for execution.
Logo Link publicClientId (format brandLL_…) — not provided; placeholder brandLL_xxx returns 401 Invalid publicClientId.
ANTHROPIC_API_KEY — not provided (needed for /guides/use-cases/powering-generative-ai snippets).
Make.com / Zapier / n8n / Google / Microsoft 365 / claude CLI accounts — not provided (needed for the no-code and spreadsheet pages).
curl https://api.context.dev/v1/brand/retrieve -H 'Authorization: Bearer …' -d '{"domain":"stripe.com"}' returns HTTP 403 "The API you have tried to access does not exist." — -d makes the request POST, but the endpoint only accepts GET (a keyless GET on the same path returns the documented 401 Unauthorized). Suggested fix in docs:curl "https://api.context.dev/v1/brand/retrieve?domain=stripe.com" -H "Authorization: Bearer YOUR_API_KEY" (drop -d and Content-Type, switch to query string). Not applied.
2
typescript
SKIP
Basic SDK retrieve — API key DISABLED.
3
typescript
SKIP
dotenv/config env-setup fragment — partial fragment; depends on .env.
4
typescript
SKIP
fetchBrandWithRetry retry helper — partial fragment (uses outer client).
5
typescript
SKIP
Backend-proxy POST route handler — partial fragment, requires Next.js host.
6
python
SKIP
Basic retrieve — runtime unavailable.
7
python
SKIP
dotenv env setup — runtime unavailable.
8
ruby
SKIP
Basic retrieve — runtime unavailable.
9
ruby
SKIP
dotenv/load env setup — runtime unavailable.
10
bash
SKIP
Vercel/Heroku/Docker env-add commands — external services / no auth context.
client.utility.prefetchByDomain({ domain: 'acme.com' }) → TypeError: client.utility.prefetchByDomain is not a function. SDK exposes client.utility.prefetch({ domain }). Suggested fix in docs: rename the call to prefetch. Not applied.
client.brand.identifyTransaction({ transaction, mcc, city, country_gl }) → TypeError: client.brand.identifyTransaction is not a function. SDK exposes client.brand.identifyFromTransaction(...). Suggested fix in docs: rename to identifyFromTransaction. Not applied.
2
typescript
SKIP
displayTransaction formatter — partial fragment, depends on cleanTransactionTitle/getCategoryIcon.
3
typescript
SKIP
enrichTransaction cache wrapper — partial fragment; also wraps the broken identifyTransaction call.
HTTP-module config object parses as valid JSON. (Note: page documents "method":"POST" but the live /v1/brand/retrieve endpoint only accepts GET — same underlying issue as the Authentication curl. JSON syntax is valid.)
5
json
PASS
{"domain":"{{1.domain}}"} body parses as valid JSON.
https://logos.context.dev/?publicClientId=brandLL_xxx&domain=github.com — placeholder ID; live request returns 401 Invalid publicClientId. Real brandLL_… not provided.
2
html
SKIP
<img src=…brandLL_xxx…> — placeholder ID; same auth issue, also requires browser.
3
javascript
SKIP
fetch() example — placeholder ID, also needs DOM (document.getElementById).