Quickstart - Context.dev

By the end of this guide you’ll have an API key, an installed SDK, and your first call to Context.dev’s Brand, Web, and Classification API endpoints.

Integrate Context.dev into my app

Open in Cursor

0. Pick the right API for your job

Context.dev has 4 products:

API	Use-case
Brand APIs	Look up a brand by name, domain, email, stock ticker, or ISIN
Brand APIs	Extract a website’s styleguide: fonts, spacing, shadows, etc.
Logo Link CDN	Get embeddable logo images from a domain
Web APIs	Scrape any websiteinto clean HTML/Markdown
	Crawl a whole siteand get clean Markdown for every page
	Crawl a sitemapto discover all URLs of a domain
	Extract every imageon a webpage
	Capture a webpage screenshot
	Extract product details(name, price, features) from a page
	Extract structured datafrom a website’s pages with a JSON Schema
Classification APIs	Enrich a card-transaction descriptorto a brand
Classification APIs	Classify a brand into NAICS, SIC, or EIC industry codes

1. Get an API key

Create an account at context.dev/signup.

Copy your key from the dashboard

Open the dashboard and copy the key from the “API Keys” section. It starts with ctxt_secret_.

API Keys section in the Context.dev dashboard

Expose it as an environment variable

The SDKs and curl examples read CONTEXT_DEV_API_KEY from the environment. The SDKs read CONTEXT_DEV_API_KEY first and fall back to CONTEXT_API_KEY if it isn’t set, so exporting CONTEXT_DEV_API_KEY alone is enough:

terminal

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

For local development, save the key to a .env file and make sure it’s listed in your .gitignore. For deployment, set the key in your platform’s environment variable store:

Vercel: vercel env add CONTEXT_DEV_API_KEY
Heroku: heroku config:set CONTEXT_DEV_API_KEY=ctxt_secret_...
Docker: pass via -e CONTEXT_DEV_API_KEY=ctxt_secret_... at docker run
AWS Lambda: store in Secrets Manager or Parameter Store; expose to the function via its environment config

Never call the Context.dev API directly from a browser. The key would be visible to anyone with devtools. Always proxy through your backend.

2. Install an SDK

Context.dev publishes official SDKs for TypeScript, Python, Ruby, and Go. Pick the one for your stack.

npm install context.dev

You can also call the API directly with curl. No install required.

3. Make your first call

All code snippets expect CONTEXT_DEV_API_KEY to be set. Depending on which API you chose:

Brand API
Web API
Classification APIs

Retrieving a brand requires a brand identifier (name, domain, email, stock ticker, or ISIN code) and gives you its logo, name, slogan, description, address, social media handles, and more.Read the full guide

curl -G https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "domain=airbnb.com"

10 credits per successful call

With Context.dev’s Web APIs, you can:

Scrape clean HTML/Markdown from URLs
Extract structured data from a website by passing a JSON Schema.
Extract every image on a page
Capture webpage screenshots
Crawl a sitemap to discover all URLs of a domain
Crawl an entire website into per-page Markdown
Pull a website’s styleguide: fonts, typography, spacing, shadows, components, and colors
Extract product details (name, price, features) from a product page.

Looking for embeddable logos? That’s Logo Link, Context.dev’s separate CDN product. It embeds a logo for any domain with one src URL, no API call required.For this quickstart, let’s use the webpage scraping endpoint. Pass in any URL and it returns clean, LLM-ready Markdown:

curl -G https://api.context.dev/v1/web/scrape/markdown \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "url=https://airbnb.com"

1 credit per successful call

With Context.dev’s Classification APIs, you can:

Get brand details from a card transaction descriptor
Classify a brand into NAICS industry codes (2022 NAICS hierarchy)
Classify a brand into SIC industry codes (1987 SIC or SEC EDGAR)
Read EIC industries (Context.dev’s own taxonomy). There’s no dedicated EIC endpoint; EIC ships inline under industries.eic on every full brand response at no extra cost

For this quickstart, let’s use the transaction identifier endpoint. Pass in a card transaction descriptor and it returns the resolved brand record:

