> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the foundational concepts behind Context.dev's APIs

## Overview

Context.dev provides multiple APIs for extracting structured data from the web. The Brand API is the core data model, with additional APIs for web scraping, AI-powered extraction, screenshots, and styleguide analysis.

## The Brand Data Model

When you request brand data for a domain, Context.dev returns a comprehensive object containing:

### Brand Assets

* **Logos** - Multiple variants (icon, full logo, light mode, dark mode, transparent, opaque)
* **Colors** - Brand color palette with hex codes and human-readable names
* **Backdrops** - Background images and hero graphics

### Company Information

* **Basic Details** - Company name, description, slogan
* **Contact Info** - Address, phone number
* **Social Links** - X, LinkedIn, Facebook, YouTube profiles
* **Links** - Careers page, blog, pricing, terms, privacy policy

### Business Context

* **Industries** - Industry classifications (EIC codes)
* **Financial** - Stock ticker information (for public companies)
* **NAICS Codes** - North American Industry Classification System codes

## Understanding Logo Types

Context.dev provides different logo variants to suit different use cases:

### Logo Type: `icon` vs `logo`

* **`icon`** - Square or near-square logos, perfect for avatars and app icons (aspect ratio \~1:1)
* **`logo`** - Horizontal logos, ideal for navigation bars and headers (aspect ratio >2:1)

### Logo Mode: Light, Dark, and Transparency

* **`light`** - Transparent logo designed for light backgrounds (dark text/graphics)
* **`dark`** - Transparent logo designed for dark backgrounds (light text/graphics)
* **`has_opaque_background`** - Logo includes its own background color

<Tip>
  **Pro tip:** For navigation bars, look for logos with `type: "logo"`, `mode: "light"`, and `aspect_ratio > 2`. For user avatars, look for `type: "icon"` with `aspect_ratio` close to 1.
</Tip>

## Color Extraction

Context.dev extracts brand colors from verified sources and provides them in a structured format:

```json theme={null}
{
  "hex": "#655ef3",
  "name": "Blue Hepatica"
}
```

Colors are typically ordered by importance, with the primary brand color first. Each color includes a human-readable name to help you understand its semantic meaning.

<Warning>
  The color names are generated using a color-naming algorithm and may not
  always match official brand terminology.
</Warning>

## Data Freshness & Caching

<Info>Context.dev will only cache brand data for 3 months at most.</Info>

Context.dev uses intelligent caching to provide fast responses while keeping data fresh:

### Response Times

* **Warm hits (cached)** - \~250ms p50 latency
* **Cold hits (new domain)** - \~7 seconds p50 latency (first request)

### Cache Strategy

When you request a domain for the first time, Context.dev:

1. Checks the cache for existing data
2. If not cached, crawls verified sources in real-time
3. Extracts and structures the brand data
4. Stores the result for fast subsequent requests

### Prefetching

Use the [Prefetch by Email endpoint](/api-reference/utility/prefetch-brand-data-by-email) to warm the cache before the user needs the data:

```typescript theme={null}
// Prefetch when user enters email (doesn't count against credits)
await client.utility.prefetchByEmail({
  email: "john@acme.com",
});

// Later, retrieve is fast (~250ms)
const { brand } = await client.brand.retrieve({
  domain: "acme.com",
});
```

## Data Sources & Verification

Context.dev aggregates data from multiple verified sources to ensure accuracy:

* Official company websites
* Social media profiles (verified accounts)
* Business registries and databases
* Public company filings (for financial data)

All data is cleaned, standardized, and validated before being returned through the API.

## API Response Structure

Every Context.dev API response follows a consistent structure:

```json theme={null}
{
  "status": "ok",
  "brand": {
    // Brand data object
  },
  "code": 200
}
```

* **`status`** - Always `"ok"` for successful requests
* **`brand`** - The complete brand data object
* **`code`** - HTTP status code (200 for success)

## Error Handling

When a request fails, Context.dev returns structured error information:

```json theme={null}
{
  "status": "error",
  "message": "Brand not found for domain",
  "code": 404
}
```

Common error codes:

* **404** - Brand not found
* **401** - Invalid API key
* **429** - Rate limit exceeded
* **422** - Invalid parameters (e.g., disposable email)

<Card title="Error Handling Guide" icon="triangle-exclamation" href="/guides/get-started/troubleshooting">
  Learn how to handle errors gracefully
</Card>

## Rate Limits

Context.dev implements rate limits to ensure fair usage and system stability. Rate limits vary by plan tier and are measured in requests per minute.

When you exceed your rate limit, you'll receive a `429` status code with a `Retry-After` header indicating when you can retry.

<Note>
  The Prefetch by Email endpoint does not count against your rate limits or
  credit usage.
</Note>

## Best Practices

### 1. Cache Client-Side

Store brand data in your application cache to avoid repeated API calls:

```typescript theme={null}
// Cache brand data for 24 hours
const CACHE_TTL = 24 * 60 * 60 * 1000;
const cache = new Map();

async function getBrandWithCache(domain: string) {
  const cached = cache.get(domain);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const { brand } = await client.brand.retrieve({ domain });
  cache.set(domain, { data: brand, timestamp: Date.now() });
  return brand;
}
```

### 2. Handle Missing Data Gracefully

Not all brands have all data fields. Always provide fallbacks:

```typescript theme={null}
const logo = brand.logos[0]?.url || "/placeholder-logo.svg";
const primaryColor = brand.colors[0]?.hex || "#000000";
```

### 3. Use Prefetching for Better UX

Prefetch brand data as soon as you know the domain (e.g., when user types email):

```typescript theme={null}
async function handleEmailChange(email: string) {
  if (email.includes("@")) {
    // Fire and forget - prefetch in background
    client.utility.prefetchByEmail({ email }).catch(() => {});
  }
}
```

## Web Scraping

Context.dev provides web scraping endpoints that return clean, structured content from any URL:

* **HTML Scraping** - Raw HTML content with automatic proxy escalation
* **Markdown Conversion** - HTML-to-markdown with options for links and images
* **Image Extraction** - All images from a page including inline SVGs and data URIs
* **Sitemap Crawling** - Discover all page URLs from a domain's sitemap (up to 500)

These endpoints are ideal for building AI pipelines, content analysis tools, and data extraction workflows.

## AI-Powered Extraction

Context.dev uses AI to extract structured data from websites:

* **Product Extraction** - Extract product names, pricing, features, and categories from any company's website
* **AI Query** - Ask natural language questions about any website and get structured answers
* **Single Product Extraction** - Determine if a URL is a product page and extract structured product data

## Screenshots & Styleguides

* **Screenshot API** - Capture high-quality viewport or full-page screenshots of any website
* **Styleguide API** - Extract comprehensive design systems including typography, spacing, shadows, and component styles

## Related Resources

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/guides/get-started/quickstart">
    Get started in 5 minutes
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all endpoints
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/guides/use-cases/onboarding-flows">
    See real-world examples
  </Card>
</CardGroup>