agentleFS
context-dot-devcontext-dot-dev/cursor-plugin/skills/context-dev/SKILL.md

context-dev

Skill9 starsChanged 3 months agoMITView on GitHub

Build application code directly against the Context.dev REST API or SDKs with server-side API-key authentication. Use when the user asks to integrate Context.dev into a codebase, choose an SDK method or REST endpoint, debug an API request, or implement a backend Context.dev workflow. For ordinary live-web work inside Cursor, use the focused Context.dev MCP skills instead.

  • Reads credentials

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the bearer token from CONTEXT_DEV_API_KEY.

    line 23
  2. Distinctive:

    Do not use a general scrape when a purpose-built Brand or monitor operation already returns the required shape.

    line 70
  3. Distinctive:

    Do not retry validation, permission, no-match, content-size, or unsupported-media failures unchanged.

    line 176
  4. Distinctive:

    Before declaring an integration complete:

    line 194
  5. Distinctive:

    Keep the API key on the server and prove the missing-key path is intentional.

    line 198
  6. Distinctive:

    Run a focused success test and at least one relevant failure test.

    line 202

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Context.dev integration guide

Context.dev provides web scraping, URL mapping, crawling, web search and research, document parsing, and brand, people, and news data through https://api.context.dev/v1. One Scrape request can return any mix of nine outputs: Markdown, rendered HTML, a screenshot, images, original bytes, CSS-selected fields, highlights, JSON, and product data. Use the public OpenAPI document at docs.context.dev/openapi.json as the authority for paths, methods, parameters, and response fields.

Get access

  • To call Context.dev from this agent session without writing code, connect the MCP server https://mcp.context.dev/mcp. It signs in with OAuth in the user's browser and does not use an API key. Setup for each client: https://docs.context.dev/install-mcp.md
  • Application code and the CLI read an API key from CONTEXT_DEV_API_KEY. If none is configured, follow https://www.context.dev/auth.md: register with the user's email, deliver the returned setup link and code to the user before polling, and store the key in an ignored environment file or secret manager without displaying it. Never ask the user to paste a key into chat.
  • Complete setup instructions: https://docs.context.dev/agent-quickstart.md

Keep credentials server-side

Read the bearer token from CONTEXT_DEV_API_KEY. Never print it, commit it, include it in browser code, or forward it to a target website.

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

curl https://api.context.dev/v1/web/scrape \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "formats": { "markdown": true },
    "sharedParams": { "mainContentOnly": true }
  }'

Route from input to operation

Choose the narrowest operation that directly returns the needed result.

Input and desired resultOperationTask guide
One URL to Markdown or rendered HTMLPOST /web/scrape with formats.markdown or formats.htmlScrape
Known CSS selectors on one page to JSONPOST /web/scrape with formats.parse and parseParams.rulesParse fields
One URL and a question to the most relevant passagesPOST /web/scrape with formats.highlights and highlightsParams.queryHighlights
One URL and a JSON Schema to a structured objectPOST /web/scrape with formats.json and jsonParams.schemaJSON
Exact URL to an inline PNG, JPEG, or WebP screenshotPOST /web/scrape with formats.screenshotScreenshot
URL to image assetsPOST /web/scrape with formats.imagesImages
Resource URL to complete base64 bytesPOST /web/scrape with formats.bytesBytes
Product page to a product record with price, availability, images, and variantsPOST /web/scrape with formats.productProduct
YouTube video URL to metadata and a timestamped transcriptPOST /web/scrape with formats.markdownYouTube
Page that needs clicks, scrolls, or waits before capturePOST /web/scrape with sharedParams.actionsBrowser actions
Domain to its indexed URLs with page titles and descriptionsGET /web/urlsMap URLs
Starting URL to linked pages in one response, up to 500 pagesPOST /web/crawlCrawl
Starting URL or sitemap to a background crawl, up to 25,000 pagesPOST /batch/submit with input.mode: "crawl"Async crawls
URL list to Markdown or HTML in the background, up to 25,000 URLsPOST /batch/submitBatches
Search query to ranked web results, optionally with Markdown or highlightsPOST /web/searchSearch
Research task to structured JSON and source URLsPOST /web/answersAnswers
Uploaded document up to 50 MiB to MarkdownPOST /parseParse
Domain, name, work email, ticker, direct URL, or transaction descriptor to company profilePOST /brand/retrieveBrand
Partial name or domain to matching indexed brandsGET /brand/searchBrand search
Domain or exact URL to design styles, font families, and available font filesGET /web/styleguide; read styleguide.typography and styleguide.fontLinks for fontsStyleguide
Domain or work email known before a Brand or Styleguide requestPOST /utility/prefetchPrefetch
Person email, profile URL, or name plus company, school, or location to a person profilePOST /people/enrich (beta, paid plans)People
Company name, domain, ticker, or ISIN to news articlesPOST /news/searchNews
URL or site to recurring change detection/monitors operationsMonitors
Context.dev bug, docs mismatch, or friction you hit while integratingPOST /feedbackAgent feedback

