{"name":"411data","version":"0.1.0","description":"411data is a lead and business-data enrichment API. MCP tools mirror the REST surface — enrichment lookups and lead search are paid; account tools are free with a bearer token. Billing: every paid call first debits virtual USD balance (~$0.20 starting credit at wallet mint via /connect). When balance is exhausted, calls return 402 with an x402 envelope for wallet USDC settlement on Base. Bill-on-match routes refund the charge when no usable match is found. 402 responses include billing_reason, virtual_balance_usd, connect_url, topup_url, and llm_user_message — read those fields and tell the user. No bearer → mint at connect_url. Usage keys (411k_…) are scoped to data routes only; manage them at /connect?action=usage-keys. Enrichment routes return complete JSON (no SSE/streaming). For push/async delivery, use event callbacks: https://411data.io/connect?action=event-callbacks (catalog GET /api/v1/event-callbacks/catalog). Docs: https://411data.io/developers — skill: https://411data.io/skill.md","instructions":"411data is a lead and business-data enrichment API. MCP tools mirror the REST surface — enrichment lookups and lead search are paid; account tools are free with a bearer token. Billing: every paid call first debits virtual USD balance (~$0.20 starting credit at wallet mint via /connect). When balance is exhausted, calls return 402 with an x402 envelope for wallet USDC settlement on Base. Bill-on-match routes refund the charge when no usable match is found. 402 responses include billing_reason, virtual_balance_usd, connect_url, topup_url, and llm_user_message — read those fields and tell the user. No bearer → mint at connect_url. Usage keys (411k_…) are scoped to data routes only; manage them at /connect?action=usage-keys. Enrichment routes return complete JSON (no SSE/streaming). For push/async delivery, use event callbacks: https://411data.io/connect?action=event-callbacks (catalog GET /api/v1/event-callbacks/catalog). Docs: https://411data.io/developers — skill: https://411data.io/skill.md","usage_policy":{"authoritative_for":["Single-record email / company / phone enrichment","LLM web-search business contact enrichment","Filtered B2B lead search"],"on_empty_result":"If a tool returns no match or an error, tell the user plainly. Do not invent contact data. Bill-on-match routes auto-refund when no usable result is found. Offer to broaden filters, mint a bearer at /connect, or settle x402 when balance is exhausted.","tool_order":["free account tools","paid enrichment","paid lead search"]},"transport":{"type":"http","endpoint":"https://411data.io/mcp","method":"POST"},"protocolVersion":"2025-03-26","tools":[{"name":"agents_me","description":"FREE with bearer — agent profile, virtual balance, linked wallets, and usage-key summary.","inputSchema":{"type":"object","properties":{}},"outputSchema":{"type":"object","properties":{"agent_id":{"type":"integer"},"owner_email":{"type":["string","null"]},"project_name":{"type":["string","null"]},"agent_label":{"type":["string","null"]},"status":{"type":"string"},"mint_source":{"type":["string","null"],"enum":["wallet","google",null]},"wallet_address":{"type":["string","null"]},"wallets":{"type":"array","items":{"type":"object","properties":{"wallet_address":{"type":"string"},"wallet_name":{"type":"string","description":"Display label; defaults to last 4 hex chars of wallet_address."},"is_primary":{"type":"boolean"},"allowance_usd":{"type":["string","null"]},"drawn_usd":{"type":["string","null"]},"remaining_usd":{"type":["string","null"]},"chain_id":{"type":["integer","null"]},"allowance_signed_utc":{"type":["string","null"],"format":"date-time"}}}},"wallet_allowance_usd":{"type":["string","null"]},"wallet_drawn_usd":{"type":["string","null"]},"allowance_signed_utc":{"type":["string","null"],"format":"date-time"},"virtual_balance_usd":{"type":["string","null"]},"virtual_credited_usd":{"type":["string","null"]},"virtual_spent_usd":{"type":["string","null"]},"free_daily_quota":{"type":["integer","null"]},"used_today":{"type":["integer","null"]},"created_utc":{"type":["string","null"],"format":"date-time"},"last_seen_utc":{"type":["string","null"],"format":"date-time"}},"required":["agent_id","status"]},"method":"GET","path_template":"/api/v1/agents/me"},{"name":"agents_balance","description":"FREE with bearer — virtual USD balance (spent before wallet x402).","inputSchema":{"type":"object","properties":{}},"outputSchema":{"type":"object","properties":{"agent_id":{"type":"integer"},"virtual_balance_usd":{"type":"string"},"virtual_credited_usd":{"type":"string"},"virtual_spent_usd":{"type":"string"},"ledger":{"type":"array","items":{"type":"object","properties":{"ledger_id":{"type":"integer"},"utc_ts":{"type":"string","format":"date-time"},"delta_usd":{"type":"string"},"reason":{"type":"string","description":"e.g. `route_charge`, `mint_grant`, `empty_rows`, `timeout_refund`, `coverage_reject`."},"route":{"type":["string","null"]},"payment_id":{"type":["string","null"]},"request_id":{"type":["string","null"]},"balance_after_usd":{"type":"string"},"notes":{"type":["string","null"]}}}}},"required":["agent_id","virtual_balance_usd"]},"method":"GET","path_template":"/api/v1/agents/balance"},{"name":"enrich_phone","description":"PAID ($0.330): Reverse phone lookup → person name, emails, addresses. E.164 preferred. Bill-on-match. Use when: Reverse phone lookup → person name, emails, addresses.","inputSchema":{"type":"object","properties":{"phone":{"type":"string","minLength":5,"maxLength":40}},"required":["phone"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"outputExample":{"endpoint":"enrich/phone","input":{"phone":"+17242060094"},"matched":true,"data":{"people":[{"name":"James W Cole Sr","aliases":["James Cole Jr","Jim W Cole"],"phones":[{"number":"(724) 206-0094","label":"unknown","score":71,"type":"unknown","source":"https://411data.io/person-hunt","sources":[{"url":"https://411data.io/person-hunt","label":"person hunt","vendor":"whitepages","wp_id":"PX3vrMbpE3k"}]}],"emails":[],"addresses":[],"relatives":[],"company_name":null,"job_title":null,"linkedin_url":null,"source":"https://411data.io/person-hunt","wp_id":"PX3vrMbpE3k"}],"metadata":{"result_count":5,"query_mode":"reverse_phone","page":1,"page_size":5}},"vendor":"whitepages","cache_hit":false,"billed":true},"method":"POST","path_template":"/api/v1/enrich/phone","body_keys":["phone"],"paid":true},{"name":"enrich_person","description":"PAID ($0.500): Person search: find phones (including mobile), emails, and addresses by name, reverse phone, or address. Use for residential/person leads. Bill-on-match. Use when: Residential or person-shaped lead — find phones, emails, and addresses.","inputSchema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"first_name":{"type":"string","maxLength":80},"middle_name":{"type":"string","maxLength":80},"last_name":{"type":"string","maxLength":80},"phone":{"type":"string","maxLength":40},"street":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"state_code":{"type":"string","maxLength":2},"zipcode":{"type":"string","maxLength":10}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"outputExample":{"endpoint":"enrich/person","input":{"name":"John Smith","state_code":"PA","zipcode":"15213"},"matched":true,"data":{"people":[{"name":"John Smith","phones":[{"number":"(412) 555-0198","label":"mobile","score":92}],"emails":[{"address":"john@example.com","score":88}]}],"metadata":{"result_count":1,"query_mode":"name_location"}},"vendor":"stub","cache_hit":false,"billed":true},"method":"POST","path_template":"/api/v1/enrich/person","body_keys":["name","first_name","middle_name","last_name","phone","street","city","state_code","zipcode"],"paid":true},{"name":"enrich_websearch","description":"PAID ($1.000): Deep web research to find decision makers and their contact information on a business — phones, executive names and titles, addresses, and legal_associates (attorneys, registered agents, family counsel). Map fields from a CRM JSON export into the body (company → business_name, city, state, phone). More relevant input yields better results. Bill-on-match. Use when: Deep research to find decision makers and their contact information for a named business.","inputSchema":{"type":"object","properties":{"business_name":{"type":"string","minLength":2,"maxLength":200,"description":"Company name — map from a CRM JSON export (e.g. company, BusinessName)."},"city":{"type":"string","maxLength":120},"state":{"type":"string","maxLength":120},"domain":{"type":"string","maxLength":255},"prompt":{"type":"string","maxLength":8000,"description":"Optional free-form research instructions. More relevant city, state, domain, and prompt input improves executive-contact and phone results."}},"required":["business_name"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string","description":"Logical route key, e.g. enrich/email."},"input":{"type":"object","description":"Normalized request input echoed back."},"matched":{"type":"boolean","description":"True when a usable vendor/LLM result was found."},"data":{"type":["object","null"],"description":"Vendor-specific payload when matched."},"vendor":{"type":["string","null"],"description":"Winning vendor key when matched."},"cache_hit":{"type":"boolean","description":"True when served from request_response_store."},"billed":{"type":"boolean","description":"False when bill-on-match refunded a no-match call."}},"required":["endpoint","input","matched","billed"]},"outputExample":{"endpoint":"enrich/websearch","input":{"business_name":"Acme Corp","city":"Tampa","state":"FL"},"matched":true,"data":{"phones":[{"number":"+18135550100","label":"main"}],"people":[{"name":"Jane Doe","title":"President","source":"https://example.com"}],"legal_associates":[{"name":"Jane Doe","role":"registered_agent","relationship":"Listed on state filing","source":"https://sos.example.gov","outreach_note":"Registered agent — prefer operational owner contact when available"}]},"vendor":"llm_websearch","cache_hit":false,"billed":true},"method":"POST","path_template":"/api/v1/enrich/websearch","body_keys":["business_name","city","state","domain","prompt"],"paid":true},{"name":"submit_enrich_job","description":"Queue async enrich routes (websearch, lead-session, slot-rerun, slot-person, slots-rerun, synthesize-patch, finding-rerun, sic-rerun) with deferred billing. With bearer: pre-charges bill_up_to_usd from virtual USD (route catalog default when omitted; max $50) → 202 + poll_bearer (billing_mode virtual_balance). Without sufficient balance / anonymous: not supported via MCP (use REST + CDP upto). Poll with get_enrich_job. Recipe: /cookbook/async_enrich_jobs.","inputSchema":{"type":"object","required":["route","payload"],"properties":{"route":{"type":"string","enum":["enrich/websearch","enrich/lead-session","enrich/lead-session/slot-rerun","enrich/lead-session/slot-person","enrich/lead-session/slots-rerun","enrich/lead-session/synthesize-patch","enrich/lead-session/finding-rerun","enrich/lead-session/sic-rerun"],"description":"Async worker route key."},"payload":{"type":"object","description":"Same JSON body as the sync enrich route."},"bill_up_to_usd":{"type":"number","minimum":0.05,"maximum":50.0,"default":1.5,"description":"Spending ceiling (default $1.50 when omitted; max $50)."},"callback_url":{"type":"string","description":"Optional HTTPS webhook for enrich.job_completed."},"idempotency_key":{"type":"string"}}},"outputSchema":{"type":"object"},"method":"POST","path_template":"/api/v1/enrich/jobs","body_keys":["route","payload","bill_up_to_usd","callback_url","idempotency_key"],"paid":true},{"name":"get_enrich_job","description":"Poll an async enrich job by job_id. Pass poll_bearer from submit_enrich_job 202 (411j_…) as poll_bearer, or rely on the session bearer when you own the job.","inputSchema":{"type":"object","required":["job_id"],"properties":{"job_id":{"type":"string","description":"ej_… from submit_enrich_job."},"poll_bearer":{"type":"string","description":"411j_… scoped token from the 202 body (preferred)."}}},"outputSchema":{"type":"object"},"method":"GET","path_template":"/api/v1/enrich/jobs/{job_id}","paid":false},{"name":"enrich_lead_session","description":"PAID ($1.500): Enrich leads with deep research: paste a CRM record as JSON in lead (one export row or [{…}] array). Finds decision makers and their contact information via directory phone/people hunt, research_web fallback, company pass. Returns summary_markdown (user-facing cited summary — show to the user with links intact) + lead_enrichment_v1 backfill JSON. Auto-persists to the audit store when phones or contacts are found (see persist block). Bill-on-match when no usable fields found. Same lead (company+address, or CRM contact_id when supplied) in a new session warm-seeds from this agent's latest persisted backfill (skips completed tools) unless refresh=true. Follow-ups: same bound lead (keep contact_id; never swap in discovered legal entity names) + prompts: [user follow-up]. refresh=true only for explicit scratch re-hunts. See cookbook lead_session_followups. Use when: Deep research on a CRM record to find decision makers and their contact information.","inputSchema":{"type":"object","properties":{"lead":{"type":"object","default":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"description":"CRM record as JSON — paste one export row (company, street, city, state, zip, number1, contact_id, …). A single-element array is accepted."},"budget_usd":{"type":"number","default":2.0,"minimum":0.05,"maximum":20.0,"description":"Hard cap on vendor tool spend inside this session (default 2.0; max 20.0 per call). Each enrichment hop (websearch, person hunt, company, …) debits against this."},"max_rounds":{"type":"integer","default":5,"minimum":1,"maximum":10,"description":"Safety cap on orchestration steps, not LLM chat turns (default 5, range 1–10). Each paid enrichment tool that runs and merges (enrich_websearch, whitepages_person_hunt, enrich_company, etc.) counts as one round. Stops when rounds >= max_rounds, spent_usd >= budget_usd, or coverage says done. Five hops covers the usual path (websearch + person hunt + company + phase-2 supplements). Leave the default for normal enrichment; raise to 10 only for deep multi-hop research with budget headroom."},"prompts":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for dig-deeper passes. Re-post the same lead with prompts: [\"…\"] to target remaining gaps."},"mode":{"type":"string","enum":["auto","interactive"],"default":"auto","description":"auto — runs end-to-end without pausing; runs enrichment tools in sequence (websearch → person hunt → company, etc.) and stops when coverage is good enough, budget is hit, or there is nothing left to try. interactive — same orchestration, but if marginal gaps remain (nice-to-have phones, owners, etc.) and budget is tight, may pause with status awaiting_user and suggested follow-up prompts instead of stopping silently. For API/MCP calls, auto is almost always what you want — one shot, full answer back. Use interactive only when your client can show dig_deeper / suggested_user_prompts and let the user send a follow-up."},"research_model":{"type":"string","description":"Optional enrichment stack id (e.g. data411-hunt-primary)"},"refresh":{"type":"boolean","description":"When true, skip agent-scoped warm-seed from prior enrichments and run a full fresh session."},"async":{"type":"boolean","description":"When true, enqueue via POST /api/v1/enrich/jobs and return 202 + job_id (recommended for hunts >90s through Cloudflare)."}},"required":["lead"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string"},"session_id":{"type":"string"},"status":{"type":"string","enum":["complete","budget_exhausted","awaiting_user","in_progress"]},"matched":{"type":"boolean"},"spent_usd":{"type":"number"},"budget_usd":{"type":"number"},"summary_markdown":{"type":"string"},"backfill":{"type":"object","description":"lead_enrichment_v1 graph"},"coverage":{"type":"object"},"dig_deeper":{"type":["object","null"]},"research_stack":{"type":"object","description":"Opaque research model ids (no upstream provider slugs).","properties":{"synthesis":{"type":"string"},"websearch":{"type":"string"}}},"billed":{"type":"boolean"},"persist":{"type":"object","description":"Auto-applied audit-store write after each session (when backfill has rows).","properties":{"applied":{"type":"boolean"},"leb_id":{"type":["integer","null"]},"session_id":{"type":"string"},"contact_id":{"type":["integer","null"]},"idempotent_replay":{"type":"boolean"},"error":{"type":"string"}}}},"required":["endpoint","session_id","status","matched","billed"]},"outputExample":{"endpoint":"enrich/lead-session","session_id":"550e8400-e29b-41d4-a716-446655440000","status":"complete","matched":true,"spent_usd":0.21,"budget_usd":2.0,"summary_markdown":"# Acme Corp\nMain line [+1-555-0100](https://example.com/contact)","backfill":{"schema_version":"1.0","phones":[],"contacts":[]},"coverage":{"must_phones_hit":2,"must_phones_total":2},"dig_deeper":null,"billed":true,"persist":{"applied":true,"leb_id":42,"session_id":"550e8400-e29b-41d4-a716-446655440000","contact_id":81555753,"idempotent_replay":false}},"method":"POST","path_template":"/api/v1/enrich/lead-session","body_keys":["lead","budget_usd","max_rounds","prompts","mode","research_model","allow_brave","prior_backfill","chat_session_id","progress_key","refresh"],"paid":true},{"name":"rerun_hunt_slot","description":"PAID ($0.350): Re-run one parallel hunt slot (Hunt Forge, Hunt Swift, Hunt Deep, Sonar, etc.) on the bound lead after a completed enrich_lead_session. Bypasses slot cache, delta-merges into prior_backfill, refreshes summary_markdown. Use instead of refresh:true full session when the user names a single slot. model_id accepts public ids (data411-hunt-forge) or provider slugs (x-ai/grok-build-0.1). See cookbook lead_session_followups. Use when: The user names one hunt slot to re-run (Hunt Forge, Hunt Swift, Hunt Deep, Sonar, …).","inputSchema":{"type":"object","properties":{"lead":{"type":"object","default":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"description":"The same bound CRM lead passed to enrich/lead-session. Keep contact_id stable; never swap in a legal entity name discovered mid-session."},"chat_session_id":{"type":"string","minLength":8,"maxLength":64,"description":"chat_session_id of the completed session whose graph is being patched."},"model_id":{"type":"string","minLength":2,"maxLength":96,"description":"Public hunt slot id (e.g. data411-hunt-forge) or provider slug. Bypasses the slot cache for this one slot."},"prior_backfill":{"type":"object","description":"Current lead_enrichment_v1 graph; loaded from the chat session when omitted."},"prompts":{"type":"array","items":{"type":"string"},"description":"Follow-up instructions to focus this pass."},"progress_key":{"type":"string","maxLength":96,"description":"Opaque key for streaming progress reads; cleared when the op finishes."},"research_model":{"type":"string","maxLength":64,"description":"Override the research model for this pass."},"refresh_summary":{"type":"boolean","default":false,"description":"Rewrite summary_markdown after the slot merge."}},"required":["lead","chat_session_id","model_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string"},"status":{"type":"string","enum":["complete","complete_partial","refused"],"description":"complete_partial — the op ran but merged no new facts."},"matched":{"type":"boolean"},"billed":{"type":"boolean","description":"False when bill-on-match auto-credited the call."},"spent_usd":{"type":"number","description":"Vendor + LLM spend attributed to this op."},"wall_time_ms":{"type":"integer"},"summary_markdown":{"type":"string"},"backfill":{"type":"object","description":"lead_enrichment_v1 graph after the merge"},"coverage":{"type":"object","description":"Gap assessment recomputed after the merge."},"research_stack":{"type":"object","description":"Opaque research model ids (no upstream provider slugs).","properties":{"synthesis":{"type":"string"},"websearch":{"type":"string"}}},"persist":{"type":"object","description":"Audit-store write applied when the merge produced rows.","properties":{"applied":{"type":"boolean"},"leb_id":{"type":["integer","null"]},"session_id":{"type":"string"},"contact_id":{"type":["integer","null"]},"idempotent_replay":{"type":"boolean"},"error":{"type":"string"}}}},"required":["endpoint","status","matched","billed"]},"outputExample":{"endpoint":"enrich/lead-session/slot-rerun","status":"complete","matched":true,"billed":true,"spent_usd":0.09,"wall_time_ms":18420,"slot_model_id":"data411-hunt-forge","slot_label":"Hunt Forge","slot_result":{"matched":true,"error":null,"latency_ms":14210},"summary_markdown":"# Haney Furniture Co\nMain line [(724) 654-7732](https://example.com/contact) — owner **James W Cole Sr**","backfill":{"schema_version":"1.0","phones":[{"number":"(724) 654-7732","label":"main","score":91}],"contacts":[{"name":"James W Cole Sr","title":"Owner"}]},"coverage":{"must_phones_hit":1,"must_phones_total":1},"persist":{"applied":true,"leb_id":42,"contact_id":81555753,"idempotent_replay":false}},"method":"POST","path_template":"/api/v1/enrich/lead-session/slot-rerun","body_keys":["lead","chat_session_id","model_id","prior_backfill","prompts","progress_key","refresh_summary"],"paid":true},{"name":"resynthesize_lead_graph","description":"PAID ($0.080): Resynthesize summary_markdown from the current lead backfill graph without vendor hunts. Cheaper than slot-rerun — use when the user only wants an updated cited summary or gap-focused prose. For structured contact pastes (Name/Phone/Email fields) to add facts, prefer enrich_lead_session with prompts — it merges user-provided contacts without web search. Use when: The user only wants an updated or gap-focused cited summary.","inputSchema":{"type":"object","properties":{"lead":{"type":"object","default":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"description":"The same bound CRM lead passed to enrich/lead-session. Keep contact_id stable; never swap in a legal entity name discovered mid-session."},"chat_session_id":{"type":"string","minLength":8,"maxLength":64,"description":"chat_session_id of the completed session whose graph is being patched."},"prior_backfill":{"type":"object","description":"lead_enrichment_v1 graph to resynthesize from. Required here — this op runs no vendor hunts, so there is nothing to rebuild from."},"prompts":{"type":"array","items":{"type":"string"},"description":"Follow-up instructions to focus this pass."},"progress_key":{"type":"string","maxLength":96,"description":"Opaque key for streaming progress reads; cleared when the op finishes."},"research_model":{"type":"string","maxLength":64,"description":"Override the research model for this pass."},"refresh_summary":{"type":"boolean","default":true},"merge_person_hunt":{"type":"boolean","default":false},"extra_directives":{"type":"string","maxLength":32000,"description":"Free-form synthesis directives appended to the prompt."}},"required":["lead","chat_session_id","prior_backfill"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string"},"status":{"type":"string","enum":["complete","complete_partial","refused"],"description":"complete_partial — the op ran but merged no new facts."},"matched":{"type":"boolean"},"billed":{"type":"boolean","description":"False when bill-on-match auto-credited the call."},"spent_usd":{"type":"number","description":"Vendor + LLM spend attributed to this op."},"wall_time_ms":{"type":"integer"},"summary_markdown":{"type":"string"},"backfill":{"type":"object","description":"lead_enrichment_v1 graph after the merge"},"coverage":{"type":"object","description":"Gap assessment recomputed after the merge."},"research_stack":{"type":"object","description":"Opaque research model ids (no upstream provider slugs).","properties":{"synthesis":{"type":"string"},"websearch":{"type":"string"}}},"persist":{"type":"object","description":"Audit-store write applied when the merge produced rows.","properties":{"applied":{"type":"boolean"},"leb_id":{"type":["integer","null"]},"session_id":{"type":"string"},"contact_id":{"type":["integer","null"]},"idempotent_replay":{"type":"boolean"},"error":{"type":"string"}}}},"required":["endpoint","status","matched","billed"]},"outputExample":{"endpoint":"enrich/lead-session/synthesize-patch","status":"complete","matched":true,"billed":true,"spent_usd":0.09,"wall_time_ms":18420,"summary_markdown":"# Haney Furniture Co\nMain line [(724) 654-7732](https://example.com/contact) — owner **James W Cole Sr**","backfill":{"schema_version":"1.0","phones":[{"number":"(724) 654-7732","label":"main","score":91}],"contacts":[{"name":"James W Cole Sr","title":"Owner"}]},"coverage":{"must_phones_hit":1,"must_phones_total":1},"persist":{"applied":true,"leb_id":42,"contact_id":81555753,"idempotent_replay":false}},"method":"POST","path_template":"/api/v1/enrich/lead-session/synthesize-patch","body_keys":["lead","chat_session_id","prior_backfill","prompts","progress_key","refresh_summary"],"paid":true},{"name":"investigate_unmerged_finding","description":"PAID ($0.300): Targeted web hunt for one unmerged_candidates row (findings withheld during merge). Pass candidate_id from backfill.unmerged_candidates[].id. Delta-merges on match; marks investigation_status on the candidate. Use when: Chasing down one backfill.unmerged_candidates[] finding withheld during merge.","inputSchema":{"type":"object","properties":{"lead":{"type":"object","default":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"description":"The same bound CRM lead passed to enrich/lead-session. Keep contact_id stable; never swap in a legal entity name discovered mid-session."},"chat_session_id":{"type":"string","minLength":8,"maxLength":64,"description":"chat_session_id of the completed session whose graph is being patched."},"candidate_id":{"type":"string","minLength":4,"maxLength":64,"description":"id from backfill.unmerged_candidates[] — the finding to investigate."},"prior_backfill":{"type":"object","description":"Current lead_enrichment_v1 graph; loaded from the chat session when omitted."},"prompts":{"type":"array","items":{"type":"string"},"description":"Follow-up instructions to focus this pass."},"progress_key":{"type":"string","maxLength":96,"description":"Opaque key for streaming progress reads; cleared when the op finishes."},"research_model":{"type":"string","maxLength":64,"description":"Override the research model for this pass."}},"required":["lead","chat_session_id","candidate_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string"},"status":{"type":"string","enum":["complete","complete_partial","refused"],"description":"complete_partial — the op ran but merged no new facts."},"matched":{"type":"boolean"},"billed":{"type":"boolean","description":"False when bill-on-match auto-credited the call."},"spent_usd":{"type":"number","description":"Vendor + LLM spend attributed to this op."},"wall_time_ms":{"type":"integer"},"summary_markdown":{"type":"string"},"backfill":{"type":"object","description":"lead_enrichment_v1 graph after the merge"},"coverage":{"type":"object","description":"Gap assessment recomputed after the merge."},"research_stack":{"type":"object","description":"Opaque research model ids (no upstream provider slugs).","properties":{"synthesis":{"type":"string"},"websearch":{"type":"string"}}},"persist":{"type":"object","description":"Audit-store write applied when the merge produced rows.","properties":{"applied":{"type":"boolean"},"leb_id":{"type":["integer","null"]},"session_id":{"type":"string"},"contact_id":{"type":["integer","null"]},"idempotent_replay":{"type":"boolean"},"error":{"type":"string"}}}},"required":["endpoint","status","matched","billed"]},"outputExample":{"endpoint":"enrich/lead-session/finding-rerun","status":"complete","matched":true,"billed":true,"spent_usd":0.09,"wall_time_ms":18420,"candidate_id":"uc_7d21f0","summary_markdown":"# Haney Furniture Co\nMain line [(724) 654-7732](https://example.com/contact) — owner **James W Cole Sr**","backfill":{"schema_version":"1.0","phones":[{"number":"(724) 654-7732","label":"main","score":91}],"contacts":[{"name":"James W Cole Sr","title":"Owner"}]},"coverage":{"must_phones_hit":1,"must_phones_total":1},"persist":{"applied":true,"leb_id":42,"contact_id":81555753,"idempotent_replay":false}},"method":"POST","path_template":"/api/v1/enrich/lead-session/finding-rerun","body_keys":["lead","chat_session_id","candidate_id","prior_backfill","prompts","progress_key"],"paid":true},{"name":"rerun_sic_classification","description":"PAID ($0.020): Re-run BLS SIC industry code classification from the current lead summary and entity graph. Replaces a prior LLM-assigned code; does not overwrite CRM-provided SIC on input_snapshot. Runs automatically at the end of new enrich sessions when no code is present. Use when: The assigned SIC code looks wrong after the graph gained new facts.","inputSchema":{"type":"object","properties":{"lead":{"type":"object","default":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"description":"The same bound CRM lead passed to enrich/lead-session. Keep contact_id stable; never swap in a legal entity name discovered mid-session."},"chat_session_id":{"type":"string","minLength":8,"maxLength":64,"description":"chat_session_id of the completed session whose graph is being patched."},"prior_backfill":{"type":"object","description":"lead_enrichment_v1 graph to classify from. Required — the classifier reads the existing summary and entity graph, it runs no hunts."},"progress_key":{"type":"string","maxLength":96,"description":"Opaque key for streaming progress reads; cleared when the op finishes."},"model_id":{"type":"string","maxLength":96,"description":"Optional SIC classifier model (default SIC_DETERMINATION_MODEL)."}},"required":["lead","chat_session_id","prior_backfill"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string"},"status":{"type":"string","enum":["complete","complete_partial","refused"],"description":"complete_partial — the op ran but merged no new facts."},"matched":{"type":"boolean"},"billed":{"type":"boolean","description":"False when bill-on-match auto-credited the call."},"spent_usd":{"type":"number","description":"Vendor + LLM spend attributed to this op."},"wall_time_ms":{"type":"integer"},"summary_markdown":{"type":"string"},"backfill":{"type":"object","description":"lead_enrichment_v1 graph after the merge"},"coverage":{"type":"object","description":"Gap assessment recomputed after the merge."},"research_stack":{"type":"object","description":"Opaque research model ids (no upstream provider slugs).","properties":{"synthesis":{"type":"string"},"websearch":{"type":"string"}}},"persist":{"type":"object","description":"Audit-store write applied when the merge produced rows.","properties":{"applied":{"type":"boolean"},"leb_id":{"type":["integer","null"]},"session_id":{"type":"string"},"contact_id":{"type":["integer","null"]},"idempotent_replay":{"type":"boolean"},"error":{"type":"string"}}}},"required":["endpoint","status","matched","billed"]},"outputExample":{"endpoint":"enrich/lead-session/sic-rerun","status":"complete","matched":true,"billed":true,"spent_usd":0.09,"wall_time_ms":18420,"sic_audit":{"sic_code":"5712","sic_description":"Furniture Stores","confidence":0.86},"summary_markdown":"# Haney Furniture Co\nMain line [(724) 654-7732](https://example.com/contact) — owner **James W Cole Sr**","backfill":{"schema_version":"1.0","phones":[{"number":"(724) 654-7732","label":"main","score":91}],"contacts":[{"name":"James W Cole Sr","title":"Owner"}]},"coverage":{"must_phones_hit":1,"must_phones_total":1},"persist":{"applied":true,"leb_id":42,"contact_id":81555753,"idempotent_replay":false}},"method":"POST","path_template":"/api/v1/enrich/lead-session/sic-rerun","body_keys":["lead","chat_session_id","prior_backfill","progress_key","model_id"],"paid":true},{"name":"lead_backfill_apply","description":"FREE with bearer — manual replay of a lead_enrichment_v1 backfill to the audit store (idempotent on lead_record_id when LEAD_RECORD_ENABLED=1). enrich_lead_session auto-persists after each run — use this only when persist.applied was false or the user supplies an offline backfill.","inputSchema":{"type":"object","properties":{"backfill":{"type":"object","description":"Exact lead_enrichment_v1 backfill from enrich_lead_session (verbatim).","required":["schema_version","session_id","lead_ref"],"properties":{"schema_version":{"type":"string","const":"1.0"},"session_id":{"type":"string"},"lead_ref":{"type":"object","required":["contact_id","source_system"],"properties":{"contact_id":{},"source_system":{"type":"string"}}}}}},"required":["backfill"]},"outputSchema":{"type":"object"},"method":"POST","path_template":"/api/v1/enrich/lead-backfill","body_keys":["backfill"],"paid":false},{"name":"submit_support_request","description":"PAID ($0.010): Open a support ticket ($0.01): creates a Support chat in session history for bugs, billing, and account questions. Bug reports (category bug) earn $1.00 virtual USD after operator confirmation. After success, run cookbook triage (connect_wizards) before escalating to a human. Use when: User asks to file a bug, contact support, or report a billing/account issue..","inputSchema":{"type":"object","properties":{"category":{"type":"string","enum":["bug","billing","account","other"]},"subject":{"type":"string","minLength":3,"maxLength":120},"body":{"type":"string","minLength":10,"maxLength":8000},"source_session_id":{"type":"string","maxLength":64,"description":"Optional enrich chat session_id where the issue occurred."}},"required":["category","subject","body"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"endpoint":{"type":"string"},"matched":{"type":"boolean"},"billed":{"type":"boolean"},"support_session_id":{"type":"string"},"support_status":{"type":"string"},"category":{"type":"string"},"subject":{"type":"string"},"open_url":{"type":"string"},"triage_recommended":{"type":"boolean"}}},"outputExample":{"endpoint":"support/tickets","matched":true,"billed":true,"support_session_id":"a1b2c3d4e5f6789012345678abcdef01","support_status":"open","category":"billing","subject":"Cannot top up virtual balance","open_url":"/demo?session=a1b2c3d4e5f6789012345678abcdef01","triage_recommended":true},"method":"POST","path_template":"/api/v1/support/tickets","body_keys":["category","subject","body","source_session_id"],"paid":true},{"name":"export_profiles_list","description":"FREE with bearer — your reusable export destination schemas with their current columns, instructions, and settings. Destination columns are caller-defined: never assume a column vocabulary. First call seeds two starter profiles. Recipe: /cookbook/custom_export_builder.","inputSchema":{"type":"object","properties":{}},"outputSchema":{"type":"object","properties":{"profiles":{"type":"array","items":{"type":"object","properties":{"profile_id":{"type":["integer","null"]},"agent_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"slug":{"type":["string","null"]},"current_version":{"type":"integer"},"version":{"type":["integer","null"]},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Destination header, used verbatim in the CSV."},"hint":{"type":"string","description":"Free-text guidance for the mapper; no fixed vocabulary."},"source":{"type":"string","description":"Free-text preference passed to the mapper (starters use `either` / `leb`)."},"order":{"type":"integer","description":"CSV position. Excluded from mapping_hash, so reordering is free."}},"required":["name"]}},"columns_json":{"type":["string","null"]},"instructions":{"type":["string","null"],"description":"Free-text mapping instructions; part of mapping_hash."},"settings":{"type":"object","additionalProperties":true,"description":"`hints` (provider names, e.g. dm_phone_rank) plus CSV output settings: delimiter, include_header, encoding, null_as, line_ending, quoting."},"settings_json":{"type":["string","null"]},"sample_row_json":{"type":["string","null"]},"model_id":{"type":["string","null"],"description":"Row-mapper model; part of mapping_hash."},"created_utc":{"type":["string","null"]},"updated_utc":{"type":["string","null"]},"version_created_utc":{"type":["string","null"]},"deleted_at":{"type":["string","null"]}}}}},"required":["profiles"]},"method":"GET","path_template":"/api/v1/export/profiles","paid":false},{"name":"export_profile_create","description":"FREE with bearer — create an empty export profile shell (201). Add columns and instructions with export_profile_save_version.","inputSchema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"slug":{"type":"string","maxLength":80,"description":"Lowercase [a-z0-9] first char then [a-z0-9_-], 2–79 chars; derived from name when omitted."}}},"outputSchema":{"type":"object","properties":{"profile_id":{"type":["integer","null"]},"agent_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"slug":{"type":["string","null"]},"current_version":{"type":"integer"},"version":{"type":["integer","null"]},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Destination header, used verbatim in the CSV."},"hint":{"type":"string","description":"Free-text guidance for the mapper; no fixed vocabulary."},"source":{"type":"string","description":"Free-text preference passed to the mapper (starters use `either` / `leb`)."},"order":{"type":"integer","description":"CSV position. Excluded from mapping_hash, so reordering is free."}},"required":["name"]}},"columns_json":{"type":["string","null"]},"instructions":{"type":["string","null"],"description":"Free-text mapping instructions; part of mapping_hash."},"settings":{"type":"object","additionalProperties":true,"description":"`hints` (provider names, e.g. dm_phone_rank) plus CSV output settings: delimiter, include_header, encoding, null_as, line_ending, quoting."},"settings_json":{"type":["string","null"]},"sample_row_json":{"type":["string","null"]},"model_id":{"type":["string","null"],"description":"Row-mapper model; part of mapping_hash."},"created_utc":{"type":["string","null"]},"updated_utc":{"type":["string","null"]},"version_created_utc":{"type":["string","null"]},"deleted_at":{"type":["string","null"]}}},"method":"POST","path_template":"/api/v1/export/profiles","body_keys":["name","slug"],"paid":false},{"name":"export_profile_save_version","description":"FREE with bearer — publish a new immutable version of an export profile's columns, instructions, settings, and mapper model (201). Column set, hints, instructions, and model form the mapping_hash that makes re-exports free; column order and CSV output settings are excluded, so reordering costs nothing.","inputSchema":{"type":"object","required":["profile_id","columns"],"properties":{"profile_id":{"type":"integer"},"columns":{"type":"array","minItems":1,"description":"Destination columns, capped at EXPORT_PROFILE_MAX_COLUMNS (default 200).","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"CSV header, used verbatim."},"hint":{"type":"string","description":"Free-text guidance for the mapper."},"source":{"type":"string","description":"Free-text preference, e.g. either or leb."},"source_ref":{"type":"string","description":"Makes this a PASSTHROUGH column: copied from this dotted path at assembly time and never sent to the model. Use leb.<path> for a stock lead-graph column (see export_stock_columns), or source.<field> for an uploaded-row field. Excluded from mapping_hash and from the price band, so adding one bumps the profile version yet costs nothing and keeps already-mapped rows cached."},"order":{"type":"integer","description":"CSV position; excluded from mapping_hash."}}}},"instructions":{"type":"string","maxLength":20000,"description":"Free-text mapping rules. Say 'unknown values must be null'."},"settings":{"type":"object","description":"hints: [\"dm_phone_rank\"] offers the mapper ranked phone candidates; plus delimiter, include_header, encoding, null_as, line_ending, quoting. share_link_column names an extra column holding a never-expiring PUBLIC per-lead share URL (no code needed at download). magic_link_column names one holding a single file-wide magic link, which only appears when download.csv is called with ?magic_code=."},"sample_row":{"type":"object"},"model_id":{"type":"string","maxLength":128}}},"outputSchema":{"type":"object","properties":{"profile_id":{"type":["integer","null"]},"agent_id":{"type":["integer","null"]},"name":{"type":["string","null"]},"slug":{"type":["string","null"]},"current_version":{"type":"integer"},"version":{"type":["integer","null"]},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Destination header, used verbatim in the CSV."},"hint":{"type":"string","description":"Free-text guidance for the mapper; no fixed vocabulary."},"source":{"type":"string","description":"Free-text preference passed to the mapper (starters use `either` / `leb`)."},"order":{"type":"integer","description":"CSV position. Excluded from mapping_hash, so reordering is free."}},"required":["name"]}},"columns_json":{"type":["string","null"]},"instructions":{"type":["string","null"],"description":"Free-text mapping instructions; part of mapping_hash."},"settings":{"type":"object","additionalProperties":true,"description":"`hints` (provider names, e.g. dm_phone_rank) plus CSV output settings: delimiter, include_header, encoding, null_as, line_ending, quoting."},"settings_json":{"type":["string","null"]},"sample_row_json":{"type":["string","null"]},"model_id":{"type":["string","null"],"description":"Row-mapper model; part of mapping_hash."},"created_utc":{"type":["string","null"]},"updated_utc":{"type":["string","null"]},"version_created_utc":{"type":["string","null"]},"deleted_at":{"type":["string","null"]}}},"method":"POST","path_template":"/api/v1/export/profiles/{profile_id}/versions","body_keys":["columns","instructions","settings","sample_row","model_id"],"paid":false},{"name":"export_stock_columns","description":"FREE with bearer — the flattened lead-graph columns available for an enriched batch, i.e. the columns its stock CSV download would have, each with a sample value and how many sampled rows carry one. Store a returned source_ref on a profile column to copy that value instead of asking the model for it: that is excluded from mapping_hash, so adding one never re-bills an already-mapped file. A lead graph is sparse, so a path missing here may exist on a row outside the sample. Recipe: /cookbook/custom_export_builder.","inputSchema":{"type":"object","required":["batch_id"],"properties":{"batch_id":{"type":"string","minLength":3,"maxLength":64},"sample_rows":{"type":"integer","minimum":1,"maximum":100,"description":"Enriched rows to flatten (default 25)."}}},"outputSchema":{"type":"object","properties":{"batch_id":{"type":"string"},"rows_scanned":{"type":"integer","description":"Enriched rows flattened to build this list. A lead graph is sparse, so a path missing here may still exist on a row outside the sample."},"columns":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Flattened lead-graph path, as named in the stock batch CSV."},"source_ref":{"type":"string","description":"Store this on a profile column as `source_ref` to copy the value at assembly time instead of asking the model for it."},"sample":{"type":["string","null"],"description":"First non-empty value seen, clipped to 160 chars."},"non_empty_rows":{"type":"integer","description":"Sampled rows carrying a value, for judging how populated a path is."}}}}},"required":["columns"]},"method":"GET","path_template":"/api/v1/export/columns/stock","paid":false},{"name":"export_columns_derive","description":"FREE with bearer — turn a pasted destination sample into column descriptors: a header array, one record, an array of records (keys unioned), or {name, hint} descriptors. Nothing is saved; pass the result to export_profile_save_version.","inputSchema":{"type":"object","properties":{"sample":{"description":"JSON object or array. Required unless headers is set."},"headers":{"type":"array","items":{"type":"string"}}}},"outputSchema":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Destination header, used verbatim in the CSV."},"hint":{"type":"string","description":"Free-text guidance for the mapper; no fixed vocabulary."},"source":{"type":"string","description":"Free-text preference passed to the mapper (starters use `either` / `leb`)."},"order":{"type":"integer","description":"CSV position. Excluded from mapping_hash, so reordering is free."}},"required":["name"]}},"column_count":{"type":"integer"},"max_columns":{"type":"integer","description":"EXPORT_PROFILE_MAX_COLUMNS (default 200)."}},"required":["columns","column_count"]},"method":"POST","path_template":"/api/v1/export/profiles/derive","body_keys":["sample","headers"],"paid":false},{"name":"export_run_estimate","description":"FREE with bearer — quote an export mapping run: per_lead_usd, rows_billable, total_usd, mapping_hash, and shortfall_usd + topup_url when the balance is short. rows_cached rows cost $0.00; is_rebuild=true means the whole run is free. Quote with the same file_instructions you will submit — they feed the mapping_hash. Always call this before export_run_submit.","inputSchema":{"type":"object","properties":{"batch_id":{"type":"string","minLength":5,"maxLength":40},"profile_id":{"type":"integer"},"profile_version":{"type":"integer","description":"Defaults to the profile's current version."},"scope_kind":{"type":"string","default":"all","description":"all | row_list | rebuild | filter. Supplying `rows` promotes `all` to `row_list`; anything unrecognised takes the quality-filter path."},"rows":{"type":"string","description":"Row indexes, e.g. 0,3,7."},"parent_run_id":{"type":"integer","description":"Required by every quality filter and by scope_kind=rebuild."},"remap_changed_leads":{"type":"boolean","default":false},"file_instructions":{"type":"string","description":"Per-file instructions appended to the profile's; part of mapping_hash."},"degraded":{"type":"boolean","default":false},"guard_flagged":{"type":"boolean","default":false},"errored":{"type":"boolean","default":false},"low_confidence":{"type":"boolean","default":false},"min_confidence":{"type":"number","minimum":0.0,"maximum":1.0,"description":"Threshold for low_confidence (default 0.7)."},"column_empty":{"type":"boolean","default":false},"empty_columns":{"type":"array","items":{"type":"string"},"description":"Repeated (`?empty_columns=a&empty_columns=b`) destination column names for column_empty — a user-defined column name may itself contain a comma. Omit to mean \"the row produced nothing at all\"; this API never guesses column names."},"hint_disagreement":{"type":"boolean","default":false},"profile_version_lt":{"type":"integer","minimum":1}},"required":["batch_id","profile_id"]},"outputSchema":{"type":"object","properties":{"per_lead_usd":{"type":"number","description":"Sell price for one mapped row in this price band."},"rows_in_scope":{"type":"integer"},"rows_matched":{"type":"integer"},"rows_with_raw":{"type":"integer","description":"In-scope rows carrying an uploaded source row (attach-raw)."},"rows_eligible":{"type":"integer","description":"In-scope rows whose enrichment finished (matched or no_match)."},"rows_cached":{"type":"integer","description":"Eligible rows already paid for under this mapping_hash — always $0.00."},"rows_leb_changed":{"type":"integer"},"rows_billable":{"type":"integer","description":"Rows that still need an LLM mapping."},"total_usd":{"type":"number","description":"per_lead_usd × rows_billable."},"is_rebuild":{"type":"boolean","description":"True when every eligible row is cached, so the run costs nothing."},"column_count":{"type":"integer"},"price_band":{"type":"string","description":"export/row-map | export/row-map/standard | export/row-map/wide (by column count)."},"virtual_balance_usd":{"type":["number","null"]},"shortfall_usd":{"type":"number"},"topup_url":{"type":["string","null"],"description":"Prepay wizard URL when balance is short."},"mapping_hash":{"type":"string","description":"Mapping identity: column set (name/hint/source) + instructions + hint providers + model. Excludes profile_id, version, column order, and output settings."}}},"method":"GET","path_template":"/api/v1/export/runs/estimate","query_params":["batch_id","profile_id","profile_version","scope_kind","rows","parent_run_id","remap_changed_leads","file_instructions","degraded","guard_flagged","errored","low_confidence","min_confidence","column_empty","empty_columns","hint_disagreement","profile_version_lt"],"paid":false},{"name":"export_run_submit","description":"PAID per billable row (export/row-map band: $0.015, $0.025 above 40 columns, $0.040 above 80) — debited from virtual USD balance first; the wallet is never charged while virtual credit remains, and a 402 body carries topup_url. Precharges at submit and refunds the unused remainder on settle or cancel. Rows already mapped under the same mapping_hash cost $0.00, so a re-export of the same leads with the same mapping semantics is free (scope_kind=rebuild). Poll export_run_get, review with export_run_rows, download the CSV at GET /api/v1/export/runs/{run_id}/download.csv (free). Recipe: /cookbook/custom_export_builder.","inputSchema":{"type":"object","required":["batch_id","profile_id"],"properties":{"batch_id":{"type":"string","description":"Enriched batch (be_…)."},"profile_id":{"type":"integer"},"profile_version":{"type":"integer","description":"Defaults to the profile's current version."},"scope_kind":{"type":"string","enum":["all","row_list","rebuild","filter"],"default":"all","description":"row_list reads scope_json; rebuild replays parent_run_id's rows."},"scope_json":{"type":"array","items":{"type":"integer"},"description":"row_index values for scope_kind=row_list."},"parent_run_id":{"type":"integer","description":"Run this one is judged against. Its out-of-scope rows carry forward free so a scoped re-run still downloads complete."},"remap_changed_leads":{"type":"boolean","default":false},"file_instructions":{"type":"string","description":"Per-file instructions appended to the profile's; part of mapping_hash."},"skip_no_match":{"type":"boolean","default":false},"filters":{"type":"object","description":"Re-run subset selectors, OR-ed, judged against parent_run_id's rows. Any of them without parent_run_id returns 400 PARENT_RUN_REQUIRED. A filtered re-run always bills.","properties":{"degraded":{"type":"boolean"},"guard_flagged":{"type":"boolean"},"errored":{"type":"boolean"},"low_confidence":{"type":"boolean"},"min_confidence":{"type":"number","minimum":0.0,"maximum":1.0},"column_empty":{"type":"boolean"},"empty_columns":{"type":"array","items":{"type":"string"}},"hint_disagreement":{"type":"boolean"},"profile_version_lt":{"type":"integer","minimum":1}}}}},"outputSchema":{"type":"object","properties":{"run_id":{"type":"integer"},"status":{"type":"string","description":"queued | running | completed | failed | cancelled | paused_balance."},"scope_kind":{"type":"string"},"estimate":{"type":"object","properties":{"per_lead_usd":{"type":"number","description":"Sell price for one mapped row in this price band."},"rows_in_scope":{"type":"integer"},"rows_matched":{"type":"integer"},"rows_with_raw":{"type":"integer","description":"In-scope rows carrying an uploaded source row (attach-raw)."},"rows_eligible":{"type":"integer","description":"In-scope rows whose enrichment finished (matched or no_match)."},"rows_cached":{"type":"integer","description":"Eligible rows already paid for under this mapping_hash — always $0.00."},"rows_leb_changed":{"type":"integer"},"rows_billable":{"type":"integer","description":"Rows that still need an LLM mapping."},"total_usd":{"type":"number","description":"per_lead_usd × rows_billable."},"is_rebuild":{"type":"boolean","description":"True when every eligible row is cached, so the run costs nothing."},"column_count":{"type":"integer"},"price_band":{"type":"string","description":"export/row-map | export/row-map/standard | export/row-map/wide (by column count)."},"virtual_balance_usd":{"type":["number","null"]},"shortfall_usd":{"type":"number"},"topup_url":{"type":["string","null"],"description":"Prepay wizard URL when balance is short."},"mapping_hash":{"type":"string","description":"Mapping identity: column set (name/hint/source) + instructions + hint providers + model. Excludes profile_id, version, column order, and output settings."}}},"row_count":{"type":"integer"},"rows_billable":{"type":"integer"},"rows_cached":{"type":"integer"},"rows_carried_forward":{"type":"integer","description":"Rows copied from parent_run_id. Never billed."},"precharged_usd":{"type":"number","description":"Virtual USD debited at submit; unused amounts are refunded on settle or cancel."},"virtual_balance_usd":{"type":["number","null"]}},"required":["run_id","status"]},"method":"POST","path_template":"/api/v1/export/runs","body_keys":["batch_id","profile_id","profile_version","scope_kind","scope_json","parent_run_id","remap_changed_leads","file_instructions","skip_no_match","filters"],"paid":false},{"name":"export_run_preview","description":"PAID per cache-miss row at the same per-row price as a run — debited from virtual USD balance first, wallet x402 only once that balance is exhausted. Maps 1–5 rows and returns each cell beside the deterministic hint ranking (hint_rank null = the ranker never offered that value). Cache hits are free; misses are banked to the map cache so the later full run does not re-charge them, and degraded rows are refunded. Use to sanity-check instructions before paying for the whole file. ASYNC: rows map in parallel but one row can take over a minute, so this returns a preview_id — poll export_preview_get until status is completed. Only a fully cached preview returns the result inline.","inputSchema":{"type":"object","required":["batch_id","profile_id"],"properties":{"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"profile_version":{"type":"integer"},"file_instructions":{"type":"string"},"row_limit":{"type":"integer","minimum":1,"maximum":5,"default":3}}},"outputSchema":{"type":"object","properties":{"preview_id":{"type":"string","description":"Handle to poll at GET /api/v1/export/runs/preview/{preview_id}. Absent when every requested row was already cached, in which case the reply is the finished result and there is nothing to poll."},"status":{"type":"string","description":"running | completed | error. 202 means running; poll until completed."},"poll_url":{"type":["string","null"]},"previews":{"type":"array","items":{"type":"object","properties":{"row_index":{"type":"integer"},"cached":{"type":"boolean","description":"True when the mapping was already paid for ($0.00)."},"degraded":{"type":"boolean","description":"Mapper produced nothing usable; the row is refunded."},"guard_flags":{"type":"array","items":{"type":"string"}},"confidence":{"type":["number","null"]},"cells":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"llm_value":{"description":"Mapped value, or null."},"hint_value":{"type":["string","null"],"description":"Top-ranked hint candidate, if any."},"hint_rank":{"type":["integer","null"],"description":"1-based rank of llm_value in a hint list; null means the ranker never offered it."},"rationale":{"type":["string","null"]}},"required":["column"]}},"hints":{"type":"object","additionalProperties":true}},"required":["row_index","cells"]},"description":"Rows finished so far, ordered by row_index. On a 202 this holds only the cache hits; mapped rows appear as the job progresses."},"column_count":{"type":"integer"},"rows_total":{"type":"integer"},"rows_done":{"type":"integer","description":"Rows available in `previews` right now."},"rows_cached":{"type":"integer"},"rows_billable":{"type":"integer","description":"Cache-miss rows precharged."},"rows_billed":{"type":"integer","description":"Cache-miss rows charged, minus refunded degraded rows."},"per_lead_usd":{"type":"number"},"charged_usd":{"type":"number","description":"Virtual USD kept after degraded-row refunds."},"virtual_balance_usd":{"type":["number","null"]},"detail":{"type":["string","null"],"description":"Set when status is error."}},"required":["previews"]},"method":"POST","path_template":"/api/v1/export/runs/preview","body_keys":["batch_id","profile_id","profile_version","file_instructions","row_limit"],"paid":false},{"name":"export_preview_get","description":"FREE with bearer — poll a preview started by export_run_preview (the mapping is already paid for). Returns status (running | completed | error), rows_done / rows_total, and the rows finished so far ordered by row_index. Kept for one hour after it finishes, then 404.","inputSchema":{"type":"object","properties":{"preview_id":{"type":"string","minLength":8,"maxLength":64}},"required":["preview_id"]},"outputSchema":{"type":"object","properties":{"preview_id":{"type":"string","description":"Handle to poll at GET /api/v1/export/runs/preview/{preview_id}. Absent when every requested row was already cached, in which case the reply is the finished result and there is nothing to poll."},"status":{"type":"string","description":"running | completed | error. 202 means running; poll until completed."},"poll_url":{"type":["string","null"]},"previews":{"type":"array","items":{"type":"object","properties":{"row_index":{"type":"integer"},"cached":{"type":"boolean","description":"True when the mapping was already paid for ($0.00)."},"degraded":{"type":"boolean","description":"Mapper produced nothing usable; the row is refunded."},"guard_flags":{"type":"array","items":{"type":"string"}},"confidence":{"type":["number","null"]},"cells":{"type":"array","items":{"type":"object","properties":{"column":{"type":"string"},"llm_value":{"description":"Mapped value, or null."},"hint_value":{"type":["string","null"],"description":"Top-ranked hint candidate, if any."},"hint_rank":{"type":["integer","null"],"description":"1-based rank of llm_value in a hint list; null means the ranker never offered it."},"rationale":{"type":["string","null"]}},"required":["column"]}},"hints":{"type":"object","additionalProperties":true}},"required":["row_index","cells"]},"description":"Rows finished so far, ordered by row_index. On a 202 this holds only the cache hits; mapped rows appear as the job progresses."},"column_count":{"type":"integer"},"rows_total":{"type":"integer"},"rows_done":{"type":"integer","description":"Rows available in `previews` right now."},"rows_cached":{"type":"integer"},"rows_billable":{"type":"integer","description":"Cache-miss rows precharged."},"rows_billed":{"type":"integer","description":"Cache-miss rows charged, minus refunded degraded rows."},"per_lead_usd":{"type":"number"},"charged_usd":{"type":"number","description":"Virtual USD kept after degraded-row refunds."},"virtual_balance_usd":{"type":["number","null"]},"detail":{"type":["string","null"],"description":"Set when status is error."}},"required":["previews"]},"method":"GET","path_template":"/api/v1/export/runs/preview/{preview_id}","paid":false},{"name":"export_runs_list","description":"FREE with bearer — your export runs, newest first, optionally filtered by batch_id. Carries status, row counts, price_band, precharged_usd, settled_usd.","inputSchema":{"type":"object","properties":{"batch_id":{"type":"string","minLength":5,"maxLength":40}},"required":[]},"outputSchema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"integer"},"agent_id":{"type":"integer"},"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"profile_version":{"type":"integer"},"mapping_hash":{"type":"string"},"status":{"type":"string","description":"queued | running | completed | failed | cancelled | paused_balance."},"scope_kind":{"type":"string","description":"all | row_list | rebuild | filter (rebuild is stamped by a free re-export)."},"scope_json":{"type":["string","null"],"description":"JSON text as stored."},"parent_run_id":{"type":["integer","null"]},"row_count":{"type":"integer","description":"Rows in the downloadable file, carried-forward included."},"rows_done":{"type":"integer"},"rows_error":{"type":"integer"},"rows_cached":{"type":"integer"},"rows_billable":{"type":"integer","description":"Billable scope size stamped at submit."},"rows_billed":{"type":"integer","description":"Rows actually LLM-mapped, used at settlement."},"price_band":{"type":"string"},"per_lead_usd":{"type":"number"},"precharged_usd":{"type":"number"},"settled_usd":{"type":"number"},"remap_changed_leads":{"type":["boolean","integer"]},"worker_id":{"type":["string","null"]},"lease_expires_utc":{"type":["string","null"]},"created_utc":{"type":["string","null"]},"started_utc":{"type":["string","null"]},"completed_utc":{"type":["string","null"]},"settled_utc":{"type":["string","null"],"description":"Set once; guards double refunds."}}}}},"required":["runs"]},"method":"GET","path_template":"/api/v1/export/runs","query_params":["batch_id"],"paid":false},{"name":"export_run_get","description":"FREE with bearer — poll one export run. Terminal at completed, failed, or cancelled; paused_balance means the worker stopped for want of virtual USD and resumes after a top-up. CSV: GET /api/v1/export/runs/{run_id}/download.csv.","inputSchema":{"type":"object","properties":{"run_id":{"type":"integer"}},"required":["run_id"]},"outputSchema":{"type":"object","properties":{"run_id":{"type":"integer"},"agent_id":{"type":"integer"},"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"profile_version":{"type":"integer"},"mapping_hash":{"type":"string"},"status":{"type":"string","description":"queued | running | completed | failed | cancelled | paused_balance."},"scope_kind":{"type":"string","description":"all | row_list | rebuild | filter (rebuild is stamped by a free re-export)."},"scope_json":{"type":["string","null"],"description":"JSON text as stored."},"parent_run_id":{"type":["integer","null"]},"row_count":{"type":"integer","description":"Rows in the downloadable file, carried-forward included."},"rows_done":{"type":"integer"},"rows_error":{"type":"integer"},"rows_cached":{"type":"integer"},"rows_billable":{"type":"integer","description":"Billable scope size stamped at submit."},"rows_billed":{"type":"integer","description":"Rows actually LLM-mapped, used at settlement."},"price_band":{"type":"string"},"per_lead_usd":{"type":"number"},"precharged_usd":{"type":"number"},"settled_usd":{"type":"number"},"remap_changed_leads":{"type":["boolean","integer"]},"worker_id":{"type":["string","null"]},"lease_expires_utc":{"type":["string","null"]},"created_utc":{"type":["string","null"]},"started_utc":{"type":["string","null"]},"completed_utc":{"type":["string","null"]},"settled_utc":{"type":["string","null"],"description":"Set once; guards double refunds."}}},"method":"GET","path_template":"/api/v1/export/runs/{run_id}","paid":false},{"name":"export_run_rows","description":"FREE with bearer — paged mapped rows in row_index order. output_json is keyed by your destination column names; guard_flags_json marks values the no-invention validator nulled. Cell overrides are applied at CSV assembly, so they are deliberately absent here. limit is clamped to 500.","inputSchema":{"type":"object","properties":{"run_id":{"type":"integer"},"offset":{"type":"integer","default":0,"minimum":0},"limit":{"type":"integer","default":100,"maximum":500}},"required":["run_id"]},"outputSchema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"run_id":{"type":"integer"},"row_index":{"type":"integer","description":"Batch row index; stable across runs of the same file."},"status":{"type":"string","description":"pending | running | done | cached | degraded | error | cancelled. `cached` and carried-forward `done` rows were never billed by this run."},"output_json":{"type":["string","null"],"description":"JSON text keyed by destination column name. Overrides never mutate it."},"hints_json":{"type":["string","null"],"description":"JSON text: ranked candidate lists the mapper was offered."},"llm_cost_usd":{"type":["number","null"]},"model_id":{"type":["string","null"]},"error_code":{"type":["string","null"]},"guard_flags_json":{"type":["string","null"],"description":"JSON array; `invented_*` entries mark values the no-invention validator nulled."},"confidence":{"type":["number","null"]},"carried_forward":{"type":["boolean","integer"]},"running_since_utc":{"type":["string","null"]},"processed_utc":{"type":["string","null"]},"worker_id":{"type":["string","null"]},"lease_expires_utc":{"type":["string","null"]}}}},"offset":{"type":"integer"},"limit":{"type":"integer","description":"Clamped to 500."}},"required":["rows"]},"method":"GET","path_template":"/api/v1/export/runs/{run_id}/rows","query_params":["offset","limit"],"paid":false},{"name":"export_run_cancel","description":"FREE with bearer — cancel a queued or running export run and refund the unused precharge (precharged_usd − settled_usd) to virtual USD. Rows already mapped stay downloadable.","inputSchema":{"type":"object","required":["run_id"],"properties":{"run_id":{"type":"integer"}}},"outputSchema":{"type":"object","properties":{"run_id":{"type":"integer"},"agent_id":{"type":"integer"},"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"profile_version":{"type":"integer"},"mapping_hash":{"type":"string"},"status":{"type":"string","description":"queued | running | completed | failed | cancelled | paused_balance."},"scope_kind":{"type":"string","description":"all | row_list | rebuild | filter (rebuild is stamped by a free re-export)."},"scope_json":{"type":["string","null"],"description":"JSON text as stored."},"parent_run_id":{"type":["integer","null"]},"row_count":{"type":"integer","description":"Rows in the downloadable file, carried-forward included."},"rows_done":{"type":"integer"},"rows_error":{"type":"integer"},"rows_cached":{"type":"integer"},"rows_billable":{"type":"integer","description":"Billable scope size stamped at submit."},"rows_billed":{"type":"integer","description":"Rows actually LLM-mapped, used at settlement."},"price_band":{"type":"string"},"per_lead_usd":{"type":"number"},"precharged_usd":{"type":"number"},"settled_usd":{"type":"number"},"remap_changed_leads":{"type":["boolean","integer"]},"worker_id":{"type":["string","null"]},"lease_expires_utc":{"type":["string","null"]},"created_utc":{"type":["string","null"]},"started_utc":{"type":["string","null"]},"completed_utc":{"type":["string","null"]},"settled_utc":{"type":["string","null"],"description":"Set once; guards double refunds."}}},"method":"POST","path_template":"/api/v1/export/runs/{run_id}/cancel","paid":false},{"name":"export_overrides_list","description":"FREE with bearer — active cell overrides for a batch, optionally narrowed to one profile.","inputSchema":{"type":"object","properties":{"batch_id":{"type":"string","minLength":5,"maxLength":40},"profile_id":{"type":"integer"}},"required":["batch_id"]},"outputSchema":{"type":"object","properties":{"overrides":{"type":"array","items":{"type":"object","properties":{"override_id":{"type":"integer"},"agent_id":{"type":"integer"},"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"scope":{"type":"string","description":"row | file. File scope applies to every row."},"row_index":{"type":["integer","null"],"description":"Required for scope=row; always null for file."},"column_name":{"type":"string"},"mode":{"type":"string","description":"literal (human-typed value; counted in X-411data-Human-Literal-Cells) | source_ref (lead.* / source.* / hints.* dotted path) | clear (force empty)."},"value_text":{"type":["string","null"]},"source_ref":{"type":["string","null"]},"created_utc":{"type":["string","null"]},"created_by_key_id":{"type":["integer","null"]},"revoked_at":{"type":["string","null"],"description":"Set on revoke or replacement; a revoked override restores the mapper's value."}}}}},"required":["overrides"]},"method":"GET","path_template":"/api/v1/export/overrides","query_params":["batch_id","profile_id"],"paid":false},{"name":"export_overrides_set","description":"FREE with bearer — upsert up to 500 durable cell overrides (201). No LLM call and no re-run needed. CSV assembly precedence is a contract: row override, then file override, then the mapper's output_json, then empty. output_json is never mutated, so revoking restores the mapped value. literal values are human-typed and bypass the no-invention validator, so downloads count them in the X-411data-Human-Literal-Cells header.","inputSchema":{"type":"object","required":["overrides"],"properties":{"overrides":{"type":"array","maxItems":500,"items":{"type":"object","required":["batch_id","profile_id","scope","column_name","mode"],"properties":{"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"scope":{"type":"string","enum":["row","file"]},"row_index":{"type":"integer","description":"Required when scope=row."},"column_name":{"type":"string","maxLength":200},"mode":{"type":"string","enum":["literal","source_ref","clear"]},"value_text":{"type":"string","description":"Required when mode=literal."},"source_ref":{"type":"string","maxLength":500,"description":"Required when mode=source_ref. Dotted path under lead.*, source.*, or hints.* — e.g. hints.ranked_phones.0.e164."}}}}}},"outputSchema":{"type":"object","properties":{"overrides":{"type":"array","items":{"type":"object","properties":{"override_id":{"type":"integer"},"agent_id":{"type":"integer"},"batch_id":{"type":"string"},"profile_id":{"type":"integer"},"scope":{"type":"string","description":"row | file. File scope applies to every row."},"row_index":{"type":["integer","null"],"description":"Required for scope=row; always null for file."},"column_name":{"type":"string"},"mode":{"type":"string","description":"literal (human-typed value; counted in X-411data-Human-Literal-Cells) | source_ref (lead.* / source.* / hints.* dotted path) | clear (force empty)."},"value_text":{"type":["string","null"]},"source_ref":{"type":["string","null"]},"created_utc":{"type":["string","null"]},"created_by_key_id":{"type":["integer","null"]},"revoked_at":{"type":["string","null"],"description":"Set on revoke or replacement; a revoked override restores the mapper's value."}}}},"count":{"type":"integer"}},"required":["overrides","count"]},"method":"POST","path_template":"/api/v1/export/overrides","body_keys":["overrides"],"paid":false},{"name":"export_override_revoke","description":"FREE with bearer — revoke one cell override. The next download falls back through the precedence chain, restoring the mapper's value at no cost.","inputSchema":{"type":"object","required":["override_id"],"properties":{"override_id":{"type":"integer"}}},"outputSchema":{"type":"object","properties":{"ok":{"type":"boolean"},"override_id":{"type":"integer"}},"required":["ok","override_id"]},"method":"DELETE","path_template":"/api/v1/export/overrides/{override_id}","paid":false},{"name":"cookbook_search","description":"FREE — search cookbook recipes by intent (2–4 words). Call before paid tools or during support triage.","inputSchema":{"type":"object","properties":{"q":{"type":"string","minLength":2,"maxLength":500},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10}},"required":["q"]},"outputSchema":{"type":"object","properties":{"matches":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"score":{"type":"number"},"url":{"type":"string","description":"Relative path, e.g. /cookbook/driveout_price."},"snippet":{"type":"string"}},"required":["slug","title","score","url","snippet"]}},"q":{"type":"string"},"count":{"type":"integer"}},"required":["matches","q","count"]},"method":"GET","path_template":"/cookbook/search","query_params":["q","limit"],"paid":false},{"name":"cookbook_read","description":"FREE — read full cookbook recipe markdown by slug.","inputSchema":{"type":"object","properties":{"slug":{"type":"string","description":"Recipe slug, e.g. enrich_email or bill_on_match."}},"required":["slug"]},"outputSchema":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","description":"Relative HTML path, e.g. /cookbook/error_code_diagnostics."},"markdown":{"type":"string","description":"Full recipe source (Markdown)."}},"required":["slug","title","url","markdown"]},"method":"GET","path_template":"/cookbook/read/{slug}","paid":false},{"name":"openapi_route_lookup","description":"FREE — compact OpenAPI route index (not full openapi.json). Filter by q= for agents/keys/balance/onramp/demo paths.","inputSchema":{"type":"object","properties":{"q":{"type":"string","maxLength":200},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25}},"required":[]},"outputSchema":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer"},"routes":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"summary":{"type":"string"},"operation_id":{"type":"string"}}}}}},"method":"GET","path_template":"/api/v1/openapi/routes","query_params":["q","limit"],"paid":false},{"name":"signup_email","description":"FREE — self-serve email signup. Submit a work email and receive a single-use magic link that mints a scoped 411k_… usage key on redeem. Response is always the same whether or not the address is eligible.","inputSchema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}},"outputSchema":{"type":"object","properties":{"message":{"type":"string"},"billing_note":{"type":"string"}},"required":["message","billing_note"]},"method":"POST","path_template":"/api/v1/signup/email","body_keys":["email"],"paid":false}],"links":{"openapi":"https://411data.io/openapi.json","openapi_free":"https://411data.io/openapi-free.json","developers":"https://411data.io/developers","skill":"https://411data.io/skill.md","well_known_x402":"https://411data.io/.well-known/x402","pricing":"https://411data.io/pricing"}}