Context.dev

Context.dev turns any domain or URL into structured, typed JSON: brand profiles, design systems, scraped content, extracted products, industry codes, and merchant identity. Base URL https://api.context.dev/v1. Full docs: docs.context.dev · machine index: docs.context.dev/llms.txt.

Every endpoint takes one bearer token and returns typed JSON. No HTML parsing, no Open Graph scraping. This file tells you which endpoint answers which question, exactly what each takes, and exactly what each gives back.

Setup

Authenticate with a bearer token read from CONTEXTDEVAPI_KEY. Never hardcode it; never ship it to client-side code (use a backend proxy).

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

Install an SDK, or call REST directly with curl:

import ContextDev from "context.dev";
const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });
const { brand } = await client.brand.retrieve({ type: "by_domain", domain: "stripe.com" });

SDK naming. Methods below are shown in TypeScript camelCase (client.brand.retrieve). Python and Ruby use snakecase (retrieve); PHP uses the same camelCase method names as TypeScript with named parameters ($client->brand->retrieve(type: 'bydomain', domain: 'stripe.com')); Go uses PascalCase and renames a few (client.Brand.Get, client.Industry.GetNaics). Methods are grouped under five namespaces that don't always match the URL path: brand., web., ai., industry. (NAICS/SIC, despite /web/ paths), utility.* (prefetch). Styleguide and font extraction are under client.web in every current SDK. See best practices.

Choosing an endpoint

Pick the narrowest endpoint that answers the question. Start from what you already have:

Prefer bare domains: use stripe.com instead of https://stripe.com or www.stripe.com. The API normalizes protocol and www., but a string with no TLD fails validation.

Brand intelligence

Brand lookups share the same response envelope: { status, code, brand }. They cost 10 credits each and only bill on a successful resolution (a 400 NOT_FOUND "no brand" response is free). Guide: Get brand data.

The brand object (shared response shape)

This is what brand contains on Brand responses from POST /brand/retrieve, including domain, name, email, ticker, direct URL, and transaction lookups. Any field may be null/absent, so always provide fallbacks.

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "stripe.com",
    "title": "Stripe",
    "colors": [{ "hex": "#543cfb", "name": "Meteor Shower" }],
    "logos": [
      {
        "url": "https://media.brand.dev/….svg",
        "mode": "light",
        "type": "logo",
        "resolution": { "width": 150, "height": 48, "aspect_ratio": 3.13 }
      }
    ],
    "industries": {
      "eic": [
        { "industry": "Finance", "subindustry": "Payments & Money Movement" }
      ]
    },
    "stock": null
  }
}

Retrieve brand by domain

POST /brand/retrieve with type: "by_domain" · 10 credits · SDK client.brand.retrieve (Go Brand.Get) Guide · API reference

• When: you have the company's website domain and want the full profile (logos, colors, socials, address, industry, stock).
• Takes (JSON body): type: "bydomain" (required discriminator), domain (string, required, bare domain). Optional: maxSpeed (bool; skip slow steps for a faster, lighter answer), forcelanguage (SupportedLanguage enum), maxAgeMs (int, default 7776000000 ≈ 90d, clamped 1d–1y), timeoutMS (int, max 300000).
• Gives: the shared { status, code, brand } envelope above.

Retrieve by company name

POST /brand/retrieve with type: "by_name" · 10 credits · SDK client.brand.retrieve (Go Brand.Get) Guide · API reference

• When: you only know the company name and need Context to resolve it to a domain + full profile.
• Takes (JSON body): type: "byname" (required), name (string, required, 3–30 chars). Optional: countrygl (ISO 3166-1 alpha-2 hint to disambiguate, e.g. us), maxSpeed, force_language, maxAgeMs, timeoutMS.
• Gives: the full shared brand envelope.

Retrieve by work email

POST /brand/retrieve with type: "by_email" · 10 credits · SDK client.brand.retrieve (Go Brand.Get) Guide · API reference

