# DiscoLike API

> REST API and MCP server for B2B company discovery, firmographic data, and contact enrichment across 80M+ business domains.

For the full API reference with all parameters, response schemas, and examples, see [llms-full.txt](https://docs.discolike.com/llms-full.txt).

## MCP Server

DiscoLike provides a Model Context Protocol (MCP) server for AI-assisted company discovery directly from coding environments.

Server URL: https://api.discolike.com/v1/mcp
Authentication: OAuth via browser authorization

Fastest setup for Claude Code or Codex: paste the prompt from https://docs.discolike.com/mcp/ (the agent registers the server and hands the user the browser sign-in; no API key). Other clients: config JSON on the same page for Claude Desktop, Cursor, VS Code, Windsurf, Zed.

Agent skill package: https://github.com/Discolike/discolike-skills contains the operating workflow for Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Windsurf, Grok, and AGENTS.md-compatible agents. The skill tells an agent when and how to use DiscoLike; configure this MCP server separately before expecting it to call the tools.

The MCP server also serves these skills as MCP resources: `skill://discolike/SKILL.md`, `skill://setup/SKILL.md`, `skill://feedback/SKILL.md`; supporting files at `skill://<name>/<file>`, file list at `skill://<name>/_manifest`.

Setup (Claude Code):
```
claude mcp add --transport http --scope user discolike https://api.discolike.com/v1/mcp
```

Setup (Codex CLI):
1. Add the MCP server:
```
codex mcp add discolike --url https://api.discolike.com/v1/mcp --oauth-resource https://api.discolike.com/v1/mcp
```
2. Ensure `~/.codex/config.toml` includes the OAuth resource:
```toml
[mcp_servers.discolike]
url = "https://api.discolike.com/v1/mcp"
oauth_resource = "https://api.discolike.com/v1/mcp"
```
3. Authenticate:
```
codex mcp login discolike
```
If reconnecting after changing the config, run `codex mcp logout discolike` first.

Setup (Cursor / VS Code / Windsurf, add to MCP config JSON):
```json
{
  "servers": {
    "discolike": {
      "url": "https://api.discolike.com/v1/mcp"
    }
  }
}
```

MCP tools are organized by function:

Managed prospecting: start-prospecting automatically approves and takes brief.customer_domains for a seeded, lookalike-of-your-customers run; when the brief names no company count it defaults to 100 target companies (versus 1000 for REST/SDK), since approval and its company and contact research spend happen immediately, while email lookups wait for the person's answer; get-prospecting-run accepts run_id, offset, limit (maximum 100), events_after, and returns question (question_seq, reason, content, replies, estimate) when a needs_input run waits on the person (needs_input with no question, such as run_timeout, is final); answer-prospecting(run_id, question_seq, text, idempotency_key) sends the person's answer, a replies label verbatim when offered (contacts_review: "Find emails", "Find more companies first", "Finish"; provider_unavailable, stage_unavailable, account_unavailable: "Retry", "Cancel"; question: free text), errors on a stale question_seq or with no quota left; cancel-prospecting stops new work. REST approval, chat, list, rename, and delete operations are separate. Interpretation and wizards use platform credentials; coordination and contact qualification use customer LLM integrations, except a run whose company checks use DiscoLike VibeCheck (native-icp) and whose contacts come from DiscoLike Groove (native), the contact index alone, or are not requested, which needs none and keeps contacts by title without persona qualification. Existing processing/BYOK/BYOS charges apply. With several AI or search providers and none marked default, pass validation_integration_id, contact_integration_id or search_provider_id in the brief; otherwise the run stops and its error lists the ids. Reuse the idempotency key on retries and inspect stop_reason.
Discovery: discover-similar-companies, count-matching-domains, list-industry-categories
Company Data: business-profile, digital-footprint-score, growth-metrics, extract-website-text, domain-redirects
Contacts: search-contacts, count-contacts, contact-lookup, match-contacts, bulk-match-contacts, generate-contacts (contact discovery via BYOS search plus your LLM or DiscoLike Groove native extraction), find-emails (batch email finding, poll get-email-results), get-email-results
Matching: match-company-to-domain, bulk-match-company-to-domain, segment-domains
Relationships: vendor-and-technology-data, subsidiaries-and-parent-companies, public-company-links
Saved Queries: list-saved-queries, save-mcp-query, save-exclusion-list, list-tags, add-tags-to-query, remove-tags-from-query, get-domains-by-tags
Account: account-status, usage-statistics, append-data
Enrichment: research-companies, research-contacts, get-research-status, cancel-research, list-research-providers, validate-icp-fit (accepts integration_id="native-icp" to score on DiscoLike's own ICP-fit model at no LLM cost)
CRM (Beta): push-to-crm, crm-suppress, crm-import-companies, crm-match-companies, crm-writeback-domains, crm-enrich-contacts, crm-match-contacts, crm-writeback-emails, crm-writeback-segments, crm-audit-companies: sync with HubSpot, Pipedrive, or Salesforce; connect from app Settings > Integrations first

MCP discovery workflow:
1. Call discover-similar-companies with icp_prompt parameter; it automatically extracts filters, generates ICP text, suggests domains, and runs discovery
2. Alternatively, build filters manually: pass domain for lookalike search, icp_text for semantic matching, or structured filters directly
3. Refine iteratively: add good results to domain (positive examples), bad results to negate_domain
4. For criteria that can't be filtered natively (e.g., funding stage), use extract-website-text on result domains and analyze the content
5. For batch enrichment with custom prompts, use research-companies to run DiscoGen research over a domain list; it processes each domain in an isolated context

## Official SDK & CLI

- [Python SDK: Getting Started](https://docs.discolike.com/sdk/): `pip install discolike`. Sync `Discolike` and async `AsyncDiscolike` clients covering the full API. Requires Python 3.11+. Auth via `auth=` (`ApiKeyCredential` or `OAuthCredential`), `api_key=`, `DISCOLIKE_API_KEY`, or the `discolike auth login` config file (OAuth session or API key), resolved in that order. OAuth sessions are refreshed automatically.
- [Python SDK: Reference](https://docs.discolike.com/sdk/reference/): every method by namespace (`account`, `companies`, `contacts`, `discogen`, `discovery`, `email`, `enrich`, `llm_providers`, `match`, `prospecting`, `queries`, `search_providers`), plus the request models (`discolike.requests`, validated locally before the request is sent), response models, and exception types.
- [CLI: Install & Authentication](https://docs.discolike.com/cli/): `pip install discolike-cli` or `pip install "discolike[cli]"`, zero-install `uvx --from discolike-cli discolike`. `discolike auth login` logs in through the browser (OAuth, PKCE) by default; `--api-key KEY` or `--method api_key` for an API key. Includes managed prospecting plan approval and chat.
- [CLI Command Reference](https://docs.discolike.com/cli/reference/): every command and option: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment`, and the `bulk` (companies past the 10,000-per-search ceiling, free contact estimate, contacts by domain slice with checkpoint and resume), `company`, `contacts`, `discogen`, `email`, `auth`, `account`, `prospecting`, `queries`, `search-providers`, `llm-providers` groups. Prospecting start drafts a plan; wait returns at proposed, approve requires --plan-version, and message requires --text and --idempotency-key. Omitted quantity flags preserve brief inference. Volume inputs come from files: `--domains-file`, `--customers-file`, and `--params-file form.json`.

Repo: https://github.com/Discolike/discolike-python - SDK: https://pypi.org/project/discolike/ - CLI: https://pypi.org/project/discolike-cli/

## REST API Authentication

Header: x-discolike-key: YOUR_API_KEY
Manage keys at: https://app.discolike.com/account/management/keys
Agent-initiated signup: POST https://api.discolike.com/v1/public/signup {email, first_name, last_name, agent?} creates the account for a human (no credential returned; they confirm by email and log in). Also `discolike signup` (CLI) and `discolike.signup()` (SDK). Per-agent guide: https://docs.discolike.com/guides/agent-signup/
Prompt to give an agent: "Create a DiscoLike account for me. Send POST https://api.discolike.com/v1/public/signup with Content-Type: application/json and body {"email": "<my work email>", "first_name": "<my first name>", "last_name": "<my last name>", "agent": "<your name>"}. No auth header is needed. Ask me for any value you don't know. Then relay the next_step text from the response to me. Reference: https://docs.discolike.com/guides/agent-signup/"
Or: Authorization: Bearer YOUR_ACCESS_TOKEN (OAuth 2.1 access token, accepted on every /v1/* route; live on dev, in production with the next platform release)
OAuth server metadata: https://api.discolike.com/v1/.well-known/oauth-authorization-server (authorization-code + PKCE, dynamic client registration, scope offline_access, resource https://api.discolike.com/v1)
Precedence when several are sent: web session, then bearer token, then API key. Bad bearer: 401 "Invalid API Key or Session"; unknown tenant: 403.
OpenAPI spec: https://api.discolike.com/v1/openapi.json

## Core Discovery Endpoints

- [Discover](https://docs.discolike.com/api/endpoints/discover/): GET /v1/discover. Find companies via domain lookalike (up to 10 domains), natural language ICP text, icp_prompt (auto-extracts filters and domains from natural language), or exact phrase matching. Supports filters for country, state (ISO 3166-2 code or full name, one `country` value only, which may be a region alias), multi-shape geography (repeatable `geo` circles as lat,lon or lat,lon,radius and repeatable `bbox` boxes as min_lat,min_lon,max_lat,max_lon, plus the single lat/lon/radius centre; every shape is OR'd, up to 10 per query), employee range, revenue range, business model (B2B/B2C/B2G/G2B/G2C/D2C/C2C/C2B), tech stack, industry, sub-industry (217 second-level labels scoped to their parent category), language, digital footprint score, social presence, lead generation exclusion, direct domain exclusion (exclude_domain, hard-excludes up to 100 domains without affecting lookalike matching), and more. relevance (MAX_RELEVANCE, BALANCED, MAX_COVERAGE) stops a lookalike list (icp_text or domain) where estimated ICP fit drops too low; omitted, results run to max_records; variance is deprecated, its old values map onto relevance. Returns ranked results with similarity scores, industry_groups, sub_industry, latitude, longitude, geo_precision, business_model (label:confidence dict), and revenue_range bucket on each record. Response includes X-Applied-Filters header showing the resolved filter criteria used for the search.
- [Count](https://docs.discolike.com/api/endpoints/count/): GET /v1/count. Estimate result count before running full discovery. Same filters as Discover, including sub-industry and geographic areas. Use it to size a multi-city query before running it.

## Contact Endpoints

- [Contacts](https://docs.discolike.com/api/endpoints/contacts/): GET /v1/contacts. Search business contacts. Use `icp_prompt` for automatic filter extraction and company discovery chaining (preferred), or `icp_text` for raw semantic matching. When icp_prompt detects company-level signals (tech stack, funding, product descriptions), automatically runs company discovery first then searches contacts at matching companies. Filter by seniority, department, domain, company size, industry, location, and job start date (`jobstart_date`, min or `min,max` range, the "recently hired" filter). Use `max_companies` for an enriched-company cap or `max_records` for a literal contact-count cap; do not combine them. Includes /contacts/count and /contacts/lookup (by persona_id, linkedin, or email; exact match) sub-endpoints.
- [Contacts Discover](https://docs.discolike.com/api/endpoints/contacts/#discover-contacts): POST /v1/contacts/discover. Same filters as /v1/contacts but response is grouped by company domain with firmographic data on each entry and contacts nested underneath. `max_companies` returns up to N enriched company/domain entries; `max_records` returns up to N contact rows. Billed additively: net-new contacts + net-new firmo domains from the same credit pool.
- [Contacts Discover Generate (BYOK)](https://docs.discolike.com/api/endpoints/contacts/#discover-contacts-byok-generate): POST /v1/contacts/discover/generate. Discover candidate contacts at given domains using your own search provider (BYOS) plus either your own LLM (BYOK) or DiscoLike Groove native extraction (no LLM key, no title validation). `integration_id` takes an LLM integration UUID, `native`, or is omitted for native when it is available and a search provider resolves (otherwise your default LLM integration); a search provider is required either way. Web search always enabled. Async DiscoGen task; poll /discogen/status/{task_id}, whose completed payload reports title_validation ("llm" or "none"). Returns per-row contact fields (name, title, email, linkedin_url, seniority, ...) plus the company's inferred email pattern per domain. email is null unless a source shows it; pass find_emails=true to run the email finder over named, email-less rows before the task completes (fills email and email_status; found addresses bill under the finder's rules). Otherwise no platform billing. Results are candidate data; validate before use.
- [Contact Match](https://docs.discolike.com/api/endpoints/contact-match/): GET /v1/contacts/match. Match a person's name to contact records. Optional domain, title, company filters.
- [Contact Bulk Match](https://docs.discolike.com/api/endpoints/contact-bulk-match/): POST /v1/contacts/bulk-match. Batch match person names and/or emails from JSON (each query needs `name` or `email`; emails are exact-matched first, falling back to name/company matching). Async task with status polling.
- [Email Find](https://docs.discolike.com/api/endpoints/email-find/): POST /v1/email/find (single) and POST /v1/email/find/batch (up to 500). Find and SMTP-verify a person's work email from first name, last name, and company domain. Async: poll GET /v1/email/jobs/{job_id} or GET /v1/email/batch/{batch_id}/results until terminal. Only proven addresses (status `found`) bill as records (90-day dedupe); catch-all and pattern guesses are free.

## Company Data Endpoints

- [BizData](https://docs.discolike.com/api/endpoints/bizdata/): GET /v1/bizdata. Firmographic data for a domain: name, address, phones, emails, social URLs, description, keywords, industry groups, sub_industry (217 second-level labels), latitude/longitude and geo_precision, employee count, email/MX hosting provider (mx_provider, or no_mx when the domain has no mail server).
- [Score](https://docs.discolike.com/api/endpoints/score/): GET /v1/score. Digital footprint score with components: base score from 10-year certificate history, recency multiplier, growth boost, expiration penalty.
- [Growth](https://docs.discolike.com/api/endpoints/growth/): GET /v1/growth. Quarterly growth metrics: score changes and subdomain counts per quarter, 3-month growth rates.
- [Extract](https://docs.discolike.com/api/endpoints/extract/): GET /v1/extract. Extract text content from any URL with language detection.

## Company Matching Endpoints

- [Match](https://docs.discolike.com/api/endpoints/match/): GET /v1/match. Match company name to domain with optional country, state (ISO 3166-2 code or full name for any country with subdivisions), city, zip, phone. Returns ranked candidates with confidence scores; results below match_confidence 50 are never returned. Use `min_match_confidence` (50-100, default 50) to raise that floor.
- [Bulk Match](https://docs.discolike.com/api/endpoints/bulk-match/): POST /v1/bulkmatch. Match CSV of company names to domains. Async task; results below match_confidence 50 are never returned. Use `min_match_confidence` (50-100, default 50) to raise that floor. Rows the search backend could not process carry `match_error: search_failed` instead of being reported as no-match.

## Validation Endpoints

- [Validate ICP Fit](https://docs.discolike.com/api/endpoints/validate/): POST /v1/validate/icp. Validate domains against your ICP description. Returns structured fit (Yes/No, title case on both engines), confidence (high/medium/low), and reasoning per domain. Async task with status polling via /discogen/status/{task_id}. Pass integration_id="native-icp" to score with DiscoLike's own ICP-fit model instead of your LLM provider: no LLM key or cost, no web search, and the columns become ICP Fit (Yes/No), ICP Score (0.00-1.00) and Reasoning, which on a native run carries the confidence band (High/Medium/Low confidence) rather than an explanation, since the model scores rather than explains; a low-confidence verdict is near a coin flip and should be treated as unresolved. Read column_name from the task response instead of hardcoding either set.

## AI Enrichment Endpoints

- [Managed Prospecting](https://docs.discolike.com/api/endpoints/prospecting/): POST /v1/prospecting/runs with Idempotency-Key drafts a plan (optional deliverable "leads" (default, people to contact) or "accounts" (companies only: search and ICP-check companies, no contact work, completes on target_companies fit companies), and goal "leads" (default, keep adding rounds until the contact target is met) or "companies" (take target_companies matching companies and work only those, stop_reason companies_worked)); POST /v1/prospecting/runs/{run_id}/approve requires plan_version (optional checkpoints); PATCH /v1/prospecting/runs/{run_id}/plan changes a proposed plan (requires plan_version; optional contact_integration_id, validation_integration_id, search_provider_id ("none" skips web research), all option ids from the plan message's contact_engine, company_check_engine and search_provider, target_companies (1-10,000; automatic limits re-derived), contacts_per_company (1-10), deliverable, goal, max_spend_usd, a USD limit on DiscoLike credits (records and per-request fees at the plan's rates) where 0 clears it and a plan without a rate returns 422, and max_provider_spend_usd, a USD limit on your own AI and search provider keys where 0 clears it (running batches finish, so it can end slightly above); all optional, omitted fields keep their value; engines not picked are re-chosen around the picks), re-estimates at a new plan_version (the plan message's estimate.llm_cost_usd is the expected AI and search provider spend, split into estimate.ai_cost_usd and estimate.search_cost_usd, null when it cannot be split) and rewrites the latest plan message in place (same seq, so read it from the response's messages, not the messages cursor), then approve that version, returns the run, 422 for an unknown option id or extra field, 409 when the run is not proposed or plan_version is stale, 404 for a missing run; POST /v1/prospecting/runs/{run_id}/messages requires Idempotency-Key and either text or intake, plus optional question_seq (the seq of the question a suggested reply answers; if a newer question was posted since, the reply answers nothing and the agent says the question changed). When a brief leaves out details, planning pauses on one intake card: needs_input, stop_reason "question", a question message with data.reason "intake", content listing the field labels after a headline, suggested_replies ["Use your best guess"], and data.fields (at most 5 fields, required first: key in deliverable, company_activity, industry, geography, company_size, persona_roles, list_size; label, multi, options with value and label, allow_other, default, required; company_activity and persona_roles are required, and deliverable when asked (only when the brief does not say people or companies; options leads and accounts, and accounts drops persona_roles); company_size and list_size have fixed options, list_size "all" means 10,000). Answer with intake, an object keyed by field key whose values are {values, other (max 200 characters)}; it returns 422 when a key is not on the card, a value is not an option, other is sent without allow_other, a single-choice field gets several values, or a required field is empty, and 409 "This question was already answered" when the card is closed (run resumed, newer question, or an intake answer already stored; a chat question in between keeps it open). An explicit target_companies removes list_size from the card, an explicit max_candidates limits its options and caps the chosen size, and an unclear count in the brief is asked as list_size. The choices fold into the brief without another interpretation pass, list_size sets target_companies, and the run plans once more. Intake is asked at most once per run (a fallback single question counts as it); leftover gaps get one plain question, then the run plans from its best reading, a free-text reply also works, and MCP runs never ask it (a too-vague MCP brief gets the single question). The Python SDK method is client.prospecting.answer_intake(run_id, answers, idempotency_key=, summary=) with IntakeAnswer from discolike.requests. GET /v1/prospecting/runs lists recent runs (limit 20, max 50), with before (a run ID) for keyset paging past that run, ordered created_at then run_id descending; an unknown or other-org run ID returns an empty page; GET /v1/prospecting/runs/{run_id} supports offset, limit (100, max 500), events_after, messages_after, and returns pipeline_phase ("companies" while a phased run searches and checks every company, "people" while it finds people at the fit ones, null for older interleaved runs; new runs and every accounts run are phased), provider_cost_usd (spend so far on your own AI and search provider keys, null when none recorded) with provider_ai_cost_usd and provider_search_cost_usd (its AI and search parts, null for runs started before the split; REST only), the closing message naming each part ("Your AI provider key was charged about $X and your search provider about $Y", parts under a cent omitted; older runs give the total) and companies_saved_query_id; PATCH /v1/prospecting/runs/{run_id} takes title, checkpoints ("ask" Manual or "auto" Auto), or both (neither, extra fields, or a title outside 1-80 trimmed characters is 422) and returns the run summary as in the list; a missing, deleted or other-org run is 404; a title alone renames the chat in any status, a title set before the agent plans is kept, and result lists already saved keep their names; checkpoints switches the mode of an unfinished run (finished is 409), needs the start gate (plan, active subscription and payment method, else 403; quota, else 402), applies before a title sent with it, and switching to auto while paused at a checkpoint answers it with continue and resumes (409 if another of your runs is active); a run about to pause at a checkpoint when switched to auto keeps going; contacts_review is exempt from both and stays open; POST /v1/prospecting/runs/{run_id}/cancel stops new work (completed results kept) and returns the run; DELETE /v1/prospecting/runs/{run_id} returns 204, cancels an active run first, and removes it from get/list (later calls 404; charges incurred are not refunded; saved result lists remain; reusing its Idempotency-Key returns 409). Statuses include drafting/proposed; approve reviewed plans before research. Initial counts come from the brief unless explicit settings override them, with 1000 companies and 3 contacts per company as fallbacks; max_candidates/max_actions default to automatic (0). Up to 10,000 companies; saved results are stable saved_query_id/saved_query_ids (use every id, results split into parts on large runs), plus partial results and chat replies. Work limits (max_candidates, max_actions) do not cap provider-dollar spending; max_provider_spend_usd on the plan does, and stops the run as provider_limit. Saved results group by company: every fit company is a parent row with domain and fit columns (ICP Fit, Confidence, Reasoning, Segment, Customer segment) and its contacts nested under contacts; an accounts run has parent rows only; a separate companies list is still saved at companies_saved_query_id. Starting can return 403 when the organization can't start another run right now; the message says when to retry. A chat closed for off-topic use sets chat_closed true on the run response and, for a run with no approved plan or an approved run paused on a question, cancels it with stop_reason "misuse"; an approved queued or running run keeps working. The brief's checkpoints field ("ask" or "auto", default "auto"; hidden from the OpenAPI schema, set it explicitly) picks whether the run pauses in chat at decision points: pilot (first batch validated), tail_quality (a search drifting off target), short (searches ran out under target), target_reached (companies and target_companies times contacts_per_company emails both met), and top_up (a phased goal "leads" run needs another round of companies and it needs more room than the spending limits allow; asked in auto mode too; replies continue, raise, shrink, finish as "Run another round", "Raise the limit and run it", "Run a smaller round (N companies)", "Finish with N"; a round that fits the limits starts on its own with a notice, one with no room stops the run at that limit, and MCP runs cut the round to what fits), and contacts_review (wave runs, being rolled out to lead runs: each wave is sized from the target at the expected fit, persona-match and email-find rates with a 25% margin, every company in it is checked with no email lookups, then its contacts are found and qualified; while web research runs, persona-matched contacts from DiscoLike's database get their emails looked up (approving the plan is the consent, in ask and auto mode alike, except MCP runs, which look up no email before the review; the plan message's email_lookup_note says so; one batch at a time once 50 wait or the database search is done; early emails that reach the target complete the run without a review; a run whose plan message had no email_lookup_note looks up no email before the review), then the run pauses, in auto mode too, with the wave's checked/fit/persona-matched counts, the early lookups' results and how many still run, and the estimate for the remaining emails: lookups capped at the emails still needed divided by the find rate plus a 15% margin, less those still running (raised in a wave after the first to 50 lookups across the wave, early ones included), and the credit room, minutes at about 70 lookups a minute, expected emails, records of the plan quota reserved until each lookup settles (with USD when the run has a spending limit) (once the target is reached, unstarted lookups are cancelled and not billed); replies "Find emails" (that wave's shown lookups only; counts only when sent with question_seq of the review question, otherwise the review is posted again), "Find more companies first" (another wave, reviewed again; absent when no more candidates or contact rows are full) and "Finish" (user_finished, companies and contacts kept without emails; the saved list keeps contacts without emails, CRM pushes only contacts with emails); an email shortfall afterwards proposes the next wave through top_up, and every wave after the first gets at least 50 email lookups (early and reviewed together, bounded by the matched contacts waiting) and is sized at the run's find rate for them, unstarted lookups being cancelled at the target; closed-chat runs answer Find emails themselves; MCP runs pause and are answered with answer-prospecting). A paused run is needs_input with stop_reason set to the checkpoint name and a question message carrying suggested_replies to send back verbatim via the messages endpoint; the pilot question also carries a sample of checked companies. Auto mode never pauses except at top_up and contacts_review as above: a pilot under 80% fit gets its criteria sharpened once, then the run continues on the sharpened criteria with a text notice; it only stops as pilot_failed, with the sample in pilot_sample, if the re-piloted fit comes in under 20%, and continues on the original criteria if the sharpening itself fails or finds nothing new; a drifting search is dropped automatically; a run whose search runs dry finishes as candidates_exhausted, one that reaches its candidate cap as candidate_limit (raise max_candidates or ask for fewer companies), one that reaches its max_spend_usd DiscoLike credit limit as credit_limit and its max_provider_spend_usd AI and search provider limit as provider_limit (results kept), and a goal "companies" run that worked its companies as companies_worked; an automatic max_candidates can grow once from the run's measured yield, a user-set one never does; contact research defaults to DiscoLike Groove (no AI provider cost; its web searches bill your own search provider, about two queries per researched company, never DiscoLike credits) when a search provider exists, and search_provider_id "none" or no search provider finds indexed contacts only; company checks default to DiscoLike VibeCheck when the organization has no default generative AI integration, and a run on VibeCheck with Groove, index-only, or no contacts needs no AI provider (contacts kept by title, role_fit accepted with a role_reason saying they were not checked against the persona); interrupted indexed contact searches are retried. Finishing at a checkpoint by choice stops with stop_reason "user_finished". MCP runs are always auto and pause only at contacts_review, clarifying questions, and provider, stage or account stops, answered with answer-prospecting. GET /v1/prospecting/runs/{run_id} also returns question, the same open-question object as the MCP poll (null when nothing can be answered or a reply is still being read). The plan message also carries market_size (an upper bound on companies matching the planned queries, null for a domain- or company-name-seeded brief) and all_matching_target (offered only when the market exceeds the target, capped at 10,000). A brief can carry customer_domains (up to 1,000, not with domains/company_names): the run groups the customers into up to 8 segments (stage seed_segment), expands each with a lookalike plus wizard queries under a per-segment share of the target, and tags every company with seed_segment; approve takes seed_segments (ids from the plan card; omit to keep the run's current selection, the card's default or whatever a chat edit set) and segment. Saying "segment these" on a finished run groups its accepted companies (10 or more) into results segments without reopening it; reply_pending stays true until the segments message is posted (which can take more than an hour) and clears on its own after about 90 minutes if grouping stops without an outcome.
- [DiscoGen](https://docs.discolike.com/api/endpoints/discogen/): POST /v1/discogen/process. AI research agent that runs your prompt against each domain with isolated context (website text, company profile, or domain-only). Uses your default (or only) LLM and search providers, or specify by ID; with several and none marked default, pass integration_id. Async task with status polling. integration_id="native-icp" scores an ICP validation prompt with DiscoLike's own model instead of an LLM, returning columns ICP Fit, ICP Score and a Reasoning that carries the confidence band rather than an explanation (the model scores, it does not explain); the prompt must list its criteria under "Mandatory:", "Reject if:" and "Nice-to-have:" (400 otherwise, 503 when the engine is unavailable).
- [DiscoGen Personas](https://docs.discolike.com/api/endpoints/discogen/): POST /v1/discogen/process-personas. Same as DiscoGen but processes contact records. Context modes: name_only, profile, company, or full (profile + company + homepage text).
- [DiscoGen Models](https://docs.discolike.com/api/endpoints/discogen/): GET /v1/discogen/models. List available LLM models grouped by provider with web search support flags.
- [DiscoGen Typed Columns](https://docs.discolike.com/api/endpoints/discogen/#typed-columns): typed_columns=true on /process or /process-personas answers the yes/no, fixed-set, or scale parts of your query with DiscoLike's calibrated TypeSafe (Jev) judgment model instead of generated text; no criteria payload, the query text is the whole spec. Yes/no cells are Yes/No, fixed-set cells are option labels, and scale cells are numeric weighted positions on the zero-based ordered criteria (including fractions). include_confidence=true adds a High/Medium/Low confidence column beside each. Needs a `typesafe` LLM provider integration regardless of which integration_id the rest of the query runs on; missing one 400s with TYPESAFE_INTEGRATION_MISSING at submit. Pick a `typesafe` integration as integration_id to run typed-only: no LLM provider call at all, dropping any prose the query would otherwise generate (400 TYPESAFE_NO_TYPED_COLUMNS if the query has no judgment at all, 400 TYPESAFE_NOT_A_GENERATIVE_ENGINE if reached via org default rather than picked explicitly).

## Integration Management Endpoints

- [LLM Providers](https://docs.discolike.com/api/endpoints/llm-providers/): CRUD /v1/llm-providers/config. Manage LLM provider integrations for DiscoGen. Connect OpenAI, Anthropic, custom OpenAI-compatible endpoints, or `typesafe` (for DiscoGen typed columns; no base_url, cannot be set as org default). Includes test-connection and set-default.
- [Search Providers](https://docs.discolike.com/api/endpoints/search-providers/): CRUD /v1/search-providers. Manage search provider integrations for DiscoGen web search (BYOS). Supports Tavily, Serper, Parallel AI, Linkup. Includes available models listing, set-default, and clear-default.
- [CRM](https://docs.discolike.com/api/endpoints/crm/): Beta. Connect HubSpot, Pipedrive, or Salesforce. GET /v1/crm/connections (optional probe=true for live status), GET /v1/crm/{provider}/authorize (mint OAuth URL), POST /v1/crm/{provider}/suppress (snapshot CRM companies or contacts into an exclusion list, async), DELETE /v1/crm/{provider}/connection (admin app session, not API key). Import, match, write-back, audit, and contact enrichment are not public REST; use the app or the MCP CRM tools.

## Enrichment & Analysis Endpoints

- [Append](https://docs.discolike.com/api/endpoints/append/): POST /v1/append. Bulk CSV/Excel enrichment with bizdata, domain_status, redirects, growth, vendors, or subdomains datasets. Multipart form upload, async task. Optional query_id (CSV or array) unions saved-query domains with the file (capped per saved query); file is optional when query_id is given, and a request with neither returns 400.
- [Segment](https://docs.discolike.com/api/endpoints/segment/): POST /v1/segment. ML-powered clustering of company domains into segments with descriptions and membership confidence scores (not calibrated probabilities). Optional query_id (CSV or array) unions saved-query domains into the segmented set (capped per saved query).

## Relationship Endpoints

- [Vendors](https://docs.discolike.com/api/endpoints/vendors/): GET /v1/vendors. Technology relationships: find clients of a vendor or vendors used by a client.
- [Subsidiaries](https://docs.discolike.com/api/endpoints/subsidiaries/): GET /v1/subsidiaries. Corporate hierarchy: parent companies, subsidiaries, recursive traversal. At most 10,000 rows.
- [Redirects](https://docs.discolike.com/api/endpoints/redirects/): GET /v1/redirects. Domain redirect chains: source and destination domains.
- [PublicLink](https://docs.discolike.com/api/endpoints/publiclink/): GET /v1/publiclink. Related domains by shared contact info (email, social, phone).

## Utility Endpoints

- [Usage](https://docs.discolike.com/api/endpoints/usage/): GET /v1/usage. API usage and billing: month-to-date requests, records, spend, and monthly breakdown.
- [Saved Queries](https://docs.discolike.com/api/endpoints/queries/): Manage saved queries and exclusion lists. GET /queries/saved (filter by tags/action), POST /queries/save-results (save result rows as a reusable thin query), POST /queries/exclusion-list (tags at creation), PATCH /queries/{query_id}, DELETE /queries/{query_id}.
- [Signup](https://docs.discolike.com/api/endpoints/signup/): POST /v1/public/signup. Unauthenticated. Create a DiscoLike account (user + organization) for a person from their work email and name; built for AI agents acting on behalf of a human. Returns next_step text to relay; no API key or token is issued. 409 if the email exists, 422 for free-mail or disposable domains.

## API Reference

- [Authentication](https://docs.discolike.com/api/access/): API keys and OAuth bearer tokens
- [Rate Limits](https://docs.discolike.com/api/rate-limits/): Rate limits by plan tier (Starter 1x through Enterprise 20x), plus limits on queued email lookups and running async tasks per account
- [Error Codes](https://docs.discolike.com/api/errors/): HTTP status codes and error responses. Every billed request (REST, MCP, async task submission) is priced before it bills anything, at the request fee plus every record it could return assumed new; one the remaining cycle balance cannot cover gets 403 with detail object {code "INSUFFICIENT_BALANCE", message, remaining_usd, max_affordable_records, requested_records, upgrade_url}, where both counts are in the unit the request is sized by (max_records, max_companies, upload rows, queries, domains or personas; the message names it) and a retry at max_affordable_records fits; /vendors, /publiclink, /subsidiaries, /redirects and their MCP twins price the rows they found, after the lookup; a request that could not be priced gets 503 "Unable to price this request, try again". MCP tools raise the same message. Running jobs re-check the live balance: DiscoGen, ContaGen and ICP validation tasks stop before a batch it cannot cover and keep (and bill) finished rows; ContaGen skips an unaffordable find_emails leg with a warning; CRM enrich, audit and contact match jobs check their exact count inside the job and push and bill nothing when it does not fit; prospecting runs pause as needs_input with stop_reason "account_unavailable". Concurrent requests are priced against the same balance and can together overshoot it slightly. Accounts without a spending cap are never refused
- [MCP Setup](https://docs.discolike.com/mcp/): Setup instructions for Claude, Codex, Cursor, VS Code, Windsurf, and Zed; see the linked skill package for additional agent clients
- [MCP Tools](https://docs.discolike.com/mcp/tools/): MCP tools with descriptions and managed prospecting operations
- [MCP CRM Tools](https://docs.discolike.com/mcp/crm/): Beta. Parameters, workflows, and plan requirements for the 10 CRM tools (HubSpot, Pipedrive, Salesforce)

## Optional

- [Datasets](https://docs.discolike.com/datasets/bizdata/): Available data exports (BizData, Domain Status, Vendors, Subsidiaries, Redirects, Site Text, Certificates, DNS, PublicLink)
- [Supported Languages](https://docs.discolike.com/languages/): 55 languages for website content analysis
- [Supported Industries](https://docs.discolike.com/industries/): 53 industry categories for the `category` filter and `industry_groups` field
- [Supported Sub-Industries](https://docs.discolike.com/sub-industries/): 217 second-level labels for the `sub_industry` filter and `sub_industry` field, grouped by parent category
- [Supported States](https://docs.discolike.com/states/): Countries and subdivisions supported by the `state` filter (ISO 3166-2 codes or full subdivision names)
- [Self-Hosting Guide](https://docs.discolike.com/guides/self-hosting/): Run your own LLM for DiscoGen (Ollama + LiteLLM proof-of-concept)
- [Agent Signup Guide](https://docs.discolike.com/guides/agent-signup/): Per-agent instructions (Claude Code, Codex, Cursor, ChatGPT, Google ADK, OpenAI Agents SDK, LangChain, CrewAI, n8n) for creating a DiscoLike account from an agent
- [OpenAPI Spec](https://api.discolike.com/v1/openapi.json): Machine-readable API specification
- [Python SDK on GitHub](https://github.com/Discolike/discolike-python): Official Python SDK and CLI source