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 when a task needs current public-web, company-news, website, or document data, or when the user wants to inspect their Context.dev API request logs. Search or research the live web; read, scrape, crawl, or screenshot sites; extract structured data; parse documents; retrieve brand or people intelligence; monitor changes; or process large batches. Trigger even when Context.dev is not named. Do not trigger when supplied content already contains the answer or no web, file, or Context.dev account data is needed.
---

# Context.dev

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

## Choose the right tool

- Use `get-news-search` for current, verified news about one company.
- Use `web-search` for ranked live-web results. Enable `highlightsOptions` for relevant source passages or `markdownOptions` for complete page content. Use `web-answers` for a sourced answer in a requested JSON shape.
- Use `web-scrape` for one known page. Request only the needed outputs with `formats`, such as `{ markdown: true }`, `{ screenshot: true }`, or `{ json: true }` with `jsonParams.schema`.
- Use `web-map` to discover or filter a site's URLs without downloading every page body.
- Use `web-crawl` for a focused set of linked pages when the result is needed synchronously.
- Use `parse-document` for PDFs, presentations, spreadsheets, documents, images, code, data, and text files.
- Use `get-brand` for a visual brand profile. Use `brand-retrieve-unified` for raw structured brand data or alternative company identifiers.
- Use `brand-search` to find a company, `web-styleguide` for its visual system and typography, and `people-enrich` for a person profile.
- Use `list-logs` to find recent Context.dev API requests and `get-log` for one request's redacted input, response, timing, credits, and error details.
- Use monitor tools for recurring change detection, webhook tools for delivery troubleshooting, and batch tools for large asynchronous jobs.
- Use `submit-feedback` to report a Context.dev bug, documentation mismatch, or agent friction when requested.

## Work effectively

1. When the exact URL is known, use `web-scrape` directly instead of searching first.
2. For current facts, use live tools and include the supporting source URLs in the response.
3. For structured extraction, request only the fields the user needs and never invent missing values.
4. For large jobs, call `submit-batch`, then check `get-batch` and `get-batch-results`. Submission does not mean completion.
5. Before creating or changing a monitor, confirm the intended target, schedule, and change criteria.
6. Treat browser actions, monitor or batch mutations, webhook retries or secret rotation, and feedback submission as side-effectful. Perform them only when clearly requested.
7. If authentication fails, ask the user to connect or reconnect Context.dev through OAuth. Never fabricate results or silently substitute stale data.

## Common requests

- Find a company's latest official announcements and cite the sources.
- Research a current question and return a sourced JSON answer.
- Turn a known page into clean Markdown.
- Extract every pricing plan into structured JSON.
- Parse a research paper, spreadsheet, or presentation.
- Retrieve a company's logo, colors, socials, and industry.
- Diagnose a failed Context.dev request from recent API logs.
- Find all documentation pages about a feature.
- Monitor a page for meaningful pricing changes.
- Process hundreds or thousands of URLs asynchronously.

Referenced files: 1