• When: lead/onboarding enrichment from a work email; the domain is extracted automatically.
• Takes (JSON body): type: "byemail" (required), email (string, required). Optional: maxSpeed, forcelanguage, maxAgeMs, timeoutMS.
• Gives: the full shared brand envelope.
• Note: free providers (gmail, outlook…) and disposable addresses return HTTP 422 (FREEEMAILDETECTED / DISPOSABLEEMAILDETECTED); handle 422 as "skip enrichment", not a hard error.

Retrieve by ticker

POST /brand/retrieve with type: "by_ticker" · 10 credits · SDK client.brand.retrieve (Go Brand.Get) Guide · API reference

• When: investor/finance flows keyed on a listed ticker.
• Takes (JSON body): type: "byticker" (required), ticker (string, required, 1–15 chars, e.g. AAPL, BRK.A). Optional tickerexchange (defaults to NASDAQ; set it for non-NASDAQ listings), plus maxSpeed/force_language/maxAgeMs/timeoutMS.
• Gives: the full shared brand envelope, with brand.stock populated.

Transaction enrichment

POST /brand/retrieve with type: "by_transaction" · 10 credits · SDK client.brand.retrieve Guide · API reference

• When: you have a messy card/ACH descriptor (AMZN MKTP US, SQ *COFFEE BAR) and need the real merchant brand for spend analytics or categorization.
• Takes (JSON body): type: "bytransaction" (required), transactioninfo (string, required). Optional disambiguators sharply improve accuracy: mcc (4-digit category code), city, countrygl (ISO alpha-2), phone (number), highconfidenceonly (bool, default false; set true for fewer false matches), maxSpeed, forcelanguage, timeoutMS.
• Gives: the full shared brand envelope (the identified merchant).
• Note: this is the only brand lookup that does not accept maxAgeMs.

Retrieve by direct URL

POST /brand/retrieve with type: "bydirecturl" · 10 credits · SDK client.brand.retrieve (Go Brand.Get) Guide · API reference

