Context.dev

View saved version →

---
name: context-build
description: Integrate Context.dev into application, agent, backend, or workflow code that needs live web search, company news, page scraping, crawling, structured extraction, document parsing, brand intelligence, screenshots, monitoring, or large batch jobs. Use when the user is building a product feature that needs web or file data, even if they describe the desired feature without naming Context.dev. Do not use for a one-off lookup or scrape performed only for the current conversation.
---

# Context Build

Add the smallest correct Context.dev integration to the user's existing application and verify it in the project's own stack.

## Workflow

1. Inspect the repository before choosing an implementation.
   - Identify the runtime, framework, package manager, server boundary, test runner, and existing API-client conventions.
   - Reuse the project's configuration, validation, logging, and error-handling patterns.
   - Keep Context calls on the server. Never expose the API key in browser or mobile client code.

2. Read [API routing](references/api-routing.md) and choose the narrowest capability that matches the feature.
   - Prefer search when the source URL is unknown.
   - Prefer a single-page scrape when the URL is known.
   - Prefer crawl for a focused set of linked pages and sitemap for URL discovery only.
   - Prefer extract when the output must follow a JSON schema.
   - Prefer News for company-specific stories and Web Search for broader topics.
   - Use batches only for genuinely large asynchronous work and monitors only for recurring change detection.

3. Use the official Context SDK when it supports the project language and capability. Use the REST API only when the SDK is unavailable or the repository already standardizes on raw HTTP.
   - Use `CONTEXT_DEV_API_KEY` as the environment variable.
   - Add the variable to an example environment file without a value when the repository uses one.
   - Never hardcode, print, commit, or return the secret.
   - Use `https://api.context.dev/v1` as the REST base URL.

4. Implement the smallest complete integration.
   - Add a thin server-side client or service instead of scattering calls through UI code.
   - Validate user-controlled URLs, schemas, filters, limits, and file sizes before sending requests.
   - Preserve source URLs and relevant metadata in returned application data.
   - Add timeouts and actionable errors for authentication, insufficient credits, rate limits, upstream failures, and empty results.
   - Retry only safe transient failures. Use an idempotency key when retrying batch submission.
   - Keep response payloads bounded with explicit limits or pagination.

5. Treat side effects and cost explicitly.
   - Confirm intent before creating or changing a recurring monitor, configuring a webhook, or submitting a large batch.
   - Do not start a large batch merely to demonstrate that the integration works.
   - Poll asynchronous work with a bounded interval and terminal timeout; do not busy-loop.

6. Verify the actual feature path.
   - Run the repository's formatter, typecheck, and relevant tests.
   - If `CONTEXT_DEV_API_KEY` is available, run one small representative live request through the application's integration boundary.
   - If it is unavailable, add a mocked contract test and provide the exact command the user can run after setting it.
   - Check that no secret or sensitive response data appears in logs, generated files, or client bundles.

## Completion

Report:

- the feature and Context capability added
- the files changed
- the required environment variable
- the checks and live request that passed
- any remaining setup the user must complete

Do not claim live validation if only mocked tests ran.

Referenced files: 2

View saved version →

---
name: context-dev
description: "Use Context.dev for tasks that need live public-web or document data: web search; scraping known URLs to Markdown, HTML, or images; sitemap discovery and crawling; schema-based extraction; PDF and Office parsing; company logos, colors, socials, and industry; website style guides, fonts, screenshots, monitoring, or large URL batches. Trigger even when Context.dev is not named. Do not trigger for questions answerable from supplied text, private account data, or tasks that need no web or file retrieval."
---

# Context.dev

Use the connected Context.dev tools to retrieve current public web and file data. Prefer the smallest tool that directly produces the requested result.

## Choose the right tool

- Use `web-search` when the user needs current information and does not provide the exact source URL.
- Use `web-scrape-markdown` to read, summarize, or analyze one known URL.
- Use `web-scrape-html` only when raw DOM structure, attributes, scripts, or markup are required.
- Use `web-scrape-images` to discover image assets and `web-screenshot` for a rendered page image.
- Use `web-scrape-sitemap` to discover or search a site's URLs without fetching every page body.
- Use `web-crawl` for a focused set of linked pages when results are needed synchronously.
- Use `web-extract` when the user wants structured fields such as products, pricing, jobs, locations, or company facts.
- Use `parse-document` for PDFs, presentations, spreadsheets, documents, images, code, data, and text files.
- Use `get-brand` for a visual brand profile from a domain. Use `brand-retrieve-unified` for raw structured brand data or lookups by name, email, ticker, ISIN, transaction descriptor, or direct URL.
- Use `web-styleguide` and `web-fonts` to inspect a site's visual system and typography.
- Use `web-naics` or `web-sic` for industry classification.
- Use the monitor tools for recurring change detection. Use the batch tools for large asynchronous jobs or many URLs.

## Work effectively

1. When the exact URL is known, use the corresponding scrape or extract tool instead of searching first.
2. For current facts, use live web tools and retain the source URLs in the answer.
3. For structured extraction, define the narrowest schema that matches the user's requested fields. Do not invent missing values.
4. For large jobs, call `submit-batch`, then use `get-batch` and `get-batch-results`. A successful submission is not a completed job.
5. For monitor requests, inspect existing monitors when useful and confirm the intended target, schedule, and change criteria before creating or changing one.
6. Treat browser actions, monitor mutations, and batch mutations as side-effectful. Only perform them when the user has clearly requested that action.
7. If authentication fails, tell the user to connect or reconnect Context.dev through OAuth. Do not fabricate results or silently substitute stale data.

## Match common requests

Invoke Context.dev for requests such as:

- "find the latest official announcements about this company"
- "summarize this page" or "turn this URL into Markdown"
- "extract every pricing plan as JSON"
- "parse this research paper or presentation"
- "get this company's logo, colors, socials, and industry"
- "find all documentation pages about authentication"
- "watch this page for meaningful pricing changes"
- "scrape these hundreds of URLs and give me the results"

Do not invoke Context.dev when the answer is already present in user-provided content, the task concerns private workspace data from another connected service, or no public web or file retrieval is required.

Referenced files: 1