Do not use a general scrape when a purpose-built Brand or monitor operation already returns the required shape.

Verify the installed SDK before using it

LanguagePackageClient setupScrape and Map URLs
TypeScriptcontext.devnew ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY })client.web.scrape, client.web.mapUrls
Pythoncontext.devContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])client.web.scrape, client.web.map_urls
Rubycontext.devContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))client.web.scrape, client.web.map_urls
Gogithub.com/context-dot-dev/context-go-sdk/v2Use the /v2 module; inspect its generated request model.client.Web.Scrape, client.Web.MapURLs
PHPcontext-dev/context-dev-phpInspect the installed package version and generated method signature.$client->web->scrape, $client->web->mapUrls
  • Go needs the /v2 module path for Web.Scrape, Web.MapURLs, and the current Brand request body.
  • The PHP Brand helper can't express a single lookup type; use the SDK's low-level request method for Brand calls.
  • Published packages can lag the API. If an installed scrape method doesn't accept highlightsParams, jsonParams, or productParams, send the request with the SDK's low-level request method. Do not invent generated types or pass fields the installed signature does not accept.
  • SDKs time out after 60 seconds per attempt (Go has no default timeout) and retry twice on connection errors, 408, 409, 429, and 5xx. Raise the SDK timeout above timeoutOpts.milliseconds for long requests.

For installation, runnable examples, and low-level request methods, read SDKs. For a first request and a trimmed response, read the Quickstart.

Scrape controls

  • formats: enable at least one of html, markdown, screenshot, images, bytes, parse, highlights, json, or product. Outputs share one page visit. Each output has requested, success, and data; success is true when retrieved, false when retrieval fails, and null when not requested. Failed outputs have data: null and do not discard successful outputs. Cost depends on the formats; see the cost table below.
  • maxAgeMs: chooses acceptable cache age. Scrape and both scrape/crawl batches default to three days (259200000 ms) and accept up to 365 days (31536000000 ms). Synchronous Crawl defaults to one day and accepts up to 30 days. Set 0 to fetch fresh and refresh the requested outputs. Each Scrape output has its own cache key, so one response can combine cached outputs from different visits. Brand and Styleguide default to three months, accept 0 for a hard refresh, and clamp values above one year. The direct-URL and transaction Brand variants do not accept this control. Custom headers, actions, and zdr bypass cache reads and writes; otherwise inspect cache_metadata.status (hit, miss, or zdr) and age_ms.
  • timeoutOpts: set milliseconds up to 300,000 and choose behavior: "fail" or "return-partial" where supported. Reaching the overall deadline with "fail" returns 408. Scrape requires at least 5,000 ms for return-partial and marks partial captures or failed outputs with isPartial: true; individual outputs can fail under either behavior while others succeed. Crawl and Map URLs return partial: true. Prefetch is fail-only and Parse does not accept timeoutOpts. See timeouts.
  • maxPages, maxDepth, urlRegex, and stopAfterMs: bound crawl coverage, time, and credit exposure. Crawl caps maxPages at 500.
  • sharedParams.mainContentOnly, includeSelectors, excludeSelectors, and includeFrames: control page content before conversion. Exclusions win. Filters apply to HTML, Markdown, images, and parsed fields, never to bytes.
  • formats.parse with parseParams.rules: map each field name to a CSS selector string or {selector, type: "item" | "list", output: "text" | "html" | "@attribute" | nested rules}. Results arrive in parsed.data; missing items return null and missing lists return []. Runs without an LLM.
  • sharedParams.waitFor (milliseconds or a CSS selector; default 500 ms), settleAnimations, and browser actions (type: "perform" | "scroll" | "wait" | "waitFor", 1 to 5 per request): handle dynamic page state. Actions require a paid plan and bypass the cache. Action or selector failures can leave affected outputs with success: false; verify the page state from successful captured outputs.
  • formats.bytes: returns the original HTTP body as {contentType, base64} after decompression, up to 20 MiB decoded. Waiting, actions, and content filters never change it; request formats.html for rendered HTML.
  • sharedParams.headers go to the target origin only and are separate from the API bearer key. sharedParams.country is a two-letter code for the network exit of the page fetch and image downloads; an unsupported code returns 400 before the scrape starts. See location and headers.
  • screenshot.data is an inline data URL (data:image/png;base64,...) when screenshot.success is true; otherwise it is null. Choose the capture area with screenshotParams.area (viewport, fullPage, {selector}, or a rectangle) up to 40 megapixels.
  • zdr: "enabled": bypasses shared caches and retained content logs only when Zero Data Retention is enabled for the organization; otherwise the request fails with 403.

