# Crawdar

> Crawdar turns a plain-language business research brief into a deduplicated list of businesses with public source evidence.

## Agent interfaces

- [Agent guide](https://crawdar.com/agents): MCP, API, and headless-browser instructions.
- [MCP Streamable HTTP](https://crawdar.com/api/mcp): Remote MCP endpoint with one-call research plus durable start, get, refine, and export-aware workflows.
- [Official MCP Registry](https://registry.modelcontextprotocol.io/?q=com.crawdar%2Fbusiness-research): Published as com.crawdar/business-research.
- [OpenAPI 3.1](https://crawdar.com/openapi.json): Machine-readable REST contract.
- [REST search](https://crawdar.com/api/v1/search): JSON POST endpoint.
- [Agent skill](https://crawdar.com/skills/crawdar-business-research/SKILL.md): Portable instructions for skill-aware agents.
- [Interactive app](https://crawdar.com/): JavaScript-capable browser workflow.

For repeated use, create a free service identity by POSTing `{ "label": "My research agent" }` as JSON to `https://crawdar.com/api/v1/keys`. Store the returned secret immediately because it is shown once. Send it as `x-api-key` or `Authorization: Bearer YOUR_KEY` to the API or MCP endpoint. Small anonymous samples work without a key.

## Recommended MCP workflow

1. Call explain_crawdar once if result semantics are unfamiliar.
2. Call research_businesses for a quick one-call result, or start_lead_search for a durable search job.
3. For resumable jobs, store the returned jobToken privately and call get_lead_search with view compact and limit 10. If status is running, honor retryAfter before polling again. If a job returns retryable true, call retry_lead_search.
4. Keep source URLs attached to every downstream record.
5. Inspect diagnostics and explained exclusions before treating zero results as exhaustive.
6. Pass nextCursor back unchanged. Use refine_lead_search to create a new job without changing the original.

The durable job response includes an exportUrl. Request it with Authorization: Bearer JOB_TOKEN. CSV is the default; add ?format=json for JSON.

Example research_businesses arguments:

{"brief":"Independent veterinary clinics in Berlin with an active first-party website. Exclude directories and chains.","output":"compact","limit":10,"offset":0}

## Minimal REST request

POST https://crawdar.com/api/v1/search with content-type application/json:

{"target":"independent veterinary clinics","geography":"Berlin, Germany","qualifier":"Must show an active first-party website.","fields":["Website","Location","Business email","Source links"]}

Free API and MCP usage is rate limited. A 429 response includes retry-after. Treat confidence as an evidence signal, not a guarantee. Verify evidence URLs before outreach or other action.

Results are separated into verified and likely fits. Verified means every requested first-party evidence check passed. Likely means the entity appears to be a real business but at least one requested check remains unverified. Rejected candidates include an exclusion reason so zero-result searches remain auditable.

## Product and policies

- [Business list builder](https://crawdar.com/business-list-builder): Product capabilities and evidence model.
- [Search templates](https://crawdar.com/templates): Ready-made workflows.
- [Crawler policy](https://crawdar.com/bot): Identification, robots.txt, and opt-outs.
- [Privacy](https://crawdar.com/privacy): Data processing and retention.
- [Terms](https://crawdar.com/terms): Permitted and prohibited use.

Crawdar is not designed for sensitive personal data, high-impact decisions about individuals, access-control bypasses, or unlawful marketing.