• When: you want brand fields scraped from one specific page — a subpath, landing page, preview URL, or a domain the database doesn't cover yet. Fetches only that URL; no domain resolution, DB lookup, or cross-source enrichment.
• Takes (JSON body): type: "bydirecturl" (required), directurl (string, required, full http(s) URL). Optional: timeoutMS. Rejects maxSpeed, forcelanguage, and maxAgeMs — those would be silently ignored by the single-page scrape flow.
• Gives: the shared brand envelope, but only fields extractable from the page: domain, title, description, logos (URLs only), socials, email, phone, links. Enrichment-only fields (colors, backdrops, industries, stock, address) are omitted.
• Note: unreachable URLs return 400 WEBSITEACCESSERROR (or WEBSITENOTFOUND when the domain doesn't resolve at all).

Web scraping

Render, crawl, and search the live web. Bot-detection bypass and proxy escalation are automatic. Guide: Scrape websites.

Scrape Markdown

GET /web/scrape/markdown · 1 credit · SDK client.web.webScrapeMd (Go Web.WebScrapeMd) Guide · API reference

• When: turn one page into clean, LLM-ready GitHub-Flavored Markdown (nav/ads stripped). The default for feeding pages to a model.
• Takes: url (string URI, required). Optional: includeLinks (default true), includeImages (default false), shortenBase64Images (default true), useMainContentOnly (default false), includeHTML (default false; adds the source HTML beside the Markdown), includeFrames (default false), includeSelectors[]/excludeSelectors[] (CSS selectors to keep/remove before conversion; exclusion wins), pdf object (shouldParse default true, start/end page range, ocr default false — OCRs scanned pages at 1 credit per recovered page; a scan with ocr off returns 400 PDFIMAGESONLY), maxAgeMs (default 1d, 0–30d), waitForMs (0–30000 render wait), settleAnimations, country, actions[] (up to 5 ordered {do: "wait", timeMs} / {do: "perform", action} steps; paid plan only, 2 credits, bypasses cache), headers object (forwarded to the target URL; bypasses cache), timeoutMS.
• Gives: { success: true, markdown, html?, contentLength, url, metadata }. metadata.headings[] contains { level, text } entries in document order when headings are present.

Scrape HTML

GET /web/scrape/html · 1 credit (2 with actions) · SDK client.web.webScrapeHTML (Go Web.WebScrapeHTML) Guide · API reference

• When: you need the fully-rendered raw HTML (to parse the DOM, attributes, or scripts) instead of cleaned text.
• Takes: url (required), pdf, includeFrames, useMainContentOnly, includeSelectors[]/excludeSelectors[], maxAgeMs, waitForMs, settleAnimations, country, actions[] (paid plan only, 2 credits, bypasses cache; same shape as Scrape Markdown), headers, timeoutMS (same shapes as Scrape Markdown).
• Gives: { success: true, html, url, type, metadata }. metadata.headings[] is present when headings were found.

Scrape Markdown / HTML with actions

Attach actions to /web/scrape/markdown or /web/scrape/html when the page only reveals its content after interaction (cookie banners, "Load more" buttons, tab switches). Up to 5 ordered actions run after page load and before capture. Each is a discriminated object: {do: "wait", timeMs: <0–30000>} or {do: "perform", action: "<natural-language instruction, ≤500 chars>"}. Paid plan required — free-tier keys get 403 PAIDPLANREQUIRED. Any action bumps the call to 2 credits (5 for enriched images) and bypasses the scrape cache and HTML/PDF fast paths.

Scrape Images

GET /web/scrape/images · 1 credit · 2 with actions · 5 if any enrichment flag is set · SDK client.web.webScrapeImages (Go Web.WebScrapeImages) Guide · API reference

• When: enumerate every image on a page (img, inline SVG, CSS backgrounds, video posters, data URIs) and optionally measure / classify / CDN-host them.
• Takes: url (required), maxAgeMs, dedupe (perceptually remove near-duplicates), waitForMs, actions[] (paid plan only, 2 credits, bypasses cache; same shape as Scrape Markdown — enriched calls stay at 5 credits), headers (forwarded to the target URL; bypasses cache), timeoutMS, and an enrichment object: resolution (bool), hostedUrl (bool), classification (bool), maxTimePerMs (int). Enabling any enrichment flag makes the whole call cost 5 credits (not per-image).
• Gives: { success, images[], url }. Each image: { src, element (img|svg|css|background|…), type (url|html|base64), alt|null, enrichment{ width, height, mimetype, url, type(photography|illustration|logo|wordmark|icon|…) } }. The enrichment sub-fields populate only for the flags you requested.

Crawl Sitemap

GET /web/scrape/sitemap · 1 credit (2 with search) · SDK client.web.webScrapeSitemap (Go Web.WebScrapeSitemap) Guide · API reference

• When: discover the URL inventory of a domain (cheap, no page content) before deciding what to scrape or crawl.
• Takes: domain (string, required, bare domain, not a URL). Optional: maxLinks (default 10000, 1–100000), urlRegex (RE2, ≤256 chars, filters which URLs return), search (string, 2–200 chars; filters the crawled sitemap to the pages about that phrase, e.g. pricing and plans, most relevant first — bumps the call to 2 credits), headers (forwarded to the target URL; bypasses cache), timeoutMS.
• Gives: { success, domain, urls[], meta{ sitemapsDiscovered, sitemapsFetched, sitemapsSkipped, errors } }. Returns URLs only; it does not fetch page content despite the "Crawl" name. With search set, urls[] contains only the matching pages, most relevant first.

Crawl Website

POST /web/crawl · 1 credit per page · SDK client.web.webCrawlMd (Go Web.WebCrawlMd) Guide · API reference

• When: traverse a site from a seed URL and collect every page's Markdown in one call, e.g. ingesting a docs site or blog into RAG.
• Takes (JSON body): url (required). Optional: maxPages (default 100, hard cap 500), maxDepth, urlRegex (limit which links to follow), followSubdomains (default false), includeLinks/includeImages/shortenBase64Images/useMainContentOnly, includeSelectors[]/excludeSelectors[], pdf, includeFrames, maxAgeMs, waitForMs, settleAnimations, country, stopAfterMs (soft budget, default 80000, range 10000–110000, returns partial results early), timeoutMS (hard abort).
• Gives: { results[], metadata }. Each result: { markdown, metadata{ url, title, crawlDepth, statusCode, success } }. Top-level metadata: { numUrls, maxCrawlDepth, numSucceeded, numFailed, numSkipped }. Failed pages appear with empty markdown and success: false; skipped URLs are counted but omitted. Billed per page crawled, so set maxPages conservatively.

Web Search

POST /web/search · 1 credit per 10 results · SDK client.web.search (Go Web.Search) Guide · API reference

• When: find relevant pages for a natural-language query across the web (optionally scraping each hit to Markdown in the same round-trip) and you don't already have a URL.
• Takes (JSON body): query (string, required, 1–500 chars). Optional: includeDomains[], excludeDomains[], freshness (last24hours|lastweek|lastmonth|last_year), queryFanout (bool), markdownOptions (off by default; set enabled: true to scrape each result, with the same markdown sub-options as Scrape Markdown), timeoutMS.
• Gives: { results[], query }. Each result: { url, title, description, relevance (high|medium|low), markdown{ markdown|null, code } }. Always check markdown.code first: NOTREQUESTED (scraping off), SUCCESS, TIMEOUT, CONTENTTOOLARGE (result page over the 20 MB cap), WEBSITEACCESS_ERROR, ERROR; only SUCCESS guarantees non-null markdown.

Design system

Extract a site's visual system to reproduce or theme on-brand. XOR rule: pass exactly one of domain or directUrl (omitting both → 400). Guide: Extract a design system.

Styleguide

GET /web/styleguide · 10 credits · SDK client.web.extractStyleguide (Go Web.ExtractStyleguide; Python client.web.extract_styleguide) Guide · API reference

• When: you need the full design system: palette, type scale, spacing, shadows, and paste-ready button/card CSS.
• Takes: domain or directUrl (one required), colorScheme (light|dark; emulates prefers-color-scheme and is included in the cache key), maxAgeMs (default 7776000000 ≈ 90d, clamped 1d–1y), timeoutMS.
• Gives: { status, domain, code, styleguide } where styleguide =

- mode (light|dark) - colors { accent, background, text } (hex) - typography.headings.{h1..h4} and typography.p, each { fontFamily, fontFallbacks[], fontSize, fontWeight, lineHeight, letterSpacing } - elementSpacing { xs, sm, md, lg, xl } - shadows { sm, md, lg, xl, inner } - components.button.{primary,secondary,link} and components.card; each carries a precomputed css string you can paste directly (note card uses textColor, buttons use color) - fontLinks: map of family → { type (google|custom), files{ "400": url, "700": url, … }, category, displayName }; may be {} when no families resolve to downloadable URLs.

Fonts

GET /web/fonts · 5 credits · SDK client.web.extractFonts (Go Web.ExtractFonts; Python client.web.extract_fonts) Guide · API reference

• When: you only need typography: which families a site uses, fallbacks, dominance, and downloadable file URLs.
• Takes: domain or directUrl (one required), maxAgeMs (default 7776000000 ≈ 90d, clamped 1d–1y), timeoutMS.
• Gives: { status, domain, code, fonts[], fontLinks? }. Each font: { font, uses[], fallbacks[], numelements, numwords, percentelements, percentwords } (word % = text volume, element % = DOM coverage; a mono font can dominate elements but carry few words). fontLinks is omitted entirely when nothing resolves.

Screenshots

Capture Screenshot

GET /web/screenshot · 1 credit · SDK client.web.screenshot (Go Web.Screenshot) Guide · API reference

• When: a rendered PNG of a page, for link previews, share cards, or visual archives.
• Takes: domain or directUrl (one required, XOR). Optional: fullScreenshot (string "true"/"false", not a JSON bool), handleCookiePopup (boolean, default false), colorScheme (light|dark), viewport object { width 240–7680 default 1920, height 240–4320 default 1080 }, scrollOffset (integer 0–100000; takes precedence over fullScreenshot), page (enum login|signup|blog|careers|pricing|terms|privacy|contact; auto-finds that page type; only works with domain, ignored with directUrl), country (ISO 3166-1 alpha-2), maxAgeMs, waitForMs (default 3000), timeoutMS.
• Gives: { status, domain, screenshot, screenshotType (viewport|fullPage), width, height, code }. screenshot is a hosted public image URL, not inline bytes.

AI extraction

LLM-backed structured extraction. All 10 credits, POST with JSON body. SDK namespace is client.ai. for the product endpoints and client.web. for structured web extraction (/web/extract).

Extract a single product

POST /brand/ai/product · 10 credits · SDK client.ai.extractProduct (Go AI.ExtractProduct) Guide · API reference

• When: you have one product-page URL and want its structured details.
• Takes: url (string URI, required), maxAgeMs (default 7d, 0–30d), timeoutMS.
• Gives: { isproductpage, platform (amazon|tiktokshop|etsy|generic|null), product|null }. product: { name, description, price|null, currency|null, billingfrequency(monthly|yearly|onetime|usagebased)|null, pricingmodel(perseat|flat|tiered|freemium|custom)|null, url, category|null, features[], targetaudience[], tags[], imageurl|null, images[], sku|null }.
• Note: product and platform can be null even when isproductpage is true, so branch on both. Pages we couldn't reach (blocked, WAF, timeout) and listing/category grids return 400 WEBSITEACCESSERROR — not a silent isproductpage: false.

Extract products from a site

POST /brand/ai/products · 10 credits · Beta · SDK client.ai.extractProducts (Go AI.ExtractProducts) Guide · API reference

• When: discover and extract a brand's product list from its site.
• Takes (JSON body): domain or directUrl (exactly one, XOR; both or neither → 400). Optional maxProducts (1–12), maxAgeMs, timeoutMS. (Ruby: extract_products(body: { domain: … }); Go: OfByDomain.)
• Gives: { products[] }, each product the same shape as /brand/ai/product's product. images[] may be omitted for non-physical products (SaaS).

Structured web extraction

POST /web/extract · 10 credits · SDK client.web.extract (Go Web.Extract) Guide · API reference

• When: extract arbitrary caller-defined data from a site with a JSON Schema. Replaces a scrape-many-pages-then-LLM pipeline.
• Takes (JSON body): url (required) and schema (required). Optional instructions, maxPages (1–50, default 5), maxDepth, factCheck, followSubdomains, pdf, includeFrames, maxAgeMs (default 7d), waitForMs, stopAfterMs (soft crawl budget, default 80000), and timeoutMS.
• Gives: { data, urls_analyzed[], metadata }, where data matches the schema you sent.

Industry classification

Dedicated code lookups. **SDK namespace is client.industry., not web.**, despite the /web/ path. Both 10 credits, GET. Overview: Classification.

NAICS

GET /web/naics · 10 credits · SDK client.industry.retrieveNaics (Go Industry.GetNaics) Guide · API reference

• When: you need 2022 NAICS codes for regulatory reporting or TAM segmentation.
• Takes: input (string, required; a domain is preferred, a free-text name also works), minResults (1–10, default 1), maxResults (1–10, default 5), timeoutMS.
• Gives: { status, domain, type, codes[] }, each code { code, name, confidence (high|medium|low) }.

SIC

GET /web/sic · 10 credits · SDK client.industry.retrieveSic (Go Industry.GetSic) Guide · API reference

• When: SEC filings, tax/accounting, or legacy systems that still speak SIC.
• Takes: input (required), type (originalsic default | latestsec; picks the dataset), minResults/maxResults (1–10), timeoutMS.
• Gives: { status, domain, type, classification, codes[] }. originalsic codes carry majorGroup + majorGroupName; latestsec codes carry office. Each code also has code, name, confidence.

People enrichment

Enrich Person

POST /people/enrich · 20 credits · Beta, paid plans only · SDK client.people.enrich API reference

• When: you have identity clues for a person — a social profile URL, a work email, or a name plus company/education/location — and want one normalized profile with a confidence score.
• Takes (JSON body): any combination of socialurls[] (1–20 profile URLs), name ({ first, last }), email, company ({ name, domain }), education[] ({ institution{name,domain}, degree, fieldofstudy, graduationyear }), location ({ city, region, country }), plus timeoutMS and tags. All supplied clues are considered together — more clues, better match.
• Gives: { match, keymetadata }. match is a discriminated union on status: { status: "candidate", score (0–100), person{ name{full,first,last}, email, avatarurl, bio, location, socialurls[], websiteurls[], currentrole{title, organization{name,domain}, location} } } or { status: "notfound", score: null, person: null }. Branch on match.status and treat low score values as weak matches.
• Note: free-provider and disposable emails return 422 (FREEEMAILDETECTED / DISPOSABLEEMAILDETECTED) before any credits are charged — handle as "skip enrichment". Free-tier keys get 403; every paid plan has access.

Prefetch (cache warming)

0 API credits, ordinary API rate limit, paid-subscriber only (403 FORBIDDEN otherwise). Fire-and-forget: the 200 only confirms that work was queued; it returns no brand or styleguide payload. Guide: Prefetching.

Prefetch brand data or a styleguide

POST /utility/prefetch · 0 credits · SDK client.utility.prefetch (Go Utility.Prefetch) API reference

• When: you know a domain or work email ahead of when you'll need brand data or a website styleguide and want the later read to land on a warm cache.
• Takes: type: "brand" | "styleguide" (required), identifier.domain or identifier.email (exactly one required; both or neither returns 400), timeoutMS. Use brand before /brand/retrieve and styleguide before /web/styleguide. Gives: { status, message, type, domain, key_metadata }.
• Note: email identifiers extract the domain automatically; free/disposable emails return 422 (FREEEMAILDETECTED / DISPOSABLEEMAILDETECTED).

Latency

Warm-cache responses avoid crawl work and are generally faster. A cold lookup may run a full crawl and is bounded by the five-minute platform timeout. If you know the domain/email ahead of time, prefetch it (0 credits, paid subscribers, ordinary RPM applies) so the later retrieve lands warm; otherwise set timeoutMS for your latency budget (up to 300000). Brand prefetch warms /brand/retrieve; styleguide prefetch warms /web/styleguide. It does not affect unrelated web or product-extraction calls. Details: rate limits · best practices.

Errors

Errors carry an error_code; through the SDKs they surface as typed exceptions with the status code (the SDKs do not auto-retry). Common cases:

Full catalog: Troubleshooting.

Gotchas

• Fields are nullable. Logos, colors, stock, phone, links may be absent, so always fall back.
• Pick the right logo. Filter by mode (light/dark/hasopaquebackground) and type (logo horizontal / icon square); don't assume logos[0].
• Color name is generated, not the brand's official name; key off hex.
• Bare domains only (stripe.com), and XOR domain/directUrl on styleguide, fonts, screenshot, and /brand/ai/products.
• Brand data permits cached values up to ~3 months by default. Brand, Styleguide, and Fonts clamp maxAgeMs to 1 day–1 year; scrape endpoints separately support maxAgeMs: 0 for a fresh fetch.
• Logo Link is separate. For high-volume logo embedding in a UI, use https://logos.context.dev/?publicClientId=...&domain=...: a front-end-safe publicClientId, no API key, its own quota. Optional theme=light|dark and type=icon|wordmark query params select theme and shape. See Get logos from a domain.

Reference

• Machine index for agents: docs.context.dev/llms.txt
• Introduction · Brand data · Scraping · Design system · Products · Structured extraction · Transactions · Classification
• Optimization: prefetching · rate limits · best practices · troubleshooting · fair use