Browser rendering and proxy routing improve access but do not guarantee that a page can be read. Preserve a fallback for WEBSITE_BLOCKED, login walls, missing content, and partial crawl results.

Map a website's URLs

GET /web/urls lists a site's URLs from Context.dev's index and adds stored title, description, keywords, and language where available. Pass domain without a protocol; narrow with urlRegex, maxLinks (default 10,000), includeSubdomains, or search (relevance-ordered). The SDK methods are client.web.mapUrls (TypeScript) and client.web.map_urls (Python, Ruby).

URLs without stored metadata return with only url and are queued for background enrichment, so a later request can include their metadata. Requests with zdr=enabled or credential-bearing target headers return URLs only and do not queue enrichment. partial: true means the deadline stopped URL mapping. Feed the result into Scrape, Crawl, or a batch.

Retrieve brand data

Send exactly one lookup variant:

typeRequired fieldImportant constraint
by_domaindomainPrefer a bare company domain.
by_namename3 to 30 characters; use country_gl as an ambiguity hint.
by_emailemailFree and disposable providers return 422.
by_tickertickerAdd ticker_exchange when known.
by_direct_urldirect_urlReads only that page; no wider resolver or cross-source enrichment.
by_transactiontransaction_infoAdd MCC, city, country, or phone hints when available.
const response = await client.brand.retrieve({ type: "by_domain", domain: "stripe.com" });
const title = response.brand?.title ?? "Unknown company";

An uncached domain or email lookup with behavior: "fail" and timeoutOpts.milliseconds under 10,000 returns 422 COLD_DOMAIN_TIMEOUT_TOO_LOW; allow 60,000 ms or prefetch. Brand arrays and nested fields can be missing or empty. Select logos by type, mode, and resolution; do not assume logos[0] is appropriate. Treat address, contacts, employee count, classifications, and stock data as discovered data rather than verified legal records.

Permissions and other operation notes

  • Restricted API keys need the relevant scope: data:execute for direct data calls, Read/Manage scopes for monitors and batches, and logs:read for request logs. Any key can submit Agent Feedback. Dashboard team roles are independent; Members can use shared credentials and incur charges.
  • Answers defaults to ultra mode; fast is cheaper and quicker. json_format is an example object, and source URLs are not per-field citations.
  • Scrape, Map URLs, Crawl, Search, Answers, Parse, People Enrich, and Styleguide honor zdr when the organization is entitled.
  • Page monitors accept include_selectors/exclude_selectors; changing them establishes a new baseline.

Budget requests

OperationCredits
POST /web/scrape1, or 2 with sharedParams.actions. Highlights +1 when passages are returned; JSON +4 on success; product +1 on success or a missing page; PDF OCR +1 per recovered page on a fresh fetch. 0 when every output fails, except a target 404, which charges the base (+1 with product).
GET /web/urls1, or 2 with search
POST /web/crawl1 per page; rate-limit weight 10 on per-minute plans
POST /web/search1 per 10 results; Markdown and highlights each add 1 per 10 results when returned
POST /web/answers10 (fast) or 100 (ultra, the default), charged only on success
POST /parse1, plus 1 per OCR-recovered page
POST /brand/retrieve, GET /web/styleguide10
GET /brand/search1; free on Pro, Growth, and Scale
POST /people/enrich20 per match; paid plans
POST /news/search1 per 10 results
POST /utility/prefetch0; paid plans
POST /batch/submit1 per page: 1 reserved per accepted URL (a crawl reserves maxUrls), refunded for pages that don't succeed, plus 1 per OCR-recovered PDF page
POST /monitors, POST /monitors/{id}/runPer run: 1 for a page or sitemap monitor, 10 for an extract monitor. Baseline runs, at creation or after a re-baseline, are charged; failed and skipped runs are free.
Other batch and monitor operations, webhook deliveries, request logs, POST /feedback0

