{"openapi":"3.1.0","info":{"title":"411data","version":"0.1.0","description":"Agent-native lead enrichment: email, company, phone, websearch, lead search. x402 + MCP + free trial.","contact":{"name":"411data","url":"https://411data.io/about","email":"support@411data.io"},"x-guidance":"411data is an **agent-native** lead and data enrichment API. Live paid endpoints\ncover reverse phone and person lookup, LLM web-search enrichment, and\nagentic lead-session orchestration; **bill-on-match** auto-credits when no row\nis found.\n\n**Workflow**\n1. Mint a wallet-bound agent at `/connect` ($0.20 starting virtual USD\n   balance + multi-wallet MPP support) or headless via\n   `POST /api/v1/agents/wallet-register` after SIWE.\n2. Call enrichment routes (debited from virtual balance first):\n   - `$0.330` `POST /api/v1/enrich/phone` (reverse phone lookup)\n   - `$0.500` `POST /api/v1/enrich/person` (person search)\n   - `$1.000` `POST /api/v1/enrich/websearch` (deep research → decision makers + contact info)\n   - `$1.500` base `POST /api/v1/enrich/lead-session` (+ usage true-up)\n   - Bill up to `$1.500` `POST /api/v1/enrich/jobs` (async websearch / lead-session;\n     virtual precharge with bearer or CDP upto when anonymous) + poll\n     `GET /api/v1/enrich/jobs/{job_id}` with `poll_bearer`\n   - `$1.500`/row `POST /api/v1/batch/enrich/upload` then `/start` (CSV batch lead-session;\n     optional `prefilter_lead_type` commercial/residential — see /cookbook/batch_csv_enrich)\n   - `$0.010` `POST /api/v1/support/tickets` (bug reports: $1.00 virtual credit after confirmation)\n   Catalog routes (`enrich/email`, `enrich/company`, `leads/search`) are\n   offline by default — see `GET /pricing` for the live catalogue.\n3. Pre-flight with free cookbook: `GET /cookbook/search?q=…` then\n   `GET /cookbook/read/{slug}` for worked recipes.\n\n**Free surface:** `GET /openapi-free.json` documents mint + cookbook.\nPaid catalogue: `GET /openapi.json`.\n\n**Payment:** Every billed call FIRST debits your agent's virtual USD\nbalance; the x402 v2 challenge only fires after the balance is exhausted.\nThe server runs the official `x402[fastapi,evm]` Python SDK — envelopes\nfollow the canonical v2 spec (base64 `payment-required:` header carrying\n`accepts[]` with CAIP-2 networks like `eip155:8453` and atomic-units\n`amount` strings like `\"10000\"` for $0.010 USDC, plus\n`extensions.411data-mpp` and `extensions.bazaar` for wallet allowance +\nJSON Schemas). Settle by signing an EIP-3009 `TransferWithAuthorization`\nto the listed `payTo` and retrying with `X-PAYMENT: <base64>`. After-settle\nreceipts arrive in the `payment-response: <base64>` header. Catalogue:\n`GET /.well-known/x402`. Bazaar-style discovery for facilitator indexers:\n`GET /discovery/resources`.\n","x-411data-free-openapi":"https://411data.io/openapi-free.json","x-rate-limits":{"policy":"edge-only","layers":[{"id":"cloudflare","type":"zone-burst"},{"id":"nginx","type":"limit_req"}],"retry_header":"Retry-After","in_app_quota":"none — virtual USD balance is the spend control","docs":"https://411data.io/developers#rate-limits"},"x-llm-recipes":[{"id":"enrich_phone","goal":"Reverse-lookup enrichment from a phone number.","steps":["POST /api/v1/enrich/phone with {\"phone\": \"+17242060094\"} (E.164 preferred).","Same person-search backend as enrich/person with phone-only input.","If `matched == false`, the call is auto-credited (bill-on-match)."],"cost_usd":"$0.330 per call (debited from virtual balance first)."},{"id":"enrich_person","goal":"Person/residential lookup (phones, emails, addresses).","steps":["POST /api/v1/enrich/person with name + location, or reverse phone.","Example: {\"name\": \"John Smith\", \"state_code\": \"PA\", \"zipcode\": \"15213\"}."],"cost_usd":"$0.500 per call."},{"id":"enrich_websearch","goal":"Deep research to find decision makers and their contact information for a business.","steps":["POST /api/v1/enrich/websearch — map CRM JSON fields into {\"business_name\": \"Acme Corp\", \"city\": \"Tampa\", \"state\": \"FL\"}.","Returns phones, executive names/titles, addresses, and legal_associates with source URLs."],"cost_usd":"$1.000 per call (bill-on-match)."},{"id":"enrich_lead_session","goal":"Deep research on a CRM lead — find decision makers and their contact information.","steps":["POST /api/v1/enrich/lead-session — paste a CRM record as JSON in lead (one row or [{…}]).","Example: {\"lead\": {\"company\": \"Acme Corp\", \"number1\": \"4125550100\"}, \"budget_usd\": 2.0, \"max_rounds\": 5, \"mode\": \"auto\"}.","mode auto (default): one-shot end-to-end through websearch → person hunt → company; interactive pauses with awaiting_user when marginal gaps remain.","max_rounds (default 5): safety cap on tool hops, not chat turns — each paid tool = one round.","For API/MCP calls, auto is almost always what you want.","Returns cited summary_markdown plus backfill JSON with phones, owners, and source links.","Bill-on-match refunds when no usable enrichment fields are found."],"cost_usd":"$1.500 per session (bill-on-match)."},{"id":"async_enrich_jobs","goal":"Run websearch or lead-session without holding an HTTP connection open.","steps":["POST /api/v1/enrich/jobs with route enrich/websearch or enrich/lead-session.","bill_up_to_usd defaults to $1.50 when omitted; override up to $50.","Bearer path: 202 + poll_bearer; virtual USD pre-charged up to bill_up_to_usd.","Anonymous path: 402 CDP upto → PAYMENT-SIGNATURE → 202 → poll.","GET /api/v1/enrich/jobs/{job_id} with Bearer poll_bearer until completed."],"cost_usd":"Bill up to $1.50 default (override to $50); actual ≤ max; $0 on no-match."},{"id":"batch_csv_enrich","goal":"Enrich a CRM CSV export in bulk with optional C vs R prefilter.","steps":["POST /api/v1/batch/enrich/upload (multipart: file, optional prefilter_lead_type, row_limit, batch_prompt).","If anonymous: mint at /connect then POST /{batch_id}/link with upload_token.","POST /{batch_id}/start with admin bearer (411_…) when balance ≥ min_balance_usd.","Poll GET /{batch_id} — watch rows_preprep, rows_skipped_prefilter, rows_remaining.","GET /{batch_id}/preview for recent rows; GET /{batch_id}/download.csv for full export.","Change prefilter: POST /{batch_id}/re-prep when no rows in-flight."],"cost_usd":"llm_lead_type on cache miss + $1.500/row lead-session (bill-on-match); see estimated_classify_usd on upload."},{"id":"support_tickets","goal":"Open a support thread via API.","steps":["POST /api/v1/support/tickets with category bug|billing|account|other.","Use category bug for reproducible defects — $1.00 virtual USD credit after operator confirmation."],"cost_usd":"$0.010 per call; bug category eligible for $1.00 credit after confirmation."},{"id":"402_settle_loop","goal":"What to do when a paid call returns 402.","steps":["Read `billing_reason`, `detail`, `virtual_balance_usd`, `wallet_usdc_balance_usd`, `connect_url`, and `topup_url` (or `deposit_url` / `prepay_page_url`) on every 402 — explain them to the user.","If `code == AGENT_TOKEN_REQUIRED`, mint at `connect_url` (/connect) first.","If `code == PAYMENT_REQUIRED`, GET /api/v1/agents/balance — if balance ≥ price, retry the same call (server will debit balance, no signature required).","If balance < price: show the user `topup_url` as a clickable link (prepay wizard: connect wallet → amount → sign USDC on Base). Prefer that over raw deposit/claim unless the user is headless. Manual path: /cookbook/prepay_deposits. Sender wallet must be linked via /wallet-link first.","Alternatively sign an EIP-3009 TransferWithAuthorization to the `accepts[].payTo` for the listed `maxAmountRequired` and retry with `PAYMENT-SIGNATURE: <base64>`.","After 2xx, look for `payment-response: <base64>` (the on-chain settlement receipt)."],"cost_usd":"Per the route's x-payment-info.price."}]},"externalDocs":{"url":"https://411data.io/developers","description":"Developer guide — mint, billing waterfall, bill-on-match, x402 settle loop."},"servers":[{"url":"https://411data.io"}],"components":{"schemas":{"ProductError":{"type":"object","properties":{"code":{"type":"string","enum":["AGENT_TOKEN_REQUIRED","PAYMENT_REQUIRED","ROUTE_NOT_FOUND","AGENT_SUSPENDED","FORBIDDEN","RATE_LIMIT","BURST_RATE_EXCEEDED","VALIDATION_ERROR"]},"error":{"type":"string"},"detail":{"type":"string"},"route":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string","enum":["mint_agent","settle_x402_and_retry_with_x_payment","fix_request","wait_and_retry"]},"mint":{"$ref":"#/components/schemas/ProductErrorMint"},"discover":{"$ref":"#/components/schemas/ProductErrorDiscover"}}},"ProductErrorMint":{"type":"object","description":"Mint hints attached to AGENT_TOKEN_REQUIRED 401/402 responses.","properties":{"wallet_url":{"type":"string","format":"uri","description":"Wallet-bound mint flow (`/connect`)."},"register_url":{"type":"string","format":"uri","description":"Wallet-register endpoint (`POST /api/v1/agents/wallet-register`)."},"starting_balance_usd_wallet":{"type":["string","number"],"description":"Virtual USD credit granted on wallet mint."},"starting_balance_usd_google":{"type":["string","number"],"description":"Deprecated; use starting_balance_usd_wallet."},"docs":{"type":"string","format":"uri"}}},"ProductErrorDiscover":{"type":"object","description":"Discovery pointers attached to ROUTE_NOT_FOUND 404s.","properties":{"openapi":{"type":"string","format":"uri"},"openapi_free":{"type":"string","format":"uri"},"wellknown_x402":{"type":"string","format":"uri"},"agent_card":{"type":"string","format":"uri"},"discovery_resources":{"type":"string","format":"uri"},"pricing":{"type":"string","format":"uri"}}},"PaymentRequired402":{"type":"object","description":"x402 v2 payment-required envelope. Also delivered base64-encoded in the `payment-required:` response header.","properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"code":{"type":"string","enum":["PAYMENT_REQUIRED","AGENT_TOKEN_REQUIRED"]},"detail":{"type":"string"},"accepts":{"type":"array","items":{"$ref":"#/components/schemas/X402Accept"}},"extensions":{"type":"object","description":"Per-extension info blocks. `411data-mpp` carries per-wallet allowance pool snapshot; `bazaar` carries indexer-friendly service metadata."},"mint":{"$ref":"#/components/schemas/ProductErrorMint"},"route":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string"},"billing_reason":{"type":"string","description":"Why billing blocked the call (e.g. agent_token_required, virtual_balance_insufficient, burst_rate_exceeded)."},"connect_url":{"type":"string","format":"uri","description":"Fund wallet or mint an agent at https://411data.io/connect."},"topup_url":{"type":"string","format":"uri","description":"Prepay wizard when virtual balance is insufficient — /connect?action=topup."},"deposit_url":{"type":"string","format":"uri","description":"Alias for topup_url — USDC prepay to refill virtual balance."},"prepay_page_url":{"type":"string","format":"uri","description":"Alias for topup_url — show this link to the user in chat."},"llm_user_message":{"type":"string","description":"Plain-text instruction for the LLM to relay to the user (includes prepay URL when enabled)."},"virtual_balance_usd":{"type":"number","description":"Agent virtual USD balance when `code == \"PAYMENT_REQUIRED\"`."},"wallet_usdc_balance_usd":{"type":"number","description":"On-chain USDC on Base for the agent's primary linked wallet (best effort)."},"alternative_actions":{"type":"array","items":{"type":"string"},"description":"Other recovery paths when balance is exhausted (e.g. prepay top-up)."}},"required":["x402Version","accepts"]},"X402Accept":{"type":"object","properties":{"scheme":{"type":"string","enum":["exact","upto"]},"network":{"type":"string","description":"CAIP-2 network id (e.g. `eip155:8453` for Base mainnet)."},"maxAmountRequired":{"type":"string","description":"Atomic-units price (USDC has 6 decimals — `\"10000\"` = $0.010)."},"payTo":{"type":"string","description":"Recipient address."},"asset":{"type":"string","description":"Token contract address."},"extra":{"$ref":"#/components/schemas/X402AcceptExtra"}},"required":["scheme","network","maxAmountRequired","payTo","asset"]},"X402AcceptExtra":{"type":"object","description":"Scheme/facilitator-specific metadata. Stable keys below; additional keys allowed.","properties":{"name":{"type":"string","description":"EIP-712 domain name (e.g. `USD Coin`)."},"version":{"type":"string","description":"EIP-712 domain version (e.g. `2` on Base mainnet USDC)."},"facilitatorId":{"type":"string","description":"Stable id (`xpay`, `cdp`, `payai`, `dexter`) — buyer's choice in `accepts[]` selects which facilitator settles."},"facilitator":{"type":"string","format":"uri","description":"Facilitator HTTPS endpoint."},"assetTransferMethod":{"type":"string","enum":["eip3009","permit2"],"description":"On-chain transfer scheme."}},"additionalProperties":true},"BatchEnrichJob":{"type":"object","properties":{"batch_id":{"type":"string"},"agent_id":{"type":["integer","null"]},"status":{"type":"string"},"filename":{"type":"string"},"row_count":{"type":"integer"},"process_limit":{"type":"integer"},"columns":{"type":["array","null"],"items":{"type":"string"}},"per_row_budget_usd":{"type":"number"},"rows_processed":{"type":"integer"},"rows_matched":{"type":"integer"},"total_spent_usd":{"type":"number"},"match_rate_pct":{"type":["number","null"]},"file_session_id":{"type":["string","null"]},"source":{"type":["string","null"]},"input_format":{"type":"string","enum":["csv","json"]},"batch_prompt":{"type":["string","null"]},"prefilter_lead_type":{"type":["string","null"]},"lead_type_prep_status":{"type":["string","null"],"description":"Aggregate prep phase: pending | running | complete | null when no prefilter."},"lead_type_prep_json":{"type":["string","null"],"description":"JSON string with prep counters (classified, skipped, errors)."},"column_map_json":{"type":["string","null"],"description":"JSON string of CRM column mapping used at upload."},"created_utc":{"type":"string"},"started_utc":{"type":["string","null"]},"completed_utc":{"type":["string","null"]}},"required":["batch_id","status","row_count"]},"BatchEnrichStatusResp":{"type":"object","description":"Batch job snapshot with live row counters and balance projections.","allOf":[{"type":"object","properties":{"batch_id":{"type":"string"},"agent_id":{"type":["integer","null"]},"status":{"type":"string"},"filename":{"type":"string"},"row_count":{"type":"integer"},"process_limit":{"type":"integer"},"columns":{"type":["array","null"],"items":{"type":"string"}},"per_row_budget_usd":{"type":"number"},"rows_processed":{"type":"integer"},"rows_matched":{"type":"integer"},"total_spent_usd":{"type":"number"},"match_rate_pct":{"type":["number","null"]},"file_session_id":{"type":["string","null"]},"source":{"type":["string","null"]},"input_format":{"type":"string","enum":["csv","json"]},"batch_prompt":{"type":["string","null"]},"prefilter_lead_type":{"type":["string","null"]},"lead_type_prep_status":{"type":["string","null"],"description":"Aggregate prep phase: pending | running | complete | null when no prefilter."},"lead_type_prep_json":{"type":["string","null"],"description":"JSON string with prep counters (classified, skipped, errors)."},"column_map_json":{"type":["string","null"],"description":"JSON string of CRM column mapping used at upload."},"created_utc":{"type":"string"},"started_utc":{"type":["string","null"]},"completed_utc":{"type":["string","null"]}},"required":["batch_id","status","row_count"]},{"type":"object","properties":{"rows_pending":{"type":"integer"},"rows_running":{"type":"integer"},"rows_preprep":{"type":"integer","description":"Rows awaiting commercial/residential classification."},"rows_skipped":{"type":"integer"},"rows_skipped_prefilter":{"type":"integer","description":"Rows skipped because classified type mismatched prefilter_lead_type."},"rows_skipped_deferred":{"type":"integer","description":"Rows beyond process_limit held for process-more."},"projections":{"oneOf":[{"type":"object","properties":{"match_rate":{"type":"number"},"avg_cost_per_row_usd":{"type":"number"},"remaining_balance_usd":{"type":"number"},"projected_enrichable_rows":{"type":"integer"},"projected_total_matches":{"type":"number"},"rows_remaining":{"type":"integer"}}},{"type":"null"}]},"min_balance_usd":{"type":"number"}}}]},"BatchEnrichJobsListResp":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"batch_id":{"type":"string"},"agent_id":{"type":["integer","null"]},"status":{"type":"string"},"filename":{"type":"string"},"row_count":{"type":"integer"},"process_limit":{"type":"integer"},"columns":{"type":["array","null"],"items":{"type":"string"}},"per_row_budget_usd":{"type":"number"},"rows_processed":{"type":"integer"},"rows_matched":{"type":"integer"},"total_spent_usd":{"type":"number"},"match_rate_pct":{"type":["number","null"]},"file_session_id":{"type":["string","null"]},"source":{"type":["string","null"]},"input_format":{"type":"string","enum":["csv","json"]},"batch_prompt":{"type":["string","null"]},"prefilter_lead_type":{"type":["string","null"]},"lead_type_prep_status":{"type":["string","null"],"description":"Aggregate prep phase: pending | running | complete | null when no prefilter."},"lead_type_prep_json":{"type":["string","null"],"description":"JSON string with prep counters (classified, skipped, errors)."},"column_map_json":{"type":["string","null"],"description":"JSON string of CRM column mapping used at upload."},"created_utc":{"type":"string"},"started_utc":{"type":["string","null"]},"completed_utc":{"type":["string","null"]}},"required":["batch_id","status","row_count"]}},"next_cursor":{"type":["string","null"]}},"required":["jobs"]},"BatchEnrichPreviewResp":{"type":"object","properties":{"last_enriched":{"type":"array","items":{"type":"object","properties":{"row_index":{"type":"integer"},"company":{"type":["string","null"]},"stats":{"type":"object","additionalProperties":true},"matched":{"type":["boolean","null"]},"spent_usd":{"type":["number","null"]},"demo_session_id":{"type":["string","null"]},"status":{"type":"string"},"error_code":{"type":["string","null"]},"lead_type":{"type":["string","null"],"description":"commercial | residential | unknown from stats.lead_type."}}}},"pending_rows":{"type":"integer"}},"required":["last_enriched","pending_rows"]},"BatchEnrichStopResp":{"type":"object","properties":{"batch_id":{"type":"string"},"status":{"type":"string"},"rows_cancelled":{"type":"integer"},"hunts_signalled":{"type":"integer"}}},"ExportRunSubmitResp":{"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"]},"ExportPreviewResp":{"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"]}},"responses":{"BadRequest":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"Forbidden":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"NotFound":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"RateLimited":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"ValidationError":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"securitySchemes":{"bearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Agent token minted at /connect (wallet-bound; see /developers for headless SIWE flow), presented as ``Authorization: Bearer <token>``. Paid routes accept the token; when the agent's virtual USD balance is exhausted they return 402 with an x402 v2 challenge."}}},"paths":{"/api/v1/enrich/phone":{"post":{"summary":"411data Enrich Phone","description":"Reverse phone lookup into person name, emails, and addresses.","operationId":"411dataEnrichPhone","tags":["enrichment","phone","lead"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.330000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Reverse phone lookup → person name, emails, addresses"],"avoid_when":["You also have name or street — use enrich/person for richer queries","B2B company from domain — use enrich/company or enrich/websearch"],"cost_class":"medium","latency_class":"medium","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","E.164 preferred; API normalizes common formats.","Same reverse_phone mode as enrich/person with phone only."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"type":"string","minLength":5,"maxLength":40}},"required":["phone"]},"example":{"phone":"+17242060094"}}}}}},"/api/v1/enrich/person":{"post":{"summary":"411data Enrich Person","description":"Person/residential lookup by name, phone, or address.","operationId":"411dataEnrichPerson","tags":["enrichment","person","phone","lead"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.500000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Residential or person-shaped lead — find phones, emails, and addresses","Reverse phone lookup for owner cell when business websearch missed"],"avoid_when":["Clear B2B company with website — use enrich_websearch first"],"cost_class":"high","latency_class":"medium","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Provide phone, name, or street+city/state.","Also runs automatically inside enrich/lead-session for residential leads."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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}}},"example":{"name":"John Smith","state_code":"PA","zipcode":"15213"}}}}}},"/api/v1/enrich/websearch":{"post":{"summary":"411data Enrich Websearch","description":"Deep research from CRM JSON — decision-maker contacts, phones, and compliance associates.","operationId":"411dataEnrichWebsearch","tags":["enrichment","websearch","research","lead","deep_research","decision_makers"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.000000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Deep research to find decision makers and their contact information for a named business","Public phones, executive titles, and addresses when structured vendors lack coverage","Lead refresh where legal_associates (attorneys, registered agents, family counsel) matter for outreach compliance"],"avoid_when":["Standard enrich_company or enrich_email would suffice"],"cost_class":"high","latency_class":"slow","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Map fields from a CRM JSON export into the body (company → business_name, etc.).","Deep research results include decision-maker names, titles, phones, and source URLs.","Check data.legal_associates — flag attorneys and registered agents before cold outreach.","Recipe: /cookbook/enrich_websearch_when."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"business_name":"Acme Corp","city":"Tampa","state":"FL"}}}}}},"/api/v1/enrich/lead-session":{"post":{"summary":"411data Enrich Leads","description":"Deep research on a CRM JSON record — decision-maker contacts and cited backfill.","operationId":"411dataEnrichLeads","tags":["enrichment","lead","leads","lead_enrichment","enrich_leads","deep_research","decision_makers","orchestrator","research"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.500000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Deep research on a CRM record to find decision makers and their contact information","Multi-hop lead refresh from a partial CRM export (phones, owners, legal associates)","Agentic orchestration when single enrich_* tools are insufficient"],"avoid_when":["You only need one email or phone lookup — use enrich_* instead"],"cost_class":"high","latency_class":"slow","usage_tips":["Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Paste a CRM export row as JSON in lead — one record or a single-element [{…}] array.","Deep research across directory hunt → people hunt → research_web → company.","mode auto (default): one-shot end-to-end; interactive pauses with awaiting_user when marginal gaps remain.","max_rounds (default 5): safety cap on tool hops, not chat turns — raise to 10 only for deep multi-hop research.","Returns summary_markdown with source links + lead_enrichment_v1 backfill JSON.","Auto-persists to audit store when backfill has phones or contacts (persist block).","Manual replay only: POST /api/v1/enrich/lead-backfill or MCP lead_backfill_apply."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"lead":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"budget_usd":2.0,"max_rounds":5,"mode":"auto"}}}}}},"/api/v1/enrich/lead-session/slot-rerun":{"post":{"summary":"411data Hunt Slot Rerun","description":"Single-slot hunt rerun with graph patch merge.","operationId":"411dataHuntSlotRerun","tags":["enrichment","lead","hunt","slot_rerun"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.350000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["The user names one hunt slot to re-run (Hunt Forge, Hunt Swift, Hunt Deep, Sonar, …)","A single slot errored or returned nothing while the rest of the session was fine"],"avoid_when":["No enrich/lead-session has completed for this lead — run that first.","You want a full fresh hunt — post enrich/lead-session with refresh: true."],"cost_class":"medium","latency_class":"slow","usage_tips":["Bind the SAME lead + chat_session_id as the session being patched.","Delta-merges into the existing graph; prior_backfill loads from the chat when omitted.","Serialize these ops — a concurrent call can clobber the graph via a stale prior_backfill.","Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","model_id takes a public slot id (data411-hunt-forge) or a provider slug.","Bypasses the slot cache for that slot only — cheaper than a full session replay.","refresh_summary: true to rewrite summary_markdown after the merge.","Recipe: /cookbook/lead_session_followups."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"lead":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"chat_session_id":"sess_8f3a91c2","model_id":"data411-hunt-forge"}}}}}},"/api/v1/enrich/lead-session/slot-person":{"post":{"summary":"411data Hunt Person Slot","description":"Per-contact intermediate search and gated person hunt.","operationId":"411dataHuntPersonSlot","tags":["enrichment","lead","hunt","slot_person","person_hunt"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.350000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"endpoint":"enrich/lead-session/slot-person","status":"complete","matched":true,"billed":true,"spent_usd":0.09,"wall_time_ms":18420,"target_contact_id":"c_4471","target_name":"James W Cole Sr","person_hunt_ran":true,"person_hunt_usd":0.05,"slot_label":"Person Intermediate","slot_result":{"matched":true,"error":null,"latency_ms":11080},"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}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Deepening one named contact already on backfill.contacts[]","The user asks for a direct line or personal detail on a specific decision maker"],"avoid_when":["No enrich/lead-session has completed for this lead — run that first.","You want a full fresh hunt — post enrich/lead-session with refresh: true."],"cost_class":"medium","latency_class":"slow","usage_tips":["Bind the SAME lead + chat_session_id as the session being patched.","Delta-merges into the existing graph; prior_backfill loads from the chat when omitted.","Serialize these ops — a concurrent call can clobber the graph via a stale prior_backfill.","Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","target_contact_id comes from backfill.contacts[].id — not a CRM contact_id.","include_person_hunt (default true) is skipped when that contact was already hunted.","Recipe: /cookbook/lead_session_followups."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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."},"target_contact_id":{"type":"string","minLength":2,"maxLength":64,"description":"id of the backfill.contacts[] row to research."},"target_name":{"type":"string","maxLength":120,"description":"Display name override; resolved from backfill.contacts when omitted."},"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."},"include_person_hunt":{"type":"boolean","default":true,"description":"Queue a person hunt for this contact after the intermediate search when one has not already run."},"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}},"required":["lead","chat_session_id","target_contact_id"]},"example":{"lead":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"chat_session_id":"sess_8f3a91c2","target_contact_id":"c_4471"}}}}}},"/api/v1/enrich/lead-session/synthesize-patch":{"post":{"summary":"411data Synth Patch","description":"LLM-only graph resynthesis for an enriched lead.","operationId":"411dataSynthPatch","tags":["enrichment","lead","synthesis"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.080000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["The user only wants an updated or gap-focused cited summary","Merging a completed person hunt into the narrative (merge_person_hunt: true)"],"avoid_when":["No enrich/lead-session has completed for this lead — run that first.","You want a full fresh hunt — post enrich/lead-session with refresh: true."],"cost_class":"low","latency_class":"medium","usage_tips":["Bind the SAME lead + chat_session_id as the session being patched.","Delta-merges into the existing graph; prior_backfill loads from the chat when omitted.","Serialize these ops — a concurrent call can clobber the graph via a stale prior_backfill.","Runs no vendor hunts — always billed, since it always produces a summary.","Cheapest way to re-word or re-focus prose; prefer over a slot rerun for text-only asks.","extra_directives carries free-form synthesis instructions.","Recipe: /cookbook/lead_session_followups."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"lead":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"chat_session_id":"sess_8f3a91c2","prior_backfill":{"schema_version":"1.0","phones":[],"contacts":[]}}}}}}},"/api/v1/enrich/lead-session/finding-rerun":{"post":{"summary":"411data Finding Investigate","description":"Targeted hunt for one unmerged candidate row.","operationId":"411dataFindingInvestigate","tags":["enrichment","lead","finding"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.300000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Chasing down one backfill.unmerged_candidates[] finding withheld during merge","The user asks whether a specific withheld phone or person is real"],"avoid_when":["No enrich/lead-session has completed for this lead — run that first.","You want a full fresh hunt — post enrich/lead-session with refresh: true."],"cost_class":"medium","latency_class":"slow","usage_tips":["Bind the SAME lead + chat_session_id as the session being patched.","Delta-merges into the existing graph; prior_backfill loads from the chat when omitted.","Serialize these ops — a concurrent call can clobber the graph via a stale prior_backfill.","Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","candidate_id comes from backfill.unmerged_candidates[].id.","Stamps investigation_status on the candidate whether or not it merges.","Recipe: /cookbook/lead_session_followups."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"lead":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"chat_session_id":"sess_8f3a91c2","candidate_id":"uc_7d21f0"}}}}}},"/api/v1/enrich/lead-session/sic-rerun":{"post":{"summary":"411data SIC Classify","description":"LLM catalog pick for 4-digit SIC after enrichment.","operationId":"411dataSICClassify","tags":["enrichment","lead","sic"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"]},"example":{"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}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["The assigned SIC code looks wrong after the graph gained new facts","A session finished with no SIC code present"],"avoid_when":["No enrich/lead-session has completed for this lead — run that first.","You want a full fresh hunt — post enrich/lead-session with refresh: true."],"cost_class":"low","latency_class":"fast","usage_tips":["Bind the SAME lead + chat_session_id as the session being patched.","Delta-merges into the existing graph; prior_backfill loads from the chat when omitted.","Serialize these ops — a concurrent call can clobber the graph via a stale prior_backfill.","Bill-on-match: charge is refunded when matched=false (enrichment) or zero rows (leads).","Always report matched and billed to the user — do not invent contact fields when matched=false.","See /cookbook/bill_on_match.","Runs automatically at the end of a new session when no code is present.","Replaces a prior LLM-assigned code; never overwrites a CRM-supplied SIC on input_snapshot.","Recipe: /cookbook/lead_session_followups."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"lead":{"contact_id":81555753,"company":"Haney Furniture Co","street":"30 N Beaver St","city":"New Castle","state":"PA","zip":"16101","number1":"7246547732"},"chat_session_id":"sess_8f3a91c2","prior_backfill":{"schema_version":"1.0","phones":[],"contacts":[]}}}}}}},"/api/v1/support/tickets":{"post":{"summary":"411data Support Ticket","description":"LLM-callable support ticket open; seeds a support chat thread.","operationId":"411dataSupportTicket","tags":["support","help","bug"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"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"}}},"example":{"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}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Payment required (x402 challenge).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["User asks to file a bug, contact support, or report a billing/account issue.","User reports a reproducible product bug — use category bug ($1.00 credit after confirmation)."],"avoid_when":["Question is answerable from /connect wizards or cookbook alone — try docs first."]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"example":{"category":"bug","subject":"Enrich session stuck on Thinking","body":"After pasting a CRM lead, the chat hangs for 5+ minutes."}}}}}},"/api/v1/enrich/jobs":{"post":{"summary":"Submit async enrich job","description":"Queue long-running enrich/websearch or enrich/lead-session work. Bearer agents pre-charge bill_up_to_usd from virtual USD (default $1.50 when omitted; override up to $50) and receive 202 + poll_bearer. Anonymous buyers receive 402 CDP upto (maxTimeoutSeconds 1200) and settle deferred on completion. Poll GET /api/v1/enrich/jobs/{job_id} with poll_bearer (free). See /cookbook/async_enrich_jobs.","operationId":"submitEnrichJob","tags":["enrichment","async"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.500000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"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"]},"payload":{"type":"object"},"bill_up_to_usd":{"type":"number","minimum":0.05,"maximum":50.0,"default":1.5,"description":"Spending ceiling when omitted defaults to $1.50; client override up to ENRICH_JOB_BILL_UP_TO_MAX_USD ($50)."},"callback_url":{"type":"string","format":"uri","description":"Optional HTTPS webhook; fires enrich.job_completed on finish."},"idempotency_key":{"type":"string","description":"Optional dedupe key for the submit request."}}},"example":{"route":"enrich/websearch","payload":{"business_name":"Acme Corp","city":"Tampa","state":"FL"},"bill_up_to_usd":1.5}}}},"responses":{"202":{"description":"Job accepted — poll with poll_bearer (411j_…).","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"ej_… identifier."},"status":{"type":"string","enum":["queued","running","completed","failed"]},"status_url":{"type":"string"},"poll_bearer":{"type":"string","description":"411j_… scoped token for GET poll."},"poll_interval_sec":{"type":"integer","default":2},"billing_mode":{"type":"string","enum":["virtual_balance","x402_upto"]},"bill_up_to_usd":{"type":"number"},"max_timeout_seconds":{"type":"integer"}}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"CDP upto payment required (anonymous submit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}}}},"/api/v1/enrich/jobs/{job_id}":{"get":{"summary":"Poll async enrich job","description":"Poll job status and result (free). Requires Authorization: Bearer <poll_bearer> (411j_… from the 202 body) or the owning agent bearer. Terminal when status is completed or failed; check billing_status for settle outcome.","operationId":"getEnrichJob","tags":["enrichment","async"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"example":"ej_abc123"}],"responses":{"200":{"description":"Job snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string"},"route":{"type":"string"},"status":{"type":"string","enum":["queued","running","completing","completed","failed"]},"billing_status":{"type":"string","enum":["pending","settling","settled","settled_virtual","settle_failed"]},"progress":{"type":"object"},"result":{"type":"object","description":"Sync route response when complete."},"error":{"type":"string"},"settled_usd":{"type":"number"},"settle_tx_hash":{"type":"string"},"bill_up_to_usd":{"type":"number"},"created_utc":{"type":"string"},"started_utc":{"type":"string"},"finished_utc":{"type":"string"}}}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}}}},"/api/v1/batch/enrich/jobs":{"get":{"summary":"List batch enrichment jobs","description":"Cursor-paginated list of batch jobs for the authenticated agent.","operationId":"listBatchEnrichJobs","tags":["batch-enrichment"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","description":"created_utc|batch_id from prior page."}}],"responses":{"200":{"description":"Job list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichJobsListResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"free","latency_class":"async"}}},"/api/v1/batch/enrich/stop":{"post":{"summary":"Stop in-flight batch enrichment","description":"Cancel queued and running rows for batch_id or file_session_id.","operationId":"stopBatchEnrich","tags":["batch-enrichment"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch_id":{"type":"string"},"file_session_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Cancellation summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichStopResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"free","latency_class":"async"}}},"/api/v1/batch/enrich/{batch_id}":{"get":{"summary":"Get batch enrichment status","description":"Poll job progress. Auth: Bearer agent token or `Authorization: Batch <upload_token>`.","operationId":"getBatchEnrichStatus","tags":["batch-enrichment"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"responses":{"200":{"description":"Job snapshot with row counters and projections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichStatusResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"free","latency_class":"async"}}},"/api/v1/batch/enrich/{batch_id}/start":{"post":{"summary":"Start batch enrichment","description":"Queue pending rows for lead-session enrichment. Requires admin bearer (411_…), minimum virtual balance, and completed lead-type prep when prefilter is set. Each enriched row bills lead-session (bill-on-match).","operationId":"startBatchEnrich","tags":["batch-enrichment"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.500000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"batch_prompt":{"type":"string","maxLength":4000,"description":"Optional — update or clear instructions before queueing."}}}}}},"responses":{"200":{"description":"Job queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichJob"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Insufficient virtual balance to start or process more rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"composite","latency_class":"async"},"x-pricing":{"model":"per_row_lead_session","unit_usd":"1.500","note":"Actual spend ≤ per_row_budget_usd × rows; bill-on-match credits no-match rows."}}},"/api/v1/batch/enrich/{batch_id}/resume":{"post":{"summary":"Resume batch enrichment","description":"Alias for POST /start when a paused batch has pending rows.","operationId":"resumeBatchEnrich","tags":["batch-enrichment"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.500000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"batch_prompt":{"type":"string","maxLength":4000,"description":"Optional — update or clear instructions before queueing."}}}}}},"responses":{"200":{"description":"Job queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichJob"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Insufficient virtual balance to start or process more rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"composite","latency_class":"async"},"x-pricing":{"model":"per_row_lead_session","unit_usd":"1.500","note":"Actual spend ≤ per_row_budget_usd × rows; bill-on-match credits no-match rows."}}},"/api/v1/batch/enrich/{batch_id}/process-more":{"post":{"summary":"Promote deferred batch rows","description":"Move up to `count` deferred rows into the enrichment queue after the current queue drains. Requires minimum balance.","operationId":"processMoreBatchEnrich","tags":["batch-enrichment"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"1.500000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":1},"batch_prompt":{"type":"string","maxLength":4000}}}}}},"responses":{"200":{"description":"Updated job snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichStatusResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Insufficient virtual balance to start or process more rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"composite","latency_class":"async"}}},"/api/v1/batch/enrich/{batch_id}/re-prep":{"post":{"summary":"Re-run commercial/residential prep","description":"Reset lead-type classification for all rows and re-apply prefilter_lead_type. Use when changing C vs R filter after upload. No rows may be in-flight. Uncached llm_lead_type classifications bill on cache miss.","operationId":"rePrepBatchEnrich","tags":["batch-enrichment"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prefilter_lead_type":{"type":["string","null"],"enum":["commercial","residential"],"description":"Null clears the prefilter."}}}}}},"responses":{"200":{"description":"Prep reset; job re-queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichJob"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Insufficient virtual balance to start or process more rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"composite","latency_class":"async"}}},"/api/v1/batch/enrich/{batch_id}/preview":{"get":{"summary":"Preview recent batch row results","description":"PII-trimmed preview of last enriched/skipped rows (free poll).","operationId":"previewBatchEnrich","tags":["batch-enrichment"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"responses":{"200":{"description":"Preview cards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnrichPreviewResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"free","latency_class":"async"}}},"/api/v1/batch/enrich/{batch_id}/download.csv":{"get":{"summary":"Download enriched batch CSV","description":"Full export with enrich_lead_type and enrich_error_code columns. Requires linked agent.","operationId":"downloadBatchEnrichCsv","tags":["batch-enrichment"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"batch_id","in":"path","required":true,"schema":{"type":"string"},"example":"be_abc123"}],"responses":{"200":{"description":"CSV attachment.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}}},"x-agent-hints":{"use_when":["Bulk CRM CSV/JSON enrichment with optional commercial vs residential prefilter.","After upload, link bearer then POST /start; poll GET /{batch_id}."],"avoid_when":["Single-row enrichment — use POST /api/v1/enrich/lead-session instead."],"cost_class":"free","latency_class":"async"}}},"/api/v1/export/runs":{"post":{"summary":"Start an export mapping run","description":"Map an enriched batch into the profile's destination columns. Priced per billable row in the profile's column band and precharged from virtual USD at submit; unused precharge is refunded on settle or cancel. Rows already mapped under the same mapping_hash resolve from the map cache for $0.00, and a run where every row resolves that way is stamped scope_kind=rebuild, charges nothing, and completes without a worker hop — that is the zero-cost re-export guarantee. Quote first with GET /api/v1/export/runs/estimate, then poll GET /api/v1/export/runs/{run_id} and download GET /api/v1/export/runs/{run_id}/download.csv (both free). See /cookbook/custom_export_builder.","operationId":"submitExportRun","tags":["export"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.015000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["batch_id","profile_id"],"properties":{"batch_id":{"type":"string","minLength":5,"maxLength":40},"profile_id":{"type":"integer"},"profile_version":{"type":"integer","description":"Pinned on the run; defaults to the profile's current version."},"scope_kind":{"type":"string","default":"all","description":"all | row_list | rebuild | filter. row_list reads scope_json as an array of row_index; rebuild replays parent_run_id's mapped rows; anything else takes the quality-filter path."},"scope_json":{"description":"Array of row_index for scope_kind=row_list."},"parent_run_id":{"type":"integer","description":"Run whose rows this one is judged against. Out-of-scope parent rows are carried forward free so a scoped re-run still downloads as a complete file."},"remap_changed_leads":{"type":"boolean","default":false,"description":"Re-map instead of carrying a parent row forward when the lead content moved."},"file_instructions":{"type":"string","description":"Per-file instructions appended to the profile's. Part of mapping_hash, so submit with the same text you estimated with."},"skip_no_match":{"type":"boolean","default":false,"description":"Drop rows whose enrichment found nothing before billing."},"filters":{"type":"object","description":"Quality selectors OR-ed together, each 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 — buying fresh mapping work is the point.","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,"description":"Threshold for low_confidence (default 0.7)."},"column_empty":{"type":"boolean"},"empty_columns":{"type":"array","items":{"type":"string"},"description":"Destination column names that must be non-empty. Omit to mean \"the row produced nothing at all\" — the API never guesses your column names."},"hint_disagreement":{"type":"boolean"},"profile_version_lt":{"type":"integer","minimum":1}}}}},"example":{"batch_id":"be_abc123","profile_id":12,"scope_kind":"all"}}}},"responses":{"201":{"description":"Run created — queued, or completed when it was a free rebuild.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRunSubmitResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Insufficient virtual USD balance. Body carries virtual_balance_usd, bill_up_to_usd, and topup_url. Wallet x402 is never drawn on while virtual credit remains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Mapping a finished enrichment batch into a caller-defined destination schema.","Re-running only the rows a reviewer rejected, judged against a parent run."],"avoid_when":["Column order or CSV output settings changed — re-export instead, that is always $0.00.","The batch is still enriching; only completed rows can be mapped."],"cost_class":"composite","latency_class":"async"}}},"/api/v1/export/runs/preview":{"post":{"summary":"Preview mapped export rows","description":"Map the first 1–5 rows of a batch and return each cell beside the deterministic hint ranking, so a reviewer can see where the model departed from it (hint_rank null means the ranker never offered that value). Cache hits are free; cache misses are charged at the same per-row price as a run and banked to the map cache, so the eventual full run does not pay for them again. A degraded row produces no usable mapping and is refunded.","operationId":"previewExportRun","tags":["export"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.015000"},"protocols":[{"x402":{}},{"mpp":{"method":"x402-paired-allowance","intent":"deferred-debit","currency":"USD"}}]},"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["batch_id","profile_id"],"properties":{"batch_id":{"type":"string","minLength":5,"maxLength":40},"profile_id":{"type":"integer"},"profile_version":{"type":"integer","description":"Pinned on the run; defaults to the profile's current version."},"file_instructions":{"type":"string","description":"Per-file instructions appended to the profile's. Part of mapping_hash, so submit with the same text you estimated with."},"row_limit":{"type":"integer","minimum":1,"maximum":5,"default":3}}},"example":{"batch_id":"be_abc123","profile_id":12,"row_limit":3}}}},"responses":{"200":{"description":"Preview rows with per-cell hint contrast and what was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPreviewResp"}}}},"400":{"description":"Bad request — missing required filter or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"403":{"description":"Forbidden — IP blocked, admin surface, or suspended agent token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"404":{"description":"Route not found on this worker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"422":{"description":"Request validation failed (malformed JSON or query).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"429":{"description":"Rate limit exceeded — wait for Retry-After and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductError"}}}},"402":{"description":"Insufficient virtual USD balance. Body carries virtual_balance_usd, bill_up_to_usd, and topup_url. Wallet x402 is never drawn on while virtual credit remains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired402"}}}}},"x-agent-hints":{"use_when":["Checking mapping instructions against a few real rows before paying for the file."],"avoid_when":["Column order or CSV output settings changed — re-export instead, that is always $0.00.","The batch is still enriching; only completed rows can be mapped."],"cost_class":"composite","latency_class":"slow"}}}}}