@context-dot-dev/convex

Context.dev Convex Component

Call the Context.dev API from your Convex actions. This component wraps the Context.dev REST API with typed helpers and isolated component actions—no data is stored in Convex.

Prerequisites

• A Convex app (get started)
• A Context.dev API key

Install

npm install @context-dot-dev/convex

Setup

Add the component to your Convex app config and wire your API key through component env:

import contextDev from "@context-dot-dev/convex/convex.config.js";
import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({
  env: {
    CONTEXT_DEV_API_KEY: v.string(),
  },
});

app.use(contextDev, {
  env: {
    CONTEXT_DEV_API_KEY: app.env.CONTEXT_DEV_API_KEY,
  },
});

export default app;

Set CONTEXT_DEV_API_KEY on your Convex deployment:

npx convex env set CONTEXT_DEV_API_KEY your_api_key_here
npx convex dev

Usage

Typed helper client (recommended)

Create a shared client and call it from your actions:

import { ContextDev } from "@context-dot-dev/convex";
import { v } from "convex/values";

import { components } from "./_generated/api.js";
import { action } from "./_generated/server.js";

const contextDev = new ContextDev(components.contextDev);

export const brand = action({
  args: { domain: v.string() },
  handler: async (ctx, args) => {
    return await contextDev.retrieveBrand(ctx, {
      params: { domain: args.domain },
    });
  },
});

export const scrapeMarkdown = action({
  args: { url: v.string() },
  handler: async (ctx, args) => {
    return await contextDev.scrapeMarkdown(ctx, {
      params: { url: args.url },
    });
  },
});

Direct component actions

You can also call component actions directly with ctx.runAction:

import { v } from "convex/values";

import { components } from "./_generated/api.js";
import { action } from "./_generated/server.js";

export const brand = action({
  args: { domain: v.string() },
  handler: async (ctx, args) => {
    return await ctx.runAction(components.contextDev.brand.retrieve, {
      params: { domain: args.domain },
    });
  },
});

API reference

GET endpoints take params. POST endpoints take body and may also take params when the operation defines query parameters. Responses are validated as JSON before being returned to your function.

Helper methods

Method	Description
scrapeHtml	Scrape a URL and return raw HTML
scrapeMarkdown	Scrape a URL and return Markdown
scrapeImages	Extract image references from a page
crawlSitemap	Crawl a domain sitemap
crawl	Crawl a site and return Markdown pages
extract	Crawl pages and extract structured data from a JSON schema
search	Search the web with optional filters and Markdown extraction
competitors	Find direct competitors for a domain
styleguide	Extract colors, typography, and design system details
fonts	Extract font usage and font asset links
screenshot	Capture a website screenshot
retrieveBrand	Retrieve full brand data by domain
retrieveBrandByName	Retrieve brand data by company name
retrieveBrandByEmail	Retrieve brand data from a business email
retrieveBrandByTicker	Retrieve brand data by stock ticker
retrieveBrandByIsin	Retrieve brand data by ISIN
identifyBrandFromTransaction	Identify a brand from transaction text
retrieveSimplifiedBrand	Retrieve a smaller brand payload
prefetchBrand	Queue brand prefetching by domain
prefetchBrandByEmail	Queue brand prefetching by email
retrievePerson	Retrieve a person profile from supported identifiers
retrieveNaics	Classify a company into NAICS codes
retrieveSic	Classify a company into SIC codes
aiQuery	Extract custom AI-defined datapoints from a website
extractProduct	Extract product data from a product page URL
extractProducts	Extract product listings from a domain or URL

Component action groups

Raw component actions are available under:

• components.contextDev.brand
• components.contextDev.web
• components.contextDev.ai
• components.contextDev.industry
• components.contextDev.people

Argument and response types are inferred from the Context.dev OpenAPI spec, so your editor will autocomplete params and body fields.

Caching

This component does not persist data in Convex. Context.dev caching is controlled through API parameters such as maxAgeMs on individual requests.

Learn more

• Context.dev documentation
• Convex components