Processed 404 results on priced data APIs and successful partial results are charged. Validation, authentication, rate-limit, timeout, and server errors are not. Record key_metadata.credits_consumed or the X-Credits-Used header instead of inferring cost from status. Plan allowances are on Credits and pricing.

Handle errors by category

Inspect both the HTTP status and error_code for request errors. Scrape also reports output failures inside 200 responses: inspect each output's success and preserve isPartial: true. Use raw HTTPS or the SDK's raw response if an older generated model does not expose these fields.

StatusTreat asAction
400Invalid request, inaccessible or blocked target on operations that fetch one directly (WEBSITE_ACCESS_ERROR, WEBSITE_BLOCKED), image-only PDF on Parse (PDF_IMAGES_ONLY), skipped PDF (PDF_SKIPPED), or no match, depending on error_codeFix the input or options. For PDF_IMAGES_ONLY, retry Parse with ocr=true. Use a fallback for a no-match or inaccessible site.
401Missing or unknown key (NOT_FOUND), disabled key (DISABLED), or not enough credits (USAGE_EXCEEDED)Fix the key or account state; do not retry unchanged.
403Missing key scope (INSUFFICIENT_PERMISSIONS, with required_permission), paid-plan feature (PAID_PLAN_REQUIRED), too many active batches (BATCH_LIMIT_EXCEEDED), or ZDR not enabled (ZDR_NOT_ENABLED)Do not retry unchanged; inspect error_code.
404Target or entity not found on operations that define itTreat as an expected empty outcome where appropriate.
408The request reached timeoutOpts.milliseconds with behavior: "fail" (REQUEST_TIMEOUT)Retry outside a user-facing path, raise the budget, use return-partial where supported, or prefetch supported Brand and Styleguide requests.
200 with a failed Scrape outputRetrieval, parsing, actions, selectors, or output limits prevented that output from completingPreserve successful outputs and fix the target or options before retrying the failed output. Oversized outputs have success: false and data: null.
413, 415Content too large (such as a Parse upload over 50 MiB) or unsupported, on operations that define these errorsUse a smaller or supported input. Scrape marks such outputs as failed instead.
422An operation-specific input restriction, such as a free email domain or a Brand timeout that is too lowChange the input or options; do not retry unchanged.
429Organization concurrency limit, or the API key's per-minute limit on older plansHonor Retry-After; keep parallel calls within the concurrency limit and retry with jittered, bounded backoff.
500, 502, 503Transient failure: a service error, an incomplete browser capture, or no browser capacityRetry with jittered, bounded backoff, then surface a fallback.

Do not retry validation, permission, no-match, content-size, or unsupported-media failures unchanged. The SDKs already retry twice; account for that before adding another retry layer. See Troubleshooting and Rate limits for operation-specific behavior.

Report problems with Agent Feedback

When an endpoint, docs page, SDK, or CLI behaves differently than documented, offer to report it with Agent Feedback: POST https://api.context.dev/v1/feedback with the same bearer key. It works with any API key and has its own rate limit. Send one report per problem with the affected request_id so the team can see the exact request, and keep secrets and personal data out of the note.

{
  "request_id": "<request_id from the affected response>",
  "category": "docs_mismatch",
  "note": "The response is missing a documented field; expected it per the API reference."
}

Send url instead of, or with, request_id for a docs page or one page of a crawl. Categories are bug, docs_mismatch, friction, feature_gap, quality_degradation, and other. Reporting the same request_id again returns the original feedback_id with already_submitted: true. In an MCP session, use the submit-feedback tool instead.

Completion checklist

Before declaring an integration complete:

  • Confirm the path, method, and parameter names against the current API reference.
  • Request only the formats the task needs, and read each output's data rather than assuming it is present.
  • Keep the API key on the server and prove the missing-key path is intentional.
  • Bound crawl size, latency, retries, and credit exposure.
  • Handle missing fields and expected no-result states.
  • Validate parsed and structured output and preserve provenance when needed.
  • Run a focused success test and at least one relevant failure test.

For long-lived integrations, read Security and API stability and the changelog.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.