curl -G https://api.context.dev/v1/brand/transaction_identifier \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "transaction_info=STARBUCKS STORE 12345" \
  --data-urlencode "country_gl=us"

10 credits per successful call

4. Understand the response

Brand and Classification endpoints return JSON with status, code, and a brand object. The Web Markdown endpoint returns success, url, and markdown.

Brand API
Web API
Classification APIs

Calling /brand/retrieve with domain=airbnb.com returns the brand record for Airbnb.

brand.retrieve response

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "airbnb.com",
    "title": "Airbnb",
    "description": "Airbnb is a global online community marketplace that connects hosts with guests...",
    "slogan": "Belong Anywhere",
    "colors": [
      { "hex": "#fc3c5c", "name": "Radical Red" },
      { "hex": "#fc9cb4", "name": "Saira Red" },
      { "hex": "#fb5c74", "name": "Ponceau" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/4ae9a10b-ffde-45c8-b5c1-c1e7cef5b716.png",
        "mode": "light",
        "type": "icon",
        "colors": [{ "hex": "#fc3c5c", "name": "Radical Red" }],
        "resolution": { "width": 250, "height": 250, "aspect_ratio": 1 }
      }
    ],
    "backdrops": [
      {
        "url": "https://media.brand.dev/example-backdrop.png",
        "colors": [{ "hex": "#fc3c5c", "name": "Radical Red" }],
        "resolution": { "width": 1200, "height": 630, "aspect_ratio": 1.9 }
      }
    ],
    "address": {
      "street": "888 Brannan Street",
      "city": "San Francisco",
      "state_province": "California",
      "state_code": "CA",
      "country": "United States",
      "country_code": "US",
      "postal_code": "94103"
    },
    "socials": [
      { "type": "x",         "url": "https://x.com/airbnb" },
      { "type": "facebook",  "url": "https://facebook.com/airbnb" },
      { "type": "linkedin",  "url": "https://linkedin.com/company/airbnb" },
      { "type": "instagram", "url": "https://instagram.com/airbnb" }
    ],
    "stock": { "ticker": "ABNB", "exchange": "NASDAQ" },
    "phone": "+1-415-555-0100",
    "is_nsfw": false,
    "industries": {
      "eic": [
        { "industry": "Hospitality & Tourism", "subindustry": "Vacation Rentals & Short-Term Stays" },
        { "industry": "Technology",            "subindustry": "eCommerce & Marketplace Platforms" }
      ]
    },
    "links": { "blog": null, "careers": null, "privacy": null, "terms": null, "contact": null, "pricing": null },
    "primary_language": "english"
  }
}

Field	Type	Description
`brand.title`	string	Company name.
`brand.domain`	string	Canonical domain.
`brand.description`	string	Brief description of the brand.
`brand.slogan`	string	The brand’s slogan.
`brand.colors[]`	array	Brand colors. Each has `hex` and `name`.
`brand.logos[]`	array	Logos associated with the brand. Each has `url`, `mode` (`light`, `dark`, `has_opaque_background`), `type` (`icon`, `logo`), `colors[]`, and `resolution`.
`brand.backdrops[]`	array	Backdrop images for the brand. Each has `url`, `colors[]`, and `resolution`.
`brand.address`	object	`street`, `city`, `state_province`, `state_code`, `country`, `country_code`, `postal_code`.
`brand.socials[]`	array	Social profile URLs. Each has `type` (`x`, `facebook`, `linkedin`, `instagram`, …) and `url`.
`brand.stock`	object	`ticker` and `exchange`. `null` for private companies.
`brand.phone`	string	Company phone number.
`brand.is_nsfw`	boolean	Indicates whether the brand content is not safe for work (NSFW).
`brand.industries.eic[]`	array	Easy Industry Classification industry and subindustry pairs.
`brand.links`	object	Important website links (`careers`, `privacy`, `terms`, `contact`, `blog`, `pricing`); fields may be `null` when not found.
`brand.primary_language`	string	Primary language of the brand’s website content, or `null` when not detected.

Calling /web/scrape/markdown with url=https://airbnb.com returns clean Markdown:

webScrapeMd response

{
  "success": true,
  "url": "https://airbnb.com",
  "markdown": "[Skip to content](https://airbnb.com/#site-content)\n\n# Airbnb homepage\n\n[HomesHomes](https://airbnb.com/homes) [ExperiencesExperiences, new](https://airbnb.com/experiences) [ServicesServices, new](https://airbnb.com/services)\n\nWhere\n\nWhen\n\nAdd dates\n\nWho\n\nAdd guests\n\n[Become a host](https://airbnb.com/#guest-header-become-a-host-menu)\n\n[Help Center](https://airbnb.com/help)\n\n..."
}

Field	Type	Description
`success`	boolean	Indicates success. On a successful response this is always `true`.
`url`	string	The URL that was scraped.
`markdown`	string	Page content converted to GitHub Flavored Markdown.

Calling /brand/transaction_identifier with transaction_info=STARBUCKS STORE 12345&country_gl=us resolves the descriptor and returns the brand record for Starbucks:

brand.transaction_identifier response

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "starbucks.com",
    "title": "Starbucks",
    "description": "Starbucks is a global coffee company that puts people at the heart of its business...",
    "slogan": "Inspiring and nurturing the human spirit — one person, one cup",
    "colors": [
      { "hex": "#0bac66", "name": "Secret Garden" },
      { "hex": "#7cd4b4", "name": "Seafoam Blue" },
      { "hex": "#307e63", "name": "Trans Tasman" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/67dc7846-2ca2-4a7b-9877-6bb5a5e2c0e0.png",
        "mode": "has_opaque_background",
        "type": "icon",
        "colors": [
          { "hex": "#0bac66", "name": "Secret Garden" },
          { "hex": "#7cd4b4", "name": "Seafoam Blue" }
        ],
        "resolution": { "width": 180, "height": 180, "aspect_ratio": 1 }
      }
    ],
    "industries": {
      "eic": [
        { "industry": "Hospitality & Tourism", "subindustry": "Cafes & Coffee Shops" }
      ]
    },
    "socials": [
      { "type": "x", "url": "https://x.com/starbucks" },
      { "type": "instagram", "url": "https://instagram.com/starbucks" }
    ],
    "stock": { "ticker": "SBUX", "exchange": "NASDAQ" }
  }
}

Field	Type	Description
`status`	string	`"ok"` on a confident match; `"error"` when not identified.
`code`	number	HTTP status mirror. `400` with `error_code: "NOT_FOUND"` when the descriptor can’t be resolved.
`brand.*`	object	Identical shape to `/brand/retrieve`; see the Brand API tab above for the full field reference.

Pass mcc, city, and country_gl for higher confidence on ambiguous descriptors.

5. Handle errors

A non-2xx response returns an error envelope. The common ones:

Status	Meaning	What to do
401	API key missing, invalid, or deleted	Re-check the env var and the dashboard.
408	Cold-hit timeout (rare; first crawl exceeded the deadline)	Retry once; the second hit is warm. Better: prefetch.
422	Disposable or free-email address on `retrieve-by-email`	Skip the call for personal addresses.
429	Rate limit	Wait per the `Retry-After` header; see Handle Rate Limits.
500	Transient server error	Retry once with backoff; if it persists, contact support.

A retry pattern that covers 408 and 429:

import ContextDev from "context.dev";

const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });

async function retrieveWithRetry(domain: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const { brand } = await client.brand.retrieve({ domain });
      return brand;
    } catch (err: any) {
      const retryable = err.status === 408 || err.status === 429;
      if (retryable && i < maxRetries - 1) {
        await new Promise((r) => setTimeout(r, 2 ** i * 1000));
        continue;
      }
      throw err;
    }
  }
  throw new Error("unreachable");
}

For the full catalog of error codes and remediations, see Troubleshooting.

Next steps

Prefetch for Faster Response

Hide cold-hit latency from your users.

Handle Rate Limits

Backoff strategies, client cache, and prefetch fallbacks.

Best Practices

Caching, error handling, and key hygiene.

Troubleshooting

Status codes, retry patterns, and common errors.

​0. Pick the right API for your job

​1. Get an API key

​2. Install an SDK

​3. Make your first call

​4. Understand the response

​5. Handle errors

​Next steps