{"openapi":"3.1.0","info":{"title":"Cleanlist API (Public)","description":"Public API surface for API key validation, credit balance, bulk enrichment, webhook registration, and status polling.","version":"2.0.0"},"paths":{"/api/v1/public/auth/validate-key":{"get":{"tags":["Public API (Legacy)"],"summary":"Validate Api Key","operationId":"validate_api_key_api_v1_public_auth_validate_key_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateApiKeyResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrich/bulk":{"post":{"tags":["Public API (Legacy)"],"summary":"Start Public Bulk Enrichment","operationId":"start_public_bulk_enrichment_api_v1_public_enrich_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBulkEnrichmentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBulkEnrichmentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrich/status":{"get":{"tags":["Public API (Legacy)"],"summary":"Get Public Enrichment Status","operationId":"get_public_enrichment_status_api_v1_public_enrich_status_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Id"}},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/webhooks/deliveries":{"get":{"tags":["Public API (Legacy)"],"summary":"List Public Webhook Deliveries","operationId":"list_public_webhook_deliveries_api_v1_public_webhooks_deliveries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"query","required":true,"schema":{"type":"string","title":"Workflow Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicWebhookDeliveryResponse"},"title":"Response List Public Webhook Deliveries Api V1 Public Webhooks Deliveries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/folders":{"post":{"tags":["Public API (Legacy)"],"summary":"Public Create Folder","description":"Create a folder for organizing LeadLists.","operationId":"public_create_folder_api_v1_public_folders_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFolderCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFolderResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/whoami":{"get":{"tags":["Public Workspace"],"summary":"Whoami","description":"Return the authenticated identity.\n\nFor API-key auth, `user_email` is masked so a leaked key can't\nreveal the creator's full email. `user_name` (first + last from\nClerk) and `organization_name` (from the local `organizations`\ntable) are best-effort lookups — both nullable so the widget can\nfall back to email / org_id when display names are missing.","operationId":"whoami_api_v1_public_whoami_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoamiResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/credits/balance":{"get":{"tags":["Public Workspace"],"summary":"Credits Balance","description":"Current credit balance for the caller's organization.","operationId":"credits_balance_api_v1_public_credits_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsBalanceResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/credits/estimate":{"post":{"tags":["Public Workspace"],"summary":"Credits Estimate","description":"Pre-flight a paid operation. Returns a quote_id bound to the\ncanonical request (tool, list_id|filters, scope, row_count, org).\n\nWhen `list_id` is provided, row_count is ALWAYS derived from the\nlist — never trusts caller-supplied `body.row_count`. Otherwise an\nattacker could pass `list_id=<small list>` + `row_count=99999` and\nget a quote priced for 99999 rows that downstream verifies against\nthe 99999 cap, letting them enrich way more than they paid for.","operationId":"credits_estimate_api_v1_public_credits_estimate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateCostRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateCostResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/api-keys":{"get":{"tags":["Public Workspace"],"summary":"List Api Keys Endpoint","description":"List the caller's API keys (prefix + last 4 only — never full values).\n\nRepo is user-scoped (`get_by_user(user_sub)`). Defense in depth: we\nalso filter by org so a Clerk user in multiple orgs only sees keys\nbelonging to the calling token's org.\n\nPer-key `scopes` is empty on current staging — scopes are sourced\nfrom Clerk publicMetadata via the MCP's X-Scopes header, not stored\non the ApiKey row. A future migration will add a `scopes` JSON\ncolumn and backfill from publicMetadata.","operationId":"list_api_keys_endpoint_api_v1_public_api_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeysResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/usage":{"get":{"tags":["Public Workspace"],"summary":"Usage Report","description":"Aggregate `api_key_request_log` for this org over `days`.\n\nCurrent ApiKeyRequestLog schema lacks `tool_name` and `cost_credits`\ncolumns, so:\n  - group_by=\"tool\" buckets by `path` (closest proxy)\n  - credits_spent is always 0 (no per-row cost column yet)\nBoth will improve when the log schema gains tool_name + cost_credits.\n\nSQL composition + per-row aggregation live in\n`ApiKeyRequestLogRepository.aggregate_usage` per the repo-pattern\nrule. This handler just composes the request shape and delegates.","operationId":"usage_report_api_v1_public_usage_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":7,"title":"Days"}},{"name":"group_by","in":"query","required":false,"schema":{"enum":["tool","key","day","error"],"type":"string","default":"tool","title":"Group By"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/lead-lists":{"post":{"tags":["Public Lead Lists"],"summary":"Create List","description":"Create a private LeadList in the caller's workspace.","operationId":"create_list_api_v1_public_lead_lists_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateListRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Public Lead Lists"],"summary":"List Lists","description":"Paginate LeadLists accessible to the caller (owned, org-wide, shared).","operationId":"list_lists_api_v1_public_lead_lists_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"folder_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListsPageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/lead-lists/{list_id}":{"get":{"tags":["Public Lead Lists"],"summary":"Get List","description":"Return one LeadList accessible to the caller.","operationId":"get_list_api_v1_public_lead_lists__list_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","title":"List Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/lead-lists/{list_id}/leads":{"get":{"tags":["Public Lead Lists"],"summary":"List Leads In List","description":"Paginate leads in a list.\n\nFields like `first_name`, `last_name`, `title`, `company` come from\nthe joined Prospect + Company relations — the Lead row itself only\ncarries enrichment results (email, phone, linkedin URL).","operationId":"list_leads_in_list_api_v1_public_lead_lists__list_id__leads_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","title":"List Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadsPageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Public Lead Lists"],"summary":"Add Leads To List","description":"Add leads to a list by explicit lead_ids[].\n\nCross-org safety: every lead_id must be a member of at least one\nlist already owned by this org. This blocks \"knew the UUID, added\nto my list\" attacks. When the MCPTask registry lands, a second\nreachability path opens up: lead_ids that appear in a recent\n`search_people` cohort owned by this org.\n\nFilter-based add is rejected — the MCP description tells the agent\nto translate filters into lead_ids before calling.","operationId":"add_leads_to_list_api_v1_public_lead_lists__list_id__leads_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddLeadsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddLeadsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Public Lead Lists"],"summary":"Remove Leads From List","description":"Remove leads from a list (max 100 per call).\n\nRemoves the membership row only — the Lead itself stays in the\nworkspace (still findable via `search_people`, still in other lists\nit belonged to). Non-existent lead_ids are silently no-op so the\ncaller can dedupe loosely without 404s.","operationId":"remove_leads_from_list_api_v1_public_lead_lists__list_id__leads_delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveLeadsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveLeadsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/lead-lists/{list_id}/csv-import":{"post":{"tags":["Public Lead Lists"],"summary":"Csv Import","description":"Import a CSV into a lead list and optionally dispatch bulk enrichment.\n\nPipeline:\n    1. Authz: `lists:write` always; `enrich:write` additionally when\n       `dispatch_enrichment=True` (the workflow spends credits).\n    2. Feature flag gate — disabled-by-default kill switch returns 503.\n    3. Idempotency cache lookup (org-wide, 24h TTL).\n    4. Base64 decode + parse via `parse_csv_to_rawpeople`.\n    5. If dispatching: verify quote (if provided), open reservation,\n       redeem quote.\n    6. Bulk-insert RawPeople into the list. UUIDs are stamped\n       Python-side so we can hand them to the workflow.\n    7. If dispatching: kick off `start_bulk_enrichment` with the\n       parsed prospects + raw_person_ids. The workflow's per-Lead\n       `insert_lead_to_list` activity handles prospect_count\n       updates per the existing pattern; import-only path bumps\n       prospect_count here directly.\n    8. Cache the response under `idempotency_key` (if provided).\n\nCross-list dedup: this endpoint dedupes ONLY within the upload. A\nrow whose identity already exists as a Lead elsewhere in the\nworkspace still imports as a RawPerson here; the workflow's\n`persist_enrichment_result` then deduplicates against existing\nLeads by public_identifier / prospect_id (existing behavior).\nNet effect: no duplicate Lead, but the RawPerson stub persists\nuntil the workflow processes it.","operationId":"csv_import_api_v1_public_lead_lists__list_id__csv_import_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"string","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CsvImportRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CsvImportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/search/people/filters":{"get":{"tags":["Public People Search"],"summary":"Search Filters People","description":"Valid filter values for people search. ZERO CREDITS.\n\nFixed-enum fields (seniority, management_levels, departments,\njob_functions, company_headcount) return a canned list — Crustdata\naccepts these values verbatim, no autocomplete needed.\n\nAutocompletable fields (titles, locations, company_industries)\ndelegate to Crustdata's autocomplete with the friendly field name\ntranslated via `_PEOPLE_AUTOCOMPLETE_FIELD_MAP`.","operationId":"search_filters_people_api_v1_public_search_people_filters_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"field","in":"query","required":true,"schema":{"enum":["titles","seniority","departments","job_functions","management_levels","locations","company_headcount","company_industries"],"type":"string","title":"Field"}},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleFiltersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/search/people":{"post":{"tags":["Public People Search"],"summary":"Search People","description":"Search people. FREE — credits are spent at enrichment / save time.\n\nDelegates to the internal staging handler so the 5-step filter\npipeline (location component expansion → region contains expansion\n→ column mapping → enum alias expansion → Crustdata format\ntransform) runs unchanged. We pass the caller's actual tier so\nFREE-tier callers get the 25-row preview cap.","operationId":"search_people_api_v1_public_search_people_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeopleSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/search/companies/filters":{"get":{"tags":["Public Companies Search"],"summary":"Search Filters Companies","description":"Valid filter values for companies. ZERO CREDITS.\n\nTwo paths:\n- Fixed enums (employee_count_ranges, funding_stages) → canned list.\n  No external call.\n- Free-form fields (industries, locations) → Crustdata autocomplete.\n\nNote: `revenue_ranges` and `technologies` were intentionally removed\nfrom the surface because the backing CompanyDB columns aren't on\nthe current Crustdata plan tier. Re-add the corresponding branches\nhere AND the entries in `_COMPANY_FILTER_COLUMN_MAP` /\n`CompanyFilterField` when the plan expands.","operationId":"search_filters_companies_api_v1_public_search_companies_filters_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"field","in":"query","required":true,"schema":{"enum":["industries","employee_count_ranges","locations","funding_stages"],"type":"string","title":"Field"}},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyFiltersResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/search/companies":{"post":{"tags":["Public Companies Search"],"summary":"Search Companies","description":"Search companies. FREE — credits are spent at enrichment / save time.\n\nDistinguishes \"caller sent no filters\" (400 validation_error) from\n\"caller's filters were all dropped by the availability probe\" (503\nfilters_unavailable). The latter is transient — the caller can\nretry as the probe cycles, or switch to a more widely-supported\nfilter column.","operationId":"search_companies_api_v1_public_search_companies_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/search/companies/similar":{"post":{"tags":["Public Companies Search"],"summary":"Find Similar Companies","description":"Find companies similar to a reference, ranked by similarity score.\n\nCrustdata doesn't ship a lookalike endpoint, so we synthesize one:\n  1. ``/screener/identify`` (FREE) resolves the reference company\n     and returns its canonical facets — industries, headcount\n     band, last funding round, crunchbase categories.\n  2. ``/screener/companydb/search`` (paid; same single-call cost\n     as the user's regular company search) finds companies that\n     share those facets. We filter out the reference itself and\n     rank by industry/funding-stage match closeness.\n\nThe similarity score is a simple coverage metric — how many of the\nreference's facets the candidate also has — so two SaaS companies\nin the same funding band score higher than two SaaS companies\nwhere one is post-IPO and the other is pre-seed. Not an embedding\nmodel; it's a deterministic shared-facet count normalized to\n[0, 1]. Good enough for \"show me 25 lookalike accounts\" and free\non the Identify hop.","operationId":"find_similar_companies_api_v1_public_search_companies_similar_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarCompaniesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarCompaniesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrichment/person":{"post":{"tags":["Public Enrichment"],"summary":"Enrich Person","description":"Enrich a single person. Asynchronous — returns workflow_id.\n\nCost: 1 credit (partial / email only), 10 credits (phone_only), or\n11 credits (full = email + phone). Driven by the explicit\n`enrichment_type` field; falls back to the legacy `include_phone`\nboolean when unset.\n\nQuote_id is optional — single-call scale doesn't need quote\nenforcement, but we honor it if provided so callers can pre-commit.","operationId":"enrich_person_api_v1_public_enrichment_person_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichPersonRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichPersonResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrichment/company":{"post":{"tags":["Public Enrichment"],"summary":"Enrich Company","description":"Enrich a single company. SYNCHRONOUS — returns the full record.\n\nCost: 1 credit. Uses CompanyDB single-record lookup; no Temporal.\n`company_ticker` resolution is intentionally not implemented yet —\npass `domain` if you have one; ticker support lands when we add\nthe ticker→domain map.","operationId":"enrich_company_api_v1_public_enrichment_company_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichCompanyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichCompanyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrichment/by-task":{"post":{"tags":["Public Enrichment"],"summary":"Enrich By Task","description":"Enrich a cohort from a prior search's task_id.\n\nPerson tasks → async (returns workflow_id; results land in\nlead_list_id). Company tasks → synchronous (returns full results\nper entity, no workflow).","operationId":"enrich_by_task_api_v1_public_enrichment_by_task_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichByTaskRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichByTaskResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrichment/bulk":{"post":{"tags":["Public Enrichment"],"summary":"Enrich List","description":"Bulk waterfall enrichment over an existing LeadList.\n\nREQUIRES `quote_id` from `/credits/estimate`. Cost is bounded by\nthe quote's `max_credits`; actual deduction is the recomputed cost\ncapped at that ceiling.","operationId":"enrich_list_api_v1_public_enrichment_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichListRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/enrichment/status/{workflow_id}":{"get":{"tags":["Public Enrichment"],"summary":"Enrichment Status","description":"Poll a workflow's status. Free.\n\nAccepts EITHER a workflow_id (e.g. `enrich-...` / `bulk-enrich-...`)\nOR an MCPTask cohort `task_id` (`cl-task_...`). When given a\ntask_id, we look up the cohort's stored `workflow_id` from when\nthe workflow was started. This lets the agent keep using the one\nhandle it already has from search_people / list_leads_in_list.","operationId":"enrichment_status_api_v1_public_enrichment_status__workflow_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"workflow_id","in":"path","required":true,"schema":{"type":"string","title":"Workflow Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkflowStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/smart-agents/run":{"post":{"tags":["Public Smart Agents"],"summary":"Run Smart Agent","description":"Kick off a smart-agent run. Requires a quote_id from /credits/estimate.\n\n`lead_scope=\"all\"` runs above the configured threshold (default 500)\nreturn `approval_required` 400 — the agent must come back with\n`lead_scope=\"subset\"` or explicit user approval routed through a\nseparate flow.","operationId":"run_smart_agent_api_v1_public_smart_agents_run_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSmartAgentRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSmartAgentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/smart-agents":{"get":{"tags":["Public Smart Agents"],"summary":"List Smart Agents","description":"List smart-agent runs for the org. Free.","operationId":"list_smart_agents_api_v1_public_smart_agents_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"List Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSmartAgentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/smart-agents/{smart_agent_task_id}":{"get":{"tags":["Public Smart Agents"],"summary":"Get Smart Agent Results","description":"Poll smart-agent results. Free.","operationId":"get_smart_agent_results_api_v1_public_smart_agents__smart_agent_task_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"smart_agent_task_id","in":"path","required":true,"schema":{"type":"string","description":"Canonical id from /smart-agents/run's `smart_agent_task_id` field","title":"Smart Agent Task Id"},"description":"Canonical id from /smart-agents/run's `smart_agent_task_id` field"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartAgentResultsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/sync/crm":{"post":{"tags":["Public Sync"],"summary":"Sync To Crm","description":"Push leads from a LeadList to HubSpot / Salesforce / Outreach.\n\nExternal write — requires `approved=true` AND a valid `quote_id`.","operationId":"sync_to_crm_api_v1_public_sync_crm_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncCrmRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/sync/sequencer":{"post":{"tags":["Public Sync"],"summary":"Sync To Sequencer","description":"Add leads from a LeadList to a Lemlist campaign.\n\nSame external-write gates as sync_to_crm: `approved=true` +\n`quote_id`. Lemlist is currently the only sequencer integrated.","operationId":"sync_to_sequencer_api_v1_public_sync_sequencer_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncSequencerRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/export/csv/signed-url":{"post":{"tags":["Public Export"],"summary":"Export Csv","description":"Export a LeadList as CSV. Returns a SAS-signed download URL (24h TTL).\n\nFREE. Builds the CSV in memory then uploads to Azure Blob Storage.\nFor very large lists (>50k rows), memory pressure builds — see the\nstreaming-CSV follow-up.","operationId":"export_csv_api_v1_public_export_csv_signed_url_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportCsvRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportCsvResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/public/export/json":{"get":{"tags":["Public Export"],"summary":"Export Json","description":"Export leads as JSON. Paginated. FREE.\n\nSame columns as the CSV export by default. `cursor` is a stringified\noffset; malformed cursors return 400 rather than silently\nrewinding to page 0.","operationId":"export_json_api_v1_public_export_json_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"list_id","in":"query","required":true,"schema":{"type":"string","title":"List Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"columns","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Columns"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJsonResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AddLeadsRequest":{"properties":{"lead_ids":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Lead Ids"}},"additionalProperties":false,"type":"object","required":["lead_ids"],"title":"AddLeadsRequest"},"AddLeadsResponse":{"properties":{"list_id":{"type":"string","title":"List Id"},"added":{"type":"integer","title":"Added"},"skipped_duplicates":{"type":"integer","title":"Skipped Duplicates"}},"additionalProperties":false,"type":"object","required":["list_id","added","skipped_duplicates"],"title":"AddLeadsResponse"},"ApiKeyInfo":{"properties":{"key_id":{"type":"string","title":"Key Id"},"key_prefix":{"type":"string","title":"Key Prefix"},"key_last4":{"type":"string","title":"Key Last4"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"is_active":{"type":"boolean","title":"Is Active"}},"additionalProperties":false,"type":"object","required":["key_id","key_prefix","key_last4","scopes","is_active"],"title":"ApiKeyInfo"},"ApiKeysResponse":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/ApiKeyInfo"},"type":"array","title":"Keys"}},"additionalProperties":false,"type":"object","required":["keys"],"title":"ApiKeysResponse"},"CompanyFiltersResponse":{"properties":{"field":{"type":"string","title":"Field"},"options":{"items":{"$ref":"#/components/schemas/FilterOption"},"type":"array","title":"Options"}},"additionalProperties":false,"type":"object","required":["field","options"],"title":"CompanyFiltersResponse"},"CompanyRecord":{"properties":{"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"industries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Industries"},"employee_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employee Count"},"employee_count_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Employee Count Range"},"revenue_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Range"},"hq_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq Location"},"funding_stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Funding Stage"},"total_funding_usd":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Funding Usd"},"tech_stack":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tech Stack"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"}},"additionalProperties":true,"type":"object","title":"CompanyRecord","description":"Synchronous company enrichment result. Shape follows what\nCompanyDB returns, but with stable field names independent of\nCrustdata's response shape drift."},"CompanyResultRow":{"properties":{"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"employee_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employee Count"},"revenue_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Range"},"hq_location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hq Location"},"funding_stage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Funding Stage"}},"additionalProperties":false,"type":"object","title":"CompanyResultRow"},"CompanySearchRequest":{"properties":{"filters":{"additionalProperties":true,"type":"object","title":"Filters"},"limit":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Limit","default":25},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},"additionalProperties":false,"type":"object","required":["filters"],"title":"CompanySearchRequest"},"CompanySearchResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"entity_kind":{"type":"string","const":"company","title":"Entity Kind","default":"company"},"results":{"items":{"$ref":"#/components/schemas/CompanyResultRow"},"type":"array","title":"Results"},"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"credits_charged":{"type":"integer","title":"Credits Charged"},"truncation_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Truncation Warning"}},"additionalProperties":false,"type":"object","required":["results","total","credits_charged"],"title":"CompanySearchResponse"},"CreateListRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"folder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Id"}},"additionalProperties":false,"type":"object","required":["name"],"title":"CreateListRequest"},"CreditsBalanceResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"organization_id":{"type":"string","title":"Organization Id"},"credits":{"type":"integer","title":"Credits"}},"additionalProperties":false,"type":"object","required":["organization_id","credits"],"title":"CreditsBalanceResponse","description":"Minimal balance shape. The MCP `check_credits` description tells\nthe agent to direct the user to billing for plan/renewal info, so\nwe deliberately don't ship plan_slug / renew_at here even though\ncallers might want them — keep the contract tight."},"CsvImportRequest":{"properties":{"csv_content_base64":{"type":"string","title":"Csv Content Base64","description":"Full CSV file body, base64-encoded. UTF-8 (with or without BOM). v1 hard-caps the raw body at 150 KB / ~600 rows — past that the base64 payload starts hitting tool-call output limits in the agent before any server cap fires. Above the cap the endpoint returns 413; chunk the file upstream."},"column_mapping":{"additionalProperties":{"type":"string"},"propertyNames":{"enum":["first_name","last_name","full_name","email","phone","linkedin_url","company_name","company_domain","job_title","city","state","country"]},"type":"object","minProperties":1,"title":"Column Mapping","description":"{ canonical_field: csv_header_name }. The MCP agent reads the CSV header line and supplies the mapping; the server never guesses. CSV columns not mapped are dropped. Mapping a field that isn't in the CSV header returns 400 missing_column with the bad header name in `details`."},"dispatch_enrichment":{"type":"boolean","title":"Dispatch Enrichment","description":"When True (default), the import dispatches a BulkEnrichmentWorkflow immediately after the RawPeople rows land. When False, rows land as RawPerson(status=pending) and the caller dispatches enrichment separately via enrich_list.","default":true},"enrichment_type":{"anyOf":[{"type":"string","enum":["partial","phone_only","full"]},{"type":"null"}],"title":"Enrichment Type","description":"Required when dispatch_enrichment=True. Same enum and pricing as enrich_person / enrich_list."},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id","description":"Optional signed quote from /credits/estimate. The MCP tool should quote first for large dispatches; small ones can skip and let the per-call deduct run. Verified against the tool=`bulk_import_csv`, row_count=rows_imported, filter={list_id}, extra={enrichment_type} canonical."},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"Opaque caller-supplied key. If a previous request with the same key+org succeeded within 24h, the cached response is replayed with idempotency_replayed=true and the CSV is NOT re-imported (credits are NOT re-charged). Scope is org-wide: the same key targeting different lists collides — first wins. Use a fresh UUID per logical import."}},"additionalProperties":false,"type":"object","required":["csv_content_base64","column_mapping"],"title":"CsvImportRequest"},"CsvImportResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"list_id":{"type":"string","title":"List Id"},"rows_parsed":{"type":"integer","title":"Rows Parsed"},"rows_imported":{"type":"integer","title":"Rows Imported"},"rows_skipped":{"type":"integer","title":"Rows Skipped"},"skip_reasons":{"additionalProperties":{"type":"integer"},"type":"object","title":"Skip Reasons"},"sample_skip_rows":{"items":{"type":"integer"},"type":"array","title":"Sample Skip Rows"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Id"},"enrichment_status_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Enrichment Status Url"},"idempotency_replayed":{"type":"boolean","title":"Idempotency Replayed","default":false}},"additionalProperties":false,"type":"object","required":["list_id","rows_parsed","rows_imported","rows_skipped"],"title":"CsvImportResponse"},"EnrichByTaskEntityResult":{"properties":{"entity_id":{"type":"string","title":"Entity Id"},"status":{"type":"string","enum":["queued","enriched","skipped","failed"],"title":"Status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"company":{"anyOf":[{"$ref":"#/components/schemas/CompanyRecord"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["entity_id","status"],"title":"EnrichByTaskEntityResult"},"EnrichByTaskRequest":{"properties":{"task_id":{"type":"string","title":"Task Id"},"data_points":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Data Points"},"entity_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Entity Ids"},"lead_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lead List Id"}},"additionalProperties":false,"type":"object","required":["task_id","data_points"],"title":"EnrichByTaskRequest"},"EnrichByTaskResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"entity_kind":{"type":"string","enum":["person","company"],"title":"Entity Kind"},"workflow_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workflow Id"},"status":{"type":"string","enum":["pending","completed"],"title":"Status"},"total_entities":{"type":"integer","title":"Total Entities"},"credits_reserved":{"type":"integer","title":"Credits Reserved"},"results":{"items":{"$ref":"#/components/schemas/EnrichByTaskEntityResult"},"type":"array","title":"Results"}},"additionalProperties":false,"type":"object","required":["entity_kind","status","total_entities","credits_reserved","results"],"title":"EnrichByTaskResponse"},"EnrichCompanyRequest":{"properties":{"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"company_ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Ticker"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"}},"additionalProperties":false,"type":"object","title":"EnrichCompanyRequest"},"EnrichCompanyResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"company":{"$ref":"#/components/schemas/CompanyRecord"},"credits_charged":{"type":"integer","title":"Credits Charged"}},"additionalProperties":false,"type":"object","required":["company","credits_charged"],"title":"EnrichCompanyResponse"},"EnrichListRequest":{"properties":{"list_id":{"type":"string","title":"List Id"},"scope":{"type":"string","enum":["partial","full","phone-only"],"title":"Scope","default":"partial"},"quote_id":{"type":"string","title":"Quote Id","description":"Required. Obtain via POST /credits/estimate first."}},"additionalProperties":false,"type":"object","required":["list_id","quote_id"],"title":"EnrichListRequest"},"EnrichListResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"workflow_id":{"type":"string","title":"Workflow Id"},"status":{"type":"string","const":"pending","title":"Status"},"total_leads":{"type":"integer","title":"Total Leads"},"estimated_cost":{"type":"integer","title":"Estimated Cost"},"credits_reserved":{"type":"integer","title":"Credits Reserved"},"poll_url":{"type":"string","title":"Poll Url"}},"additionalProperties":false,"type":"object","required":["workflow_id","status","total_leads","estimated_cost","credits_reserved","poll_url"],"title":"EnrichListResponse"},"EnrichPersonRequest":{"properties":{"lead_list_id":{"type":"string","title":"Lead List Id","description":"Target list for enrichment result"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"person_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Person Id"},"enrichment_type":{"anyOf":[{"type":"string","enum":["partial","phone_only","full"]},{"type":"null"}],"title":"Enrichment Type"},"include_phone":{"type":"boolean","title":"Include Phone","default":false},"quote_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote Id"}},"additionalProperties":false,"type":"object","required":["lead_list_id"],"title":"EnrichPersonRequest"},"EnrichPersonResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"workflow_id":{"type":"string","title":"Workflow Id"},"status":{"type":"string","const":"pending","title":"Status"},"credits_reserved":{"type":"integer","title":"Credits Reserved"},"lead_list_id":{"type":"string","title":"Lead List Id"},"poll_url":{"type":"string","title":"Poll Url"}},"additionalProperties":false,"type":"object","required":["workflow_id","status","credits_reserved","lead_list_id","poll_url"],"title":"EnrichPersonResponse"},"EstimateCostRequest":{"properties":{"tool":{"type":"string","title":"Tool"},"list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"List Id"},"filters":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Filters"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"},"agent_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Type"},"include_phone":{"type":"boolean","title":"Include Phone","default":false},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"sub_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Action"},"enrichment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Enrichment Type"},"extra":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Extra"}},"additionalProperties":false,"type":"object","required":["tool"],"title":"EstimateCostRequest"},"EstimateCostResponse":{"properties":{"quote_id":{"type":"string","title":"Quote Id"},"expires_at":{"type":"integer","title":"Expires At"},"estimated_cost":{"type":"integer","title":"Estimated Cost"},"tool":{"type":"string","title":"Tool"},"row_count":{"type":"integer","title":"Row Count"},"filter_hash":{"type":"string","title":"Filter Hash"},"available_credits":{"type":"integer","title":"Available Credits"},"sufficient":{"type":"boolean","title":"Sufficient"}},"additionalProperties":false,"type":"object","required":["quote_id","expires_at","estimated_cost","tool","row_count","filter_hash","available_credits","sufficient"],"title":"EstimateCostResponse"},"ExportCsvRequest":{"properties":{"list_id":{"type":"string","title":"List Id"},"columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Columns"},"include_smart_agents":{"type":"boolean","title":"Include Smart Agents","default":true}},"additionalProperties":false,"type":"object","required":["list_id"],"title":"ExportCsvRequest"},"ExportCsvResponse":{"properties":{"list_id":{"type":"string","title":"List Id"},"download_url":{"type":"string","title":"Download Url"},"expires_at":{"type":"string","title":"Expires At"},"row_count":{"type":"integer","title":"Row Count"},"file_size_bytes":{"type":"integer","title":"File Size Bytes"}},"additionalProperties":false,"type":"object","required":["list_id","download_url","expires_at","row_count","file_size_bytes"],"title":"ExportCsvResponse"},"ExportJsonResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"list_id":{"type":"string","title":"List Id"},"leads":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Leads"},"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},"additionalProperties":false,"type":"object","required":["list_id","leads","total"],"title":"ExportJsonResponse"},"FilterOption":{"properties":{"id":{"type":"string","title":"Id"},"label":{"type":"string","title":"Label"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"additionalProperties":false,"type":"object","required":["id","label"],"title":"FilterOption"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LeadRow":{"properties":{"lead_id":{"type":"string","title":"Lead Id"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company"}},"additionalProperties":false,"type":"object","required":["lead_id"],"title":"LeadRow"},"LeadsPageResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"list_id":{"type":"string","title":"List Id"},"leads":{"items":{"$ref":"#/components/schemas/LeadRow"},"type":"array","title":"Leads"},"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},"additionalProperties":false,"type":"object","required":["list_id","leads","total"],"title":"LeadsPageResponse"},"ListDetailResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"list_id":{"type":"string","title":"List Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"lead_count":{"type":"integer","title":"Lead Count"},"enriched_count":{"type":"integer","title":"Enriched Count"},"folder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["list_id","name","lead_count","enriched_count"],"title":"ListDetailResponse"},"ListSmartAgentsResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"runs":{"items":{"$ref":"#/components/schemas/SmartAgentRun"},"type":"array","title":"Runs"},"total":{"type":"integer","title":"Total"}},"additionalProperties":false,"type":"object","required":["runs","total"],"title":"ListSmartAgentsResponse"},"ListSummary":{"properties":{"list_id":{"type":"string","title":"List Id"},"name":{"type":"string","title":"Name"},"lead_count":{"type":"integer","title":"Lead Count"},"folder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Id"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"owner_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owner Name"},"visibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visibility"}},"additionalProperties":false,"type":"object","required":["list_id","name","lead_count"],"title":"ListSummary"},"ListsPageResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"lists":{"items":{"$ref":"#/components/schemas/ListSummary"},"type":"array","title":"Lists"},"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},"additionalProperties":false,"type":"object","required":["lists","total"],"title":"ListsPageResponse"},"PeopleFiltersResponse":{"properties":{"field":{"type":"string","title":"Field"},"options":{"items":{"$ref":"#/components/schemas/FilterOption"},"type":"array","title":"Options"}},"additionalProperties":false,"type":"object","required":["field","options"],"title":"PeopleFiltersResponse"},"PeopleSearchRequest":{"properties":{"filters":{"additionalProperties":true,"type":"object","title":"Filters"},"limit":{"type":"integer","maximum":500.0,"minimum":1.0,"title":"Limit","default":25},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"sort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort"}},"additionalProperties":false,"type":"object","required":["filters"],"title":"PeopleSearchRequest"},"PeopleSearchResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"entity_kind":{"type":"string","const":"person","title":"Entity Kind","default":"person"},"results":{"items":{"$ref":"#/components/schemas/PeopleSearchResultRow"},"type":"array","title":"Results"},"total":{"type":"integer","title":"Total"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"credits_charged":{"type":"integer","title":"Credits Charged"},"truncation_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Truncation Warning"}},"additionalProperties":false,"type":"object","required":["results","total","credits_charged"],"title":"PeopleSearchResponse"},"PeopleSearchResultRow":{"properties":{"lead_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lead Id"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"confidence_score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Confidence Score"}},"additionalProperties":false,"type":"object","title":"PeopleSearchResultRow"},"PublicBulkContact":{"properties":{"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"company_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Domain"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"}},"type":"object","title":"PublicBulkContact"},"PublicBulkEnrichmentRequest":{"properties":{"enrichment_type":{"type":"string","title":"Enrichment Type","default":"partial"},"webhook_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Webhook Url"},"contacts":{"items":{"$ref":"#/components/schemas/PublicBulkContact"},"type":"array","title":"Contacts"}},"type":"object","required":["contacts"],"title":"PublicBulkEnrichmentRequest"},"PublicBulkEnrichmentResponse":{"properties":{"workflow_id":{"type":"string","title":"Workflow Id"},"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"},"task_ids":{"items":{"type":"string"},"type":"array","title":"Task Ids"},"total_contacts":{"type":"integer","title":"Total Contacts"}},"type":"object","required":["workflow_id","status","message","task_ids","total_contacts"],"title":"PublicBulkEnrichmentResponse"},"PublicFolderCreate":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"}},"type":"object","required":["name"],"title":"PublicFolderCreate"},"PublicFolderResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Id"},"user_id":{"type":"string","title":"User Id"},"organization_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","user_id","created_at"],"title":"PublicFolderResponse"},"PublicStatusResponse":{"properties":{"workflow":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Workflow"},"task":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Task"}},"type":"object","title":"PublicStatusResponse"},"PublicWebhookDeliveryResponse":{"properties":{"id":{"type":"string","title":"Id"},"webhook_id":{"type":"string","title":"Webhook Id"},"workflow_id":{"type":"string","title":"Workflow Id"},"event_type":{"type":"string","title":"Event Type"},"attempt_number":{"type":"integer","title":"Attempt Number"},"status":{"type":"string","title":"Status"},"response_status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","webhook_id","workflow_id","event_type","attempt_number","status","created_at"],"title":"PublicWebhookDeliveryResponse"},"RemoveLeadsRequest":{"properties":{"lead_ids":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Lead Ids"}},"additionalProperties":false,"type":"object","required":["lead_ids"],"title":"RemoveLeadsRequest"},"RemoveLeadsResponse":{"properties":{"list_id":{"type":"string","title":"List Id"},"removed":{"type":"integer","title":"Removed"}},"additionalProperties":false,"type":"object","required":["list_id","removed"],"title":"RemoveLeadsResponse"},"RunSmartAgentRequest":{"properties":{"list_id":{"type":"string","title":"List Id"},"agent_type":{"type":"string","enum":["custom_ai","cold_intro_email","title_normalizer","company_intel","pain_point_hypothesis"],"title":"Agent Type","default":"custom_ai"},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt"},"column_name":{"type":"string","maxLength":100,"minLength":1,"title":"Column Name"},"lead_scope":{"type":"string","enum":["subset","all"],"title":"Lead Scope","default":"subset"},"max_rows":{"type":"integer","maximum":10000.0,"minimum":1.0,"title":"Max Rows","default":100},"quote_id":{"type":"string","title":"Quote Id"},"overwrite":{"type":"boolean","title":"Overwrite","default":false}},"additionalProperties":false,"type":"object","required":["list_id","column_name","quote_id"],"title":"RunSmartAgentRequest"},"RunSmartAgentResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"smart_agent_task_id":{"type":"string","title":"Smart Agent Task Id"},"smart_agent_task_ids":{"additionalProperties":{"type":"string"},"type":"object","title":"Smart Agent Task Ids"},"status":{"type":"string","title":"Status"},"list_id":{"type":"string","title":"List Id"},"column_name":{"type":"string","title":"Column Name"},"estimated_cost":{"type":"integer","title":"Estimated Cost"}},"additionalProperties":false,"type":"object","required":["smart_agent_task_id","status","list_id","column_name","estimated_cost"],"title":"RunSmartAgentResponse","description":"Three identifiers can live on this response (T1-6 ID-space rename):\n\n- `smart_agent_task_id` — canonical id for polling\n  `get_smart_agent_results`.\n- `smart_agent_task_ids` — dict keyed by column type when\n  `process_smart_columns` returns multiple underlying task ids.\n- `task_id` (from EnvelopeFields) — kept populated for back-compat\n  with v1.0 callers that read it from the envelope.\n\nThe three are distinct identifiers. A smart-column run's id is NOT\nan MCP cohort handle, but the envelope still carries `task_id` for\ntransitional compat. New callers should read `smart_agent_task_id`."},"SimilarCompaniesRequest":{"properties":{"company_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Domain"},"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":25}},"additionalProperties":false,"type":"object","title":"SimilarCompaniesRequest"},"SimilarCompaniesResponse":{"properties":{"reference_company":{"type":"string","title":"Reference Company"},"results":{"items":{"$ref":"#/components/schemas/SimilarCompanyRow"},"type":"array","title":"Results"}},"additionalProperties":false,"type":"object","required":["reference_company","results"],"title":"SimilarCompaniesResponse"},"SimilarCompanyRow":{"properties":{"company_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Id"},"name":{"type":"string","title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"similarity_score":{"type":"number","title":"Similarity Score"}},"additionalProperties":false,"type":"object","required":["name","similarity_score"],"title":"SimilarCompanyRow"},"SingleEnrichmentResultRead":{"properties":{"lead_id":{"type":"string","title":"Lead Id"},"status":{"type":"string","title":"Status"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"email_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Status"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company"},"enrichment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Enrichment Type"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"}},"additionalProperties":false,"type":"object","required":["lead_id","status"],"title":"SingleEnrichmentResultRead","description":"Inline enriched-lead payload for single-workflow polls.\n\nPopulated by `enrich_status` only when the workflow is a single-\nlead `enrich_person` run AND has reached a terminal state. Read\nfrom the workflow's returned `EnrichmentResult` via Temporal's\nhistory — no extra DB round-trip, no race with backend visibility.\nBulk-list runs leave `result=None` on the parent response (the\naggregate counters carry the cohort's progress instead).\n\n`status` here is the EnrichmentResult-level outcome\n(\"completed\" / \"failed\"), NOT the outer workflow status. Use it\nto distinguish a real enrichment (Lead persisted, lead_id set)\nfrom a workflow that returned cleanly with no usable Lead (e.g.\nprovider cascade exhausted — `lead_id` will be empty)."},"SmartAgentResultRow":{"properties":{"lead_id":{"type":"string","title":"Lead Id"},"value":{"anyOf":[{},{"type":"null"}],"title":"Value"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"additionalProperties":false,"type":"object","required":["lead_id"],"title":"SmartAgentResultRow"},"SmartAgentResultsResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"smart_agent_task_id":{"type":"string","title":"Smart Agent Task Id"},"status":{"type":"string","title":"Status"},"progress":{"type":"integer","title":"Progress"},"total":{"type":"integer","title":"Total"},"succeeded":{"type":"integer","title":"Succeeded"},"failed":{"type":"integer","title":"Failed"},"results":{"items":{"$ref":"#/components/schemas/SmartAgentResultRow"},"type":"array","title":"Results"}},"additionalProperties":false,"type":"object","required":["smart_agent_task_id","status","progress","total","succeeded","failed","results"],"title":"SmartAgentResultsResponse"},"SmartAgentRun":{"properties":{"task_id":{"type":"string","title":"Task Id"},"list_id":{"type":"string","title":"List Id"},"column_name":{"type":"string","title":"Column Name"},"agent_type":{"type":"string","title":"Agent Type"},"status":{"type":"string","title":"Status"},"total":{"type":"integer","title":"Total","default":0},"processed":{"type":"integer","title":"Processed","default":0},"failed":{"type":"integer","title":"Failed","default":0},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"additionalProperties":false,"type":"object","required":["task_id","list_id","column_name","agent_type","status"],"title":"SmartAgentRun"},"SyncCrmRequest":{"properties":{"provider":{"type":"string","enum":["hubspot","salesforce","outreach"],"title":"Provider"},"list_id":{"type":"string","title":"List Id"},"sub_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Action","description":"Provider-specific record type. HubSpot=contacts (default), Salesforce=leads (default) | contacts, Outreach=sequence. Omit to use the provider default."},"sequence_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sequence Id","description":"For Outreach: the sequence id to enroll Contacts into. Forwarded to the internal migration as `campaign_id`."},"field_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Field Mapping"},"quote_id":{"type":"string","title":"Quote Id"},"approved":{"type":"boolean","title":"Approved","description":"Must be true. External-write safety gate.","default":false}},"additionalProperties":false,"type":"object","required":["provider","list_id","quote_id"],"title":"SyncCrmRequest"},"SyncResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"workflow_id":{"type":"string","title":"Workflow Id"},"status":{"type":"string","enum":["completed","pending","failed"],"title":"Status"},"provider":{"type":"string","title":"Provider"},"list_id":{"type":"string","title":"List Id"},"total_leads":{"type":"integer","title":"Total Leads"},"successful":{"type":"integer","title":"Successful"},"failed":{"type":"integer","title":"Failed"},"estimated_cost":{"type":"integer","title":"Estimated Cost"},"credits_charged":{"type":"integer","title":"Credits Charged"}},"additionalProperties":false,"type":"object","required":["workflow_id","status","provider","list_id","total_leads","successful","failed","estimated_cost","credits_charged"],"title":"SyncResponse"},"SyncSequencerRequest":{"properties":{"provider":{"type":"string","const":"lemlist","title":"Provider"},"list_id":{"type":"string","title":"List Id"},"campaign_id":{"type":"string","title":"Campaign Id","description":"Target Lemlist campaign id."},"field_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Field Mapping"},"quote_id":{"type":"string","title":"Quote Id"},"approved":{"type":"boolean","title":"Approved","description":"Must be true. External-write safety gate.","default":false}},"additionalProperties":false,"type":"object","required":["provider","list_id","campaign_id","quote_id"],"title":"SyncSequencerRequest"},"UsageGroupRow":{"properties":{"group":{"type":"string","title":"Group"},"calls":{"type":"integer","title":"Calls"},"credits_spent":{"type":"integer","title":"Credits Spent"},"errors":{"type":"integer","title":"Errors"}},"additionalProperties":false,"type":"object","required":["group","calls","credits_spent","errors"],"title":"UsageGroupRow"},"UsageReportResponse":{"properties":{"days":{"type":"integer","title":"Days"},"group_by":{"type":"string","title":"Group By"},"total_calls":{"type":"integer","title":"Total Calls"},"total_credits_spent":{"type":"integer","title":"Total Credits Spent"},"total_errors":{"type":"integer","title":"Total Errors"},"rows":{"items":{"$ref":"#/components/schemas/UsageGroupRow"},"type":"array","title":"Rows"}},"additionalProperties":false,"type":"object","required":["days","group_by","total_calls","total_credits_spent","total_errors","rows"],"title":"UsageReportResponse"},"ValidateApiKeyResponse":{"properties":{"valid":{"type":"boolean","title":"Valid"},"user_id":{"type":"string","title":"User Id"},"organization_id":{"type":"string","title":"Organization Id"}},"type":"object","required":["valid","user_id","organization_id"],"title":"ValidateApiKeyResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WhoamiResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"user_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Email"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"user_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Name"},"organization_id":{"type":"string","title":"Organization Id"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"auth_type":{"type":"string","enum":["clerk_jwt","api_key","oauth"],"title":"Auth Type"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"tier":{"type":"string","enum":["free","starter","pro","enterprise"],"title":"Tier"},"features":{"items":{"type":"string"},"type":"array","title":"Features"}},"additionalProperties":false,"type":"object","required":["user_email","organization_id","auth_type","scopes","tier","features"],"title":"WhoamiResponse"},"WorkflowStatusResponse":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"timestamp_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Timestamp Ms"},"agent_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Instructions"},"usage":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"workflow_id":{"type":"string","title":"Workflow Id"},"status":{"type":"string","title":"Status"},"progress":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"processed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Processed"},"completed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Completed"},"failed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Failed"},"enrichment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Enrichment Type"},"lead_list_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lead List Id"},"summary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Summary"},"refund_status":{"anyOf":[{"type":"string","enum":["not_applicable","pending_review"]},{"type":"null"}],"title":"Refund Status"},"refund_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refund Message"},"result":{"anyOf":[{"$ref":"#/components/schemas/SingleEnrichmentResultRead"},{"type":"null"}]},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged"},"credits_refunded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Refunded"}},"additionalProperties":false,"type":"object","required":["workflow_id","status"],"title":"WorkflowStatusResponse"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Public API (Legacy)","description":"Legacy public API operations"},{"name":"Public Workspace","description":"Workspace, credits, usage"},{"name":"Public Lead Lists","description":"Lead list management"},{"name":"Public People Search","description":"People search"},{"name":"Public Companies Search","description":"Company search"},{"name":"Public Enrichment","description":"Enrichment operations"},{"name":"Public Smart Agents","description":"Smart agent runs"},{"name":"Public Sync","description":"Cohort sync"},{"name":"Public Export","description":"Data export"}],"servers":[{"url":"https://api.cleanlist.ai","description":"Production"},{"url":"http://localhost:8000","description":"Local development"}]}