{"version":"v1","generated_at":"2026-07-14T00:52:34.156Z","api":{"version":"v1","basePath":"/api/v1","auth":{"header":"X-API-Key","scopes":["search","profiles-read","enrich","communications","contacts-read","contacts-write","contacts-delegate-resolve"]},"pagination":{"limitParam":"limit","offsetParam":"offset"},"limits":{"resultsSnapshotMax":25,"previewEnrichable":false},"endpoints":[{"method":"GET","path":"/api/v1/credits","category":"credits","description":"Fetch the shared account credit-pool summary for the authenticated API key, current-key usage counters, the active search rate card, and billing semantics for each public API operation.","request":{"range":"string (optional, 7d|14d|30d|90d|today|all_time)","start_date":"string (optional, ISO date/time)","end_date":"string (optional, ISO date/time)"},"response":{"success":"boolean","owner_user_id":"uuid","current_api_key":"CurrentApiKey","current_key_usage":"CurrentApiKeyUsage","account_credit_pool":"object","rate_card":"object","billing_semantics":"CreditBillingSemanticsEntry[]","notes":"string[]"}},{"method":"GET","path":"/api/v1/credits/status","category":"credits","description":"Lightweight rolling-window credit status for the authenticated API key owner. Returns { tier, limit, used, remaining, window_start, window_days, reset_at, as_of }. Mirrors the X-Carl-Credits-* response headers emitted on every authenticated call. Safe to poll — remains reachable at or over the credit ceiling.","response":{"tier":"string (free|starter|starter_annual|pro|annual|team)","limit":"number|null","used":"number","remaining":"number|null","window_start":"string|null (RFC 3339; null when no usage in the current window)","window_days":"number","reset_at":"string|null (RFC 3339; null when no usage in the current window)","as_of":"string (RFC 3339)"}},{"method":"GET","path":"/api/v1/contacts/reconciliation/schema","scopes":["contacts-read","search"],"category":"contacts","description":"Return the public contact reconciliation row schema, supported modes, review actions, and batch limits for agent-assisted spreadsheet reconciliation. Existing MCP connector keys with the legacy search scope can use this read-only compatibility path.","request":{"delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","tool":"contacts_reconcile","source_type":"agent_reconciliation_sheet","row_schema":"object","modes":"string[]","review_actions":"string[]","notes":"string[]"}},{"method":"POST","path":"/api/v1/contacts/delegate-resolve","scopes":["contacts-delegate-resolve"],"category":"contacts","description":"API-key-only batch contact resolver for integrations that need to resolve contacts from the perspective of a supplied delegate person instead of the API key owner. The delegate is required and can be supplied by Super Carl id or LinkedIn URL/username. The endpoint accepts up to 100 contacts per call and returns compact resolved-profile projections plus evidence/reasons. It is intentionally not exposed through MCP or OAuth connector scopes.","request":{"delegate":"{ user_id | super_carl_id | linkedin_url | linkedin_username } (required)","contacts":"DelegateContactInput[] (required, max 100; supports name, emails, phone_numbers, organization_names, job_titles, address/location, LinkedIn URL)","options":"object (optional: dry_run, persist_evidence, include_email, include_email_enrichment, force_email_enrichment, email_enrichment_provider, email_minimum_confidence, fields, include_experiences, include_score_breakdown, max_candidates_per_contact, contact_concurrency)"},"response":{"success":"boolean","mode":"delegate_contact_resolve","dry_run":"boolean","persisted_evidence_count":"number","audit_run_id":"uuid|null","billing":"{ charged, billable_preview_count, billable_resolve_count, billable_email_enrichment_count, preview_credits_charged, resolve_credits_charged, email_enrichment_credits_charged, total_credits_charged }","delegate":"ResolvedDelegate","summary":"{ requested, resolved, needs_review, unresolved }","results":"DelegateContactResolveResult[] (includes selected_candidate_user_id, selected_profile projection including email when available/requested, email_resolution, evidence, candidates, warnings)"},"notes":["This route rejects OAuth/MCP-authenticated calls even if a token carries compatible scopes; use X-API-Key.","Performance: each request accepts up to 100 contacts and resolves up to 5 contacts concurrently by default. contact_concurrency can tune the per-request worker count from 1 to 10.","Billing: dry_run=true charges a lightweight preview fee of 0.01 credits per requested contact and does not persist evidence. Non-dry-run calls charge only high-confidence resolved rows at 0.10 credits each. Needs-review, unresolved, delegate 404, and validation failures are free for non-dry-run resolve billing.","Email projection is included by default when a cached/known email exists. Provider email enrichment runs only when include_email_enrichment=true, and successful provider enrichments add 0.04 credits each, including dry-run requests that explicitly ask the provider to run. Set email_minimum_confidence to require a stronger returned email quality such as validated, sourced, or verified.","Evidence persistence is opt-in with options.persist_evidence=true and options.dry_run=false. Persisted phone/email signals are hashed for future peer-evidence support.","Result evidence omits peer owner identities and support counts."]},{"method":"POST","path":"/api/v1/contacts/reconciliation/runs","scopes":["contacts-read","search"],"category":"contacts","description":"Create a bounded contact reconciliation run for a user-supplied spreadsheet or agent-normalized contact sheet. This sets up workflow/audit state only; applying changes still requires contacts-write.","request":{"delegate_user_id":"uuid (optional)","source_label":"string (optional)","options":"object (optional; allow_identity_resolution, identity_resolution_limit)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","run":"ContactReconciliationRun"}},{"method":"POST","path":"/api/v1/contacts/reconciliation/runs/:runId/batches/preview","scopes":["contacts-read","search"],"category":"contacts","description":"Preview up to 100 normalized spreadsheet rows before applying them. Preview writes audit rows for the reconciliation run but does not mutate contact state, and remains available to existing MCP connector keys with the legacy search scope.","request":{"delegate_user_id":"uuid (optional)","batch_index":"number (optional)","rows":"ContactReconciliationRow[] (required, max 100)","options":"object (optional)"},"response":{"success":"boolean","run":"ContactReconciliationRun","batch_id":"uuid","summary":"object","rows":"ContactReconciliationPlannedRow[]"}},{"method":"POST","path":"/api/v1/contacts/reconciliation/runs/:runId/batches","scopes":["contacts-write"],"category":"contacts","description":"Apply a reviewed batch of up to 100 normalized spreadsheet rows. Likely matches remain candidates until a later explicit confirm action.","request":{"delegate_user_id":"uuid (optional)","batch_index":"number (optional)","rows":"ContactReconciliationRow[] (required, max 100)","options":"object (optional; allow_identity_resolution only affects apply)","user_confirmed":"boolean (required true)"},"response":{"success":"boolean","run":"ContactReconciliationRun","batch_id":"uuid","summary":"object","rows":"ContactReconciliationAppliedRow[]"}},{"method":"GET","path":"/api/v1/contacts/reconciliation/runs/:runId","scopes":["contacts-read","search"],"category":"contacts","description":"Read reconciliation run status, aggregate row summary, and recent batch metadata.","request":{"delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","run":"ContactReconciliationRun","summary":"object","batches":"ContactReconciliationBatch[]"}},{"method":"POST","path":"/api/v1/contacts/reconciliation/runs/:runId/finalize","scopes":["contacts-write"],"category":"contacts","description":"Finalize a reconciliation run after reviewed batches are applied.","request":{"delegate_user_id":"uuid (optional)","user_confirmed":"boolean (required true)"},"response":{"success":"boolean","run":"ContactReconciliationRun","summary":"object"}},{"method":"GET","path":"/api/v1/contacts/reconciliation/review","scopes":["contacts-read","search"],"category":"contacts","description":"List contact review entities in the same buckets exposed by the incoming/review tab, including likely_match, needs_review, unresolved, approved, and ignored.","request":{"delegate_user_id":"uuid (optional)","bucket":"string (optional, approved|likely_match|needs_review|unresolved|ignored)","limit":"number (optional, max 100)","offset":"number (optional)","response_verbosity":"string (optional, compact|minimal|detailed; use compact for 100-row triage pages)"},"response":{"success":"boolean","items":"ContactReviewEntity[]","pagination":"object"}},{"method":"POST","path":"/api/v1/contacts/reconciliation/review/bulk","scopes":["contacts-write"],"category":"contacts","description":"Apply up to 100 explicit review actions in one call. Bulk confirm can use entity_ids alone to confirm each row's stored proposed/top candidate, or items with per-row candidate_user_id overrides.","request":{"delegate_user_id":"uuid (optional)","action":"confirm_candidate|reject_candidate|mark_needs_review|ignore_entity|restore_entity","entity_ids":"uuid[] (optional, max 100)","items":"array (optional, max 100; entity_id, candidate_user_id, candidate_snapshot)","user_confirmed":"boolean (required true)"},"response":{"success":"boolean","requested_count":"number","succeeded_count":"number","failed_count":"number","results":"BulkReviewResult[]"}},{"method":"GET","path":"/api/v1/contacts/reconciliation/review/:entityId/candidates","scopes":["contacts-read","search"],"category":"contacts","description":"Fetch candidate Super Carl user matches for one contact review entity before confirming or rejecting.","request":{"delegate_user_id":"uuid (optional)","query":"string (optional)","limit":"number (optional, max 25)"},"response":{"success":"boolean","entity":"ContactReviewEntity","candidates":"ContactReviewCandidate[]"}},{"method":"POST","path":"/api/v1/contacts/reconciliation/review/:entityId/confirm","scopes":["contacts-write"],"category":"contacts","description":"Confirm one specific candidate user for a contact review entity. This is the explicit promotion step for likely matches.","request":{"delegate_user_id":"uuid (optional)","candidate_user_id":"uuid","candidate_snapshot":"object (optional)","user_confirmed":"boolean (required true)"},"response":{"success":"boolean","entity":"ContactReviewEntity"}},{"method":"POST","path":"/api/v1/contacts/reconciliation/review/:entityId/:action","scopes":["contacts-write"],"category":"contacts","description":"Review mutation endpoint for needs-review, not-a-match, ignore, and restore actions. These mirror the incoming/review tab controls.","request":{"delegate_user_id":"uuid (optional)","action":"path segment: needs-review|not-a-match|ignore|restore","user_confirmed":"boolean (required true)"},"response":{"success":"boolean","entity":"ContactReviewEntity"}},{"method":"POST","path":"/api/v1/search/people","scopes":["search"],"category":"people-search","description":"Run a full people search or direct lookup by LinkedIn username or full LinkedIn profile URL. The description (or query alias) is auto-translated into AdvancedFilters by default; pass filters/search_metadata for explicit structured constraints. New lookups are enriched automatically. Set include_evidence_text=true or include_evidence_json=true to inline profile evidence for eval or LLM ranking workflows. Person rows include requester-relative previous-correspondence fields across synced/API channels when a Super Carl user identity is resolved.","request":{"description":"string","query":"string (legacy alias)","keywords":"string|array (deprecated)","limit":"number","offset":"number","linkedin_username":"string (optional)","linkedin_profile_url":"string (optional)","linkedin_url":"string (optional alias for linkedin_profile_url)","search_metadata":"object","filters":"object (optional)","include_evidence":"boolean (optional; defaults to text evidence when true)","include_evidence_text":"boolean (optional)","include_evidence_json":"boolean (optional)","evidence_format":"string (optional, none|reasons|text|json|both; reasons builds LLM match_reasons)","evidence_text_mode":"string (optional, base|full)","evidence_posts_limit":"number (optional)","defer_enrichment":"boolean (optional; skip enrichment on non-reasons calls)","skip_match_reasons":"boolean (optional; skip LLM match reasons unless evidence_format=reasons)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","search_id":"string","users":"Person[]","pagination":"object","search_metadata":"object","no_results_reason":"string (optional, present when total results are zero and a deterministic reason is available)"}},{"method":"POST","path":"/api/v1/communications/capabilities","scopes":["communications"],"category":"communications","description":"Resolve the acting user, target identity, and per-channel readiness for Super Carl direct messages, Super Carl invites, Super Carl referrals, Gmail sends, LinkedIn sends, X sends, and Instagram sends.","request":{"delegate_user_id":"uuid (optional)","target_user_id":"uuid (optional)","linkedin_profile_url":"string (optional)","linkedin_username":"string (optional)","x_profile_url":"string (optional)","x_username":"string (optional)","instagram_profile_url":"string (optional)","instagram_username":"string (optional)","recipient_email":"string (optional; for Gmail, may be a returned option or a valid user-supplied address)","channels":"string[] (optional; any of supercarl_direct_message, supercarl_invite, supercarl_referral_request, gmail_send, linkedin_send_message, x_send_message, instagram_send_message)"},"response":{"owner_user_id":"uuid","acting_user_id":"uuid","is_delegate":"boolean","resolved_target":"object","channels":"CommunicationChannelCapability[]","supercarl":"object"}},{"method":"POST","path":"/api/v1/communications","scopes":["communications"],"category":"communications","description":"Create a generic outbound communication record and send, invite, request referral, save a durable draft, or dry-run delivery through one of the supported channels.","request":{"delegate_user_id":"uuid (optional)","mode":"\"draft\" (optional; saves without delivery)","draft":"boolean (optional; alias for mode=\"draft\")","channel":"string (one of supercarl_direct_message, supercarl_invite, supercarl_referral_request, gmail_send, linkedin_send_message, x_send_message, instagram_send_message)","target_user_id":"uuid (optional)","linkedin_profile_url":"string (optional)","linkedin_username":"string (optional)","x_profile_url":"string (optional)","x_username":"string (optional)","instagram_profile_url":"string (optional)","instagram_username":"string (optional)","recipient_email":"string (optional; for Gmail, may be a returned option or a valid user-supplied address)","connector_user_id":"uuid (optional; required for supercarl_referral_request)","message":"string","subject":"string (required for gmail_send)","dry_run":"boolean (optional)","idempotency_key":"string (optional)","context":"object (optional; structured context for generation or audit metadata)","wait_ms":"number (optional; wait up to this many milliseconds for delivery progress, max 30000)","wait_until":"string (optional, terminal|first_progress; wait condition when wait_ms is set)","webhook_url":"string (optional)","webhook_secret":"string (optional)"},"response":{"id":"uuid","channel":"string","status":"string","result":"object","task":"CommunicationTask|null","reasoning_lookup":"CommunicationReasoningLookup","events":"CommunicationEvent[]","artifacts":"CommunicationArtifact[]"}},{"method":"GET","path":"/api/v1/communications/:communicationId","scopes":["communications"],"category":"communications","description":"Fetch a communication record with normalized status, recent events, task metadata, reasoning lookup, and artifact URLs.","request":{"wait_ms":"number (optional; wait up to this many milliseconds for delivery progress, max 30000)","wait_until":"string (optional, terminal|first_progress; wait condition when wait_ms is set)"},"response":{"id":"uuid","channel":"string","status":"string","result":"object","task":"CommunicationTask|null","reasoning_lookup":"CommunicationReasoningLookup","events":"CommunicationEvent[]","artifacts":"CommunicationArtifact[]","webhook":"CommunicationWebhook"}},{"method":"POST","path":"/api/v1/communications/history","scopes":["communications"],"category":"communications","description":"Fetch prior visible communication history for a resolved target before drafting or sending.","request":{"delegate_user_id":"uuid (optional)","target_user_id":"uuid (optional)","linkedin_profile_url":"string (optional)","linkedin_username":"string (optional)","x_profile_url":"string (optional)","x_username":"string (optional)","instagram_profile_url":"string (optional)","instagram_username":"string (optional)","recipient_email":"string (optional)","channel":"string (optional, all|email|gmail|super_carl|linkedin|x|instagram)","history_fresh":"boolean (optional; request a fresh LinkedIn history refresh when possible)","limit":"number (optional, 1-50)","offset":"number (optional)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","is_delegate":"boolean","resolved_target":"object","target_user_id":"uuid|null","has_prior_send":"boolean","most_recent_send":"object|null","total_count":"number","filtered_count":"number","last_sent_at":"string|null","limit":"number","offset":"number","has_more":"boolean","selected_channel":"string","channel_counts":"object","linkedin_history":"object","entries":"CommunicationHistoryEntry[]"}},{"method":"POST","path":"/api/v1/communications/:communicationId/cancel","scopes":["communications"],"category":"communications","description":"Cancel a queued or in-progress communication when the underlying channel supports cancellation before dispatch.","request":{"reason":"string (optional)"},"response":{"id":"uuid","channel":"string","status":"string","result":"object","task":"CommunicationTask|null","reasoning_lookup":"CommunicationReasoningLookup","events":"CommunicationEvent[]","artifacts":"CommunicationArtifact[]","webhook":"CommunicationWebhook"}},{"method":"GET","path":"/api/v1/communications/:communicationId/events","scopes":["communications"],"category":"communications","description":"Fetch the append-only communication event log.","request":{"after_sequence":"number (optional)","limit":"number (optional)"},"response":{"communication_id":"uuid","events":"CommunicationEvent[]"}},{"method":"GET","path":"/api/v1/communications/:communicationId/stream","scopes":["communications"],"category":"communications","description":"Server-sent events stream for communication status changes, artifacts, and completion.","response":{"content_type":"text/event-stream"}},{"method":"GET","path":"/api/v1/communications/:communicationId/artifacts/:filename","scopes":["communications"],"category":"communications","description":"Proxy an artifact or screenshot attached to a communication.","response":{"content_type":"binary"}},{"method":"GET","path":"/api/v1/projects","scopes":["communications"],"category":"projects","description":"List active projects for the authenticated owner or delegate. Projects are the public name for assignment workspaces. Pass current_project_id for an MCP/session-bound project that must be surfaced even when generic list filters would hide it.","request":{"delegate_user_id":"uuid (optional)","status":"string (optional)","limit":"number (optional)","offset":"number (optional)","include_archived":"boolean (optional)","include_searches":"boolean (optional; include search-only project shells)","current_project_id":"uuid (optional; session-bound project to include even if filtered out)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","is_delegate":"boolean","projects":"Project[]","current_session_project_id":"uuid | null (when current_project_id is supplied)","current_session_project":"Project | null (when current_project_id is supplied)","current_session_project_included":"boolean (when current_project_id is supplied)","current_session_project_reason":"already_in_list | included_from_session_binding | not_found_or_inaccessible","pagination":"object"}},{"method":"GET","path":"/api/v1/projects/:projectId","scopes":["communications"],"category":"projects","description":"Fetch one project. Set include_targets=true to inline targets, and include_search_results=true to include the search-results cache.","request":{"delegate_user_id":"uuid (optional)","include_targets":"boolean (optional)","include_search_results":"boolean (optional)","targets_limit":"number (optional)","targets_offset":"number (optional)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project":"Project"}},{"method":"GET","path":"/api/v1/projects/:projectId/targets","scopes":["communications"],"category":"projects","description":"List active included targets for a project, excluding the project owner. This is the standalone API equivalent of the product target list.","request":{"delegate_user_id":"uuid (optional)","limit":"number (optional, max 100)","offset":"number (optional)","include_mutuals":"boolean (optional)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","targets":"ProjectTarget[]","pagination":"object"}},{"method":"POST","path":"/api/v1/projects/:projectId/targets","scopes":["communications"],"category":"projects","description":"Add one or more people to a project shortlist. This is the standalone API equivalent of adding assignment targets in-product.","request":{"delegate_user_id":"uuid (optional)","target_user_ids":"uuid[] (required unless target_user_id is provided)","target_user_id":"uuid (optional single target)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","added_targets":"ProjectTarget[]","total_targets":"number"}},{"method":"DELETE","path":"/api/v1/projects/:projectId/targets","scopes":["communications"],"category":"projects","description":"Remove one or more people from a project shortlist by soft-clearing is_included. Pass remove_all=true only when intentionally clearing the shortlist.","request":{"delegate_user_id":"uuid (optional)","target_user_ids":"uuid[] (required unless target_user_id or remove_all is provided)","target_user_id":"uuid (optional single target)","remove_all":"boolean (optional)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","removed_count":"number","results":"TargetRemovalResult[]"}},{"method":"GET","path":"/api/v1/projects/:projectId/metrics","scopes":["communications"],"category":"projects","description":"Fetch outreach metrics for a project, including response rates, schedule-link click rates, and status-count breakdowns.","request":{"delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","project_id":"uuid","total_targets":"number","messages_sent":"number","responses":"number","response_rate":"number|null","target_response_rate":"number|null","schedule_link_clicks":"number","schedule_link_click_rate":"number|null","outreach_status_counts":"object","recipient_status_counts":"object"}},{"method":"PATCH","path":"/api/v1/projects/:projectId","scopes":["communications"],"category":"projects","description":"Rename a project or update basic project fields such as description, pitch, status, discovery, and engagement mode.","request":{"delegate_user_id":"uuid (optional)","title":"string (optional)","description":"string (optional)","pitch":"string (optional)","status":"string (optional)","allow_discovery":"boolean (optional)","engagement_mode":"string (optional)"},"response":{"success":"boolean","project":"Project"}},{"method":"PUT","path":"/api/v1/projects/:projectId/templates","scopes":["communications"],"category":"projects","description":"Update saved project outreach/referral/engagement templates. Set clear_personalization=true to clear generated target messages for regeneration.","request":{"delegate_user_id":"uuid (optional)","email_subject_template":"string|null (optional)","outreach_message_prompt":"string|null (optional)","engagement_meta_prompt":"string|null (optional)","engagement_prompt":"string|null (optional)","referral_intro_prompt":"string|null (optional)","referral_forward_note_prompt":"string|null (optional)","clear_personalization":"boolean (optional)"},"response":{"success":"boolean","project":"Project"}},{"method":"POST","path":"/api/v1/projects/:projectId/templates/generate","scopes":["communications"],"category":"projects","description":"Generate or regenerate a saved project template against project context. Supported template_type values include email_subject_template, outreach_message_prompt, engagement_meta_prompt, engagement_prompt, pitch, referral_intro_prompt, referral_forward_note_prompt, and generalize_message_to_template.","request":{"delegate_user_id":"uuid (optional)","template_type":"string","user_input":"string (optional)","message":"string (required for generalize_message_to_template)"},"response":{"success":"boolean","project":"Project","generated_field":"string (template-specific field, e.g. outreach_message_prompt)"}},{"method":"POST","path":"/api/v1/projects/:projectId/messages/generate","scopes":["communications"],"category":"projects","description":"Generate personalized target messages against saved project templates. This drafts/generates messages; it does not send them.","request":{"delegate_user_id":"uuid (optional)","target_ids":"uuid[] (optional assignment target row ids; omit to generate for all targets needing messages)","target_user_id":"uuid (optional; generate for one target user)","persist_target":"boolean (optional; default true for target_user_id)"},"response":{"success":"boolean","generated_count":"number","targets":"ProjectTarget[]"}},{"method":"PUT","path":"/api/v1/projects/:projectId/target-users/:targetUserId/message","scopes":["communications"],"category":"projects","description":"Save an exact draft message for one project target by target user id. This updates the reviewable project draft and does not send it.","request":{"delegate_user_id":"uuid (optional)","message":"string","message_source":"ai_generated|user_edited (optional)","review_action":"save|approve (optional; use approve only after explicit approval)","contact_channel":"string (optional, e.g. gmail_send or linkedin_send_message)","recipient_email":"string (optional for Gmail delivery; may be a returned option or a valid user-supplied address)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","target_user_id":"uuid","target":"ProjectTarget"}},{"method":"PUT","path":"/api/v1/projects/:projectId/targets/:targetId/message","scopes":["communications"],"category":"projects","description":"Save an exact draft message for one project target by assignment target row id. This updates the reviewable project draft and does not send it.","request":{"delegate_user_id":"uuid (optional)","message":"string","message_source":"ai_generated|user_edited (optional)","review_action":"save|approve (optional; use approve only after explicit approval)","contact_channel":"string (optional)","recipient_email":"string (optional for Gmail delivery; may be a returned option or a valid user-supplied address)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","assignment_target_id":"uuid","target":"ProjectTarget"}},{"method":"GET","path":"/api/v1/projects/:projectId/send-readiness","scopes":["communications"],"category":"projects","description":"Read the project send-confirm readiness summary: ready target count, previewed/not-previewed/edited/stale breakdown, stale target ids, and delivery-channel buckets.","request":{"delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","summary":"ProjectSendReadinessSummary"}},{"method":"POST","path":"/api/v1/projects/:projectId/activate","scopes":["communications"],"category":"projects","description":"Start delivery for a reviewed project. Eligible included targets are marked for dispatch, the project becomes active, and channel-specific queues handle LinkedIn daily caps and automatic resume.","request":{"delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","owner_user_id":"uuid","acting_user_id":"uuid","project_id":"uuid","message":"string","project":"Project"}},{"method":"POST","path":"/api/v1/search/people/preview","scopes":["search"],"category":"people-search","description":"Run a preview people search (auto-translated description/query, no enrichment, not enrichable). LinkedIn lookup is not supported. include_evidence_text is optional when you need inline profile evidence on preview rows.","request":{"description":"string","query":"string (legacy alias)","keywords":"string|array (deprecated)","limit":"number","offset":"number","search_metadata":"object","filters":"object (optional)","include_evidence_text":"boolean (optional)","evidence_text_mode":"string (optional, base|full)","evidence_posts_limit":"number (optional)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","search_id":"null","users":"Person[]","pagination":"object","search_metadata":"object"}},{"method":"POST","path":"/api/v1/search/people/enrich","scopes":["enrich"],"category":"people-search","description":"Re-run a full search with enrichment enabled using a search_id. Provide target_user_id to enrich one user, or omit it to enrich the current page of results. include_evidence_text can be supplied here even if the original search omitted it.","request":{"search_id":"string","limit":"number (optional)","offset":"number (optional)","target_user_id":"uuid (optional)","include_evidence_text":"boolean (optional)","evidence_text_mode":"string (optional, base|full)","evidence_posts_limit":"number (optional)"},"response":{"success":"boolean","users":"Person[]","pagination":"object","enrichment":"object"}},{"method":"POST","path":"/api/v1/companies/search/preview","scopes":["search"],"category":"companies","description":"Search companies in preview or detailed mode. Natural language queries are translated into company filters; returns a company search_id for follow-on people search joins. Set result_mode=detailed to expand each row with richer company fields, and include_evidence_text=true to inline evidence text built from stored company docs/posts.","request":{"query":"string","description":"string (optional alias for query)","filters":"object (optional)","preview_limit":"number (optional)","result_mode":"string (optional, preview|detailed)","include_evidence_text":"boolean (optional)","evidence_post_limit":"number (optional)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","companies":"array","pagination":"object","filters":"object","company_resolution":"object","annotationPayload":"object"}},{"method":"POST","path":"/api/v1/search/jobs/preview","scopes":["search"],"category":"jobs","description":"Natural-language job search scored against the viewer social-graph overlay. Accepts the full AdvancedFilters doc (hiring.*, companies.include/exclude, industries, company_stage, locations), including hiring.workplace_types for derived remote/hybrid/onsite/unknown filtering. Each result row is decorated with a network block summarizing 1st/2nd-degree connections the viewer has at the posting company.","request":{"query":"string (optional, natural-language)","filters":"object (optional, AdvancedFilters)","preview_limit":"number (optional, default 10, max 25)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","durationMs":"number","total":"number","preview_limit":"number","delegate_user_id":"uuid|null","viewer_profile":"object|null","applied_filter_summary":"object","network_overlay_status":"JobNetworkOverlayStatus","results":"JobPosting[]","search_activity_id":"uuid|null"}},{"method":"POST","path":"/api/v1/search/jobs/with-people","scopes":["search"],"category":"jobs","description":"The 'map a job to a path in' surface. Groups job_search_preview results by company and returns an inline slice of the viewer's 1st/2nd-degree people at each company. Billed as one preview search; sub-queries are linked via parent_search_activity_id.","request":{"query":"string (optional, natural-language)","filters":"object (optional, AdvancedFilters)","preview_limit":"number (optional, default 10, max 25)","people_per_company":"number (optional, default 3, max 10)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","durationMs":"number","total":"number","companies_in_order":"uuid[]","network_overlay_status":"JobNetworkOverlayStatus","groups":"JobsWithPeopleGroup[]","viewer_profile":"object|null","search_activity_id":"uuid|null"}},{"method":"POST","path":"/api/v1/search/posts/preview","scopes":["search"],"category":"posts","description":"Direct post/activity search over the activities index. Supports hard literal mentions via filters.posts.mentioned, soft expanded topic keywords via filters.posts.additional_context_keywords_core/supporting, action types, engagement counts, date windows, and target company/person/url constraints. Returns matching post rows plus a people_search_binding for pivoting into profile search.","request":{"query":"string (optional, text/topic query)","filters":"object (optional, prefer filters.posts; use mentioned for hard literal mentions and additional_context_keywords_core/supporting + keyword_match_mode=soft for topic/signal recall)","preview_limit":"number (optional, default 10, max 50)","offset":"number (optional)","sort_by":"string (optional, relevance|recent|engagement|reactions|comments)","sort_order":"string (optional, asc|desc)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","durationMs":"number","total":"number","preview_limit":"number","offset":"number","has_more":"boolean","applied_filter_summary":"object","people_search_binding":"object","results":"ActivityPost[]","search_activity_id":"uuid|null"}},{"method":"POST","path":"/api/v1/search/posts/with-people","scopes":["search"],"category":"posts","description":"Post/activity search plus a deduped people set derived from matching post actors/authors. Use for post-first \"who\" questions, then execute people_search_binding when full profile search, relationship detail, or additional structured constraints are needed.","request":{"query":"string (optional, text/topic query)","filters":"object (optional, prefer filters.posts; use mentioned for hard literal mentions and additional_context_keywords_core/supporting + keyword_match_mode=soft for topic/signal recall)","preview_limit":"number (optional, default 10, max 50)","offset":"number (optional)","people_limit":"number (optional, default 25, max 100)","sort_by":"string (optional, relevance|recent|engagement|reactions|comments)","sort_order":"string (optional, asc|desc)","delegate_user_id":"uuid (optional)"},"response":{"success":"boolean","durationMs":"number","total":"number","results":"ActivityPost[]","people":"PostMatchedPerson[]","people_search_binding":"object","search_activity_id":"uuid|null"}},{"method":"GET","path":"/api/v1/profiles/:id/chunks","scopes":["profiles-read"],"category":"profiles","description":"Fetch cached profile chunks (no refresh).","request":{"posts_limit":"number (optional)"},"response":{"success":"boolean","user_id":"uuid","chunks":"ProfileChunk[]"}},{"method":"GET","path":"/api/v1/profiles/:id/text","scopes":["profiles-read"],"category":"profiles","description":"Fetch profile text ready for LLM embeddings or contextual matching.","request":{"mode":"string (optional, base|full; base=embedding input, full=adds posts + company signals)","posts_limit":"number (optional)"},"response":{"success":"boolean","user_id":"uuid","text":"ProfileText"}},{"method":"GET","path":"/api/v1/profiles/:id","scopes":["profiles-read"],"category":"profiles","description":"Fetch a profile snapshot by user id.","response":{"id":"uuid","name":"string","username":"string|null","picture":"string|null","bio":"string|null","location":"string|null","linkedin_url":"string|null","supercarl_url":"string|null","created_at":"string","last_active":"string|null"}}]},"quick_start":{"steps":["Create an API key in Integrations > Connections. API keys are available on any plan; usage still consumes the owner credit pool.","Call /api/v1/credits to inspect the shared account credit pool, current-key usage, and the live search rate card before you scale up.","Poll /api/v1/credits/status (or read X-Carl-Credits-* response headers on any authenticated call) to stay under your 30-day rolling credit ceiling. Exhaustion returns HTTP 402 with a credits_exhausted body — see credit_enforcement in the docs schema.","Lookup a person by LinkedIn username or full LinkedIn profile URL using /api/v1/search/people (linkedin_username or linkedin_profile_url).","Use the returned user_id to fetch cached profile chunks from /api/v1/profiles/:id/chunks.","Call /api/v1/communications/capabilities before sending to learn which channels are actually available for the acting user and target.","Create dry-run or live sends with /api/v1/communications; use GET /api/v1/communications/:id or /stream for status and artifacts.","Use /api/v1/projects to list project workspaces, /targets to list/add/remove shortlist targets, /metrics to read outreach response rates, /templates to update saved templates, /messages/generate to draft personalized target messages, /target-users/:id/message or /targets/:id/message to save exact drafts, /send-readiness to check review state, and /activate to start approved project delivery.","Run people searches with /api/v1/search/people; use description (alias query) which is auto-translated into structured filters unless you supply filters directly.","Use /api/v1/search/people/enrich with a search_id to enrich one result or an entire page."],"note":"All API usage draws from the same account credit pool as in-app searches. Use /api/v1/credits for the live rate card and billing semantics. Communications are currently documented as not separately credit-billed.","curl":"curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"linkedin_profile_url\": \"https://www.linkedin.com/in/reidhoffman/\"\n  }'\n\n# Read cached chunks only\ncurl -X GET https://api.supercarl.ai/api/v1/profiles/<USER_ID>/chunks?posts_limit=10 \\\n  -H \"X-API-Key: <YOUR_API_KEY>\"\n\n# Check message-channel readiness\ncurl -X POST https://api.supercarl.ai/api/v1/communications/capabilities \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"linkedin_profile_url\": \"https://www.linkedin.com/in/reidhoffman/\"\n  }'\n\n# List project workspaces and target response metrics\ncurl -X GET https://api.supercarl.ai/api/v1/projects \\\n  -H \"X-API-Key: <YOUR_API_KEY>\"\n\ncurl -X GET https://api.supercarl.ai/api/v1/projects/<PROJECT_ID>/metrics \\\n  -H \"X-API-Key: <YOUR_API_KEY>\""},"data_scale":{"as_of":"2026-04-03","overview":"Static platform-scale figures for integration planning, agent routing, and evaluation workflows. These are published values, not live query-time counters.","coverage_note":"Current ingest cadence is approximately 75M profile updates per week. That operating rate is intended to support practical LinkedIn-wide coverage as the current rollout completes over the next few weeks.","notes":["These figures are grounded in production ingest programs and are published statically so public endpoints remain cheap and predictable.","The public API focuses on search and enrichment speed; it does not compute expensive live corpus counts per request.","Provider names are intentionally omitted from public metadata. Use the dataset shape and refresh cadence below instead."],"corpus":[{"key":"profiles","label":"Profiles","count":1000000000,"display":"1B+"},{"key":"companies","label":"Companies","count":50000000,"display":"50M+"}],"weekly_updates":[{"key":"profile_updates","label":"Profile updates","count":75000000,"display":"75M+","period":"week"}],"monthly_updates":[{"key":"profile_updates","label":"Profile updates","count":300000000,"display":"300M+","period":"month"},{"key":"company_updates","label":"Company updates","count":50000000,"display":"50M+","period":"month"},{"key":"job_posting_updates","label":"Job posting updates","count":10000000,"display":"10M+","period":"month"},{"key":"post_activity_updates","label":"Post and activity updates","count":25000000,"display":"25M+","period":"month"}]},"mcp":{"connector_url":"https://api.supercarl.ai/mcp","transport":"streamable_http","overview":"Super Carl ships a remote MCP server so agents (Claude, Claude Code, Cursor, Cowork, etc.) can run people / company / job / post search (with social-graph overlay), reconcile contacts, check channel readiness, draft/send communications, and manage project state using the same REST API the web and mobile apps use. The catalog is unified around flag-driven tools: `people_search` and `company_search` both default to `preview: true` so agents can iterate on filters cheaply before spending a search credit; flip to `preview: false` once filters are right to fetch enriched rows. `jobs_search` returns usable job rows by default; set `with_people: true` for the 'map a job to a path in' shape. `posts_search` returns matching post/activity rows by default; set `with_people: true` for a deduped actor/author set and follow `people_search_binding` for full profile search. `contacts_reconcile` previews and applies up to 100 normalized contact rows at a time, exposes compact/minimal review projections, and can bulk confirm/reject up to 100 review rows per call. `project_action` covers project shortlist, drafting, delivery, and Google Sheet output operations for MCP sessions that continue work after search or outreach.","add_to_claude":{"title":"Add Super Carl as a custom connector in Claude","steps":["Open Claude → Settings → Connectors → Add custom connector.","Remote MCP server URL: https://api.supercarl.ai/mcp","Leave Client ID and Client Secret blank — Super Carl supports Dynamic Client Registration (RFC 7591), so Claude registers itself automatically.","Click Add. Claude will open a Super Carl sign-in page; authorize the scopes you want the agent to use.","That's it — your Super Carl tools (agent_session, people_search, people_lookup_batch, company_search, company_search_batch, jobs_search, posts_search, communication_read, project_read, social_proximity_status, watch_signals_read, social_proximity_research, send_communication, project_action, contacts_export, contacts_reconcile, enrich_contacts, x_instagram_sync, watch_signals, query_search_result, get_product_help, super_carl_action) are now available to Claude."],"note":"If Claude prompts for Connector Tool permissions, grant Always allow to read-only search/help tools when appropriate and keep mutating tools such as send_communication and project_action on Needs approval unless you explicitly want Claude to run them without per-call confirmation. Super Carl advertises stable MCP tool metadata and read/write annotations, but persistence of Claude permission choices is controlled by Claude. If you are using Anthropic Cowork, your workspace admin must also allowlist api.supercarl.ai under Admin Settings > Capabilities > Code execution > Network egress > Additional allowed domains. Anthropic does not gate this centrally."},"oauth":{"spec":"OAuth 2.1 + PKCE (S256) + RFC 8707 Resource Indicators","authorization_server":"https://api.supercarl.ai","discovery":{"protected_resource":"https://api.supercarl.ai/.well-known/oauth-protected-resource","authorization_server":"https://api.supercarl.ai/.well-known/oauth-authorization-server","jwks":"https://api.supercarl.ai/.well-known/jwks.json"},"endpoints":{"registration":"https://api.supercarl.ai/oauth/register","authorize":"https://api.supercarl.ai/oauth/authorize","token":"https://api.supercarl.ai/oauth/token"},"scopes_supported":["search","profiles-read","enrich","communications","contacts-read","contacts-write"],"access_token":{"alg":"RS256","audience":"https://api.supercarl.ai/mcp","lifetime_seconds":1800},"refresh_token":{"rotation":true,"lifetime_seconds":2592000},"registration_modes":["Dynamic Client Registration (RFC 7591) — default, no pre-coordination required.","Client ID Metadata Documents — honored when the client_id is an HTTPS URL pointing at a hosted metadata JSON document (planned, not strictly required for directory listing)."],"supported_redirect_uris":["https://claude.ai/api/mcp/auth_callback","https://claude.com/api/mcp/auth_callback","RFC 8252 loopback (http://127.0.0.1:<port>/...) for Claude Code and local MCP clients","Any other HTTPS callback"]},"api_key_alternative":{"overview":"Programmatic / script callers can bypass OAuth and authenticate with a long-lived API key. This is useful for CLI tools, services, and other non-interactive MCP clients.","header":"X-API-Key","scopes":["search","profiles-read","enrich","communications","contacts-read","contacts-write"],"note":"API keys can be created by the account owner under Integrations > Connections on any plan. The /mcp endpoint accepts API keys via X-API-Key or Authorization: Bearer carl_<key>."},"tools":[{"name":"agent_session","scope":"communications","read_only":false,"destructive":false,"modes":["start","list","status","switch_project","close"],"notes":"Starts, resumes, inspects, switches, or closes an MCP agent session. Pass the returned agent_session_id on related search, project, sheet, watch, and communication calls so Super Carl can group the work and bind it to the right project."},{"name":"people_search","scope":"search","read_only":true,"destructive":false},{"name":"people_lookup_batch","scope":"search","read_only":true,"destructive":false,"notes":"Batch direct lookup for known LinkedIn URLs/usernames or Super Carl person ids. Use this for uploaded lists, profile-loading follow-ups, relationship_detail reads, or exact identity rows rather than broad discovery."},{"name":"company_search","scope":"search","read_only":true,"destructive":false},{"name":"company_search_batch","scope":"search","read_only":true,"destructive":false,"notes":"Batch named-company resolution for spreadsheets, rosters, exclusions, and long/messy employer lists. Inspect each company_resolution.status and bind only resolved/set companies into people_search."},{"name":"jobs_search","scope":"search","read_only":true,"destructive":false},{"name":"posts_search","scope":"search","read_only":true,"destructive":false},{"name":"communication_read","scope":"communications","read_only":true,"destructive":false,"modes":["precheck","history","status"],"notes":"Reads cached channel readiness, cached communication history, or queued/send delivery status without drafting, sending, cancelling, refreshing LinkedIn history, or enriching email."},{"name":"project_read","scope":"communications","read_only":true,"destructive":false,"modes":["list","status","targets","metrics","send_readiness","google_sheet_sync_status"],"notes":"Reads projects, shortlist targets, outreach metrics, send readiness, and Google Sheet sync status. Use project_action for project mutations and Google Sheet create/update/refresh actions."},{"name":"social_proximity_research","scope":"search","read_only":false,"destructive":false,"notes":"Explicitly starts LinkedIn mutual research for one target and returns social proximity relationship detail plus warm-intro paths. Completed research is reused for 30 days by default; callers should report that existing researched mutuals were reused instead of describing a fresh research run. If the target profile is skeletal but has a LinkedIn URL and research is not already recent, this can also queue browser-orchestrator profile loading and reports research.target_profile_load. Cached relationship detail is read through people_search / people_lookup_batch with relationship_detail."},{"name":"social_proximity_status","scope":"search","read_only":true,"destructive":false,"notes":"Reads cached social-proximity and LinkedIn mutual-research status for one target without starting, continuing, resetting, or refreshing browser research. Use this for polling and for recent researched mutuals."},{"name":"watch_signals_read","scope":"communications","read_only":true,"destructive":false,"modes":["role_packs","status","hits","evidence","delivery_status"],"notes":"Reads recurring Scan My Network watch configuration, hits, evidence, and delivery status without creating, updating, running, pausing, or promoting a watch."},{"name":"send_communication","scope":"communications","read_only":false,"destructive":true,"modes":["precheck","history","draft","send","status","cancel"],"notes":"Polymorphic: mode is required. mode=\"precheck\" is read-only channel-readiness check; mode=\"history\" reads previous visible communication history for a target; mode=\"draft\" stores expanded no-delivery outreach copy for review; mode=\"send\" is the destructive outbound send (with idempotency dedupe and explicit user confirmation); mode=\"status\" polls a prior send; mode=\"cancel\" cancels queued LinkedIn sends before dispatch."},{"name":"project_action","scope":"communications","read_only":false,"destructive":false,"modes":["list","status","targets","recipient_emails","metrics","send_readiness","add_targets","remove_targets","retry_failed_linkedin_sends","rename","update_templates","generate_templates","generate_messages","update_message","google_sheet_sync","activate"],"notes":"Polymorphic project API dispatcher. Read modes list projects, include the current_session_project when agent_session_id is bound, fetch one project, list active included targets, resolve recipient emails, report outreach response metrics, and summarize send readiness. Mutating modes add/remove shortlist targets, rename the project, update saved outreach/referral/engagement templates, generate saved templates and personalized target messages, save exact target drafts, manage the project Google Sheet output under mode=\"google_sheet_sync\", activate reviewed delivery, or retry non-limit LinkedIn failures. Mutating modes require user_confirmed=true in MCP."},{"name":"contacts_export","scope":"search (legacy MCP); contacts-read for newly scoped API clients","read_only":false,"destructive":false,"modes":["estimate","start","status","latest"],"notes":"Estimates, starts, and checks the account-level all-contacts Google Sheet export. The export now separates confirmed contacts, likely matches, unresolved owned contacts, observed X/Instagram follower rows, enriched public profile fields, and metadata."},{"name":"contacts_reconcile","scope":"search or contacts-read for schema/start/preview/status/review reads; contacts-write for apply/finalize/review mutations","read_only":false,"destructive":false,"modes":["schema","start_run","preview_batch","apply_batch","status","finalize","list_review","get_candidates","confirm_candidate","correct_resolution","bulk_correct_resolutions","bulk_confirm_candidates","bulk_reject_candidates","bulk_mark_needs_review","bulk_ignore_entities","bulk_restore_entities","mark_needs_review","reject_candidate","ignore_entity","restore_entity"],"notes":"API-backed contact reconciliation workflow for agents and CLI clients. Normalize spreadsheet rows, preview batches up to 100 rows, apply reviewed batches, keep likely matches as candidates, hold distinct LinkedIn/name identities that collapse onto one profile, page review rows with response_verbosity compact/minimal/detailed, correct wrong/duplicate profile links by detach or exact-identity reassignment, and perform single-row or bulk confirm/reject/needs-review/ignore/restore operations. Existing MCP connectors with search can run schema/start/preview/status/review reads; mutating modes require contacts-write and user_confirmed=true."},{"name":"enrich_contacts","scope":"search","read_only":false,"destructive":false,"modes":["estimate","run"],"notes":"Estimates and, after explicit confirmation, releases verified work emails for a short, already-vetted list. Cached emails are free; genuinely missing addresses use the credit-metered provider path."},{"name":"x_instagram_sync","scope":"integrations","read_only":false,"destructive":false,"modes":["status","refresh"],"notes":"Reads X/Instagram source-sync state or queues an explicit, user-confirmed refresh. Reconnect the browser session instead of retrying when the result reports that reconnect is required."},{"name":"watch_signals","scope":"search","read_only":false,"destructive":false,"modes":["create","role_packs","update","status","hits","evidence","delivery_status","run_now","pause","resume","snooze_hit","dismiss_hit","promote_hit"],"notes":"Creates and manages hosted Scan My Network watches anchored to a Super Carl project. Use it when the user wants ongoing monitoring, webhook/project-feed updates, evidence inspection, or promotion of qualified hits into outreach workflows."},{"name":"query_search_result","scope":"search","read_only":true,"destructive":false,"notes":"Filters, sorts, deduplicates, paginates, compares, or projects rows already returned by a typed search without rerunning retrieval or loading the full snapshot JSON into model context. Persisted external result refs currently replay at most 25 snapshot rows and do not query unseen rows from a larger result set."},{"name":"get_product_help","scope":"product_knowledge","read_only":true,"destructive":false,"notes":"Topic catalog + per-user live state (LinkedIn / Gmail / Calendar / Slack / X / Instagram / notification toggles / timezone / plan tier / availability). Pass topic=\"index\" to discover topic ids."},{"name":"super_carl_action","scope":"product_knowledge","read_only":false,"destructive":false,"action_ids":["set_timezone","set_notification_preferences","claim_bonus_credits","report_feedback"],"notes":"Dispatcher for safe per-user actions. set_timezone and set_notification_preferences require user_confirmed=true; claim_bonus_credits and report_feedback do not. claim_bonus_credits is a one-time MCP recruiting launch bonus and returns credit counts before/after the grant."}],"rest_passthrough":[{"method":"POST","path":"/api/v1/search/people/preview","description":"Preview search for iterative refinement."},{"method":"POST","path":"/api/v1/companies/search/preview","description":"Preview company search for company-first workflows."},{"method":"POST","path":"/api/v1/search/people","description":"Run a full search or enrich results."},{"method":"POST","path":"/api/v1/search/jobs/preview","description":"Natural-language job search scored against the viewer social-graph overlay."},{"method":"POST","path":"/api/v1/search/jobs/with-people","description":"The 'map a job to a path in' surface — jobs grouped by company with inline network people at each."},{"method":"POST","path":"/api/v1/search/posts/preview","description":"Direct post/activity search over posts, likes, comments, reposts, target companies/people, dates, and engagement counts."},{"method":"POST","path":"/api/v1/search/posts/with-people","description":"Post/activity search with a deduped people set derived from matching actors/authors and a people_search binding for full profile pivots."},{"method":"POST","path":"/api/v1/relationships/social-proximity/research","description":"Explicitly start LinkedIn mutual research for a target when not recently researched and return current warm-intro paths."},{"method":"GET","path":"/api/v1/relationships/social-proximity/research/status","description":"Read cached social-proximity and mutual-research status without starting or refreshing browser research."},{"method":"POST","path":"/api/v1/communications/capabilities","description":"Check channel readiness for outbound communication."},{"method":"POST","path":"/api/v1/communications","description":"Draft, send, or dry-run outbound communication."},{"method":"POST","path":"/api/v1/communications/history","description":"Read previous visible communication history for a target."},{"method":"GET","path":"/api/v1/communications/:communicationId","description":"Fetch communication status, task metadata, and artifacts."},{"method":"GET","path":"/api/v1/projects","description":"List active projects for the acting user; current_project_id surfaces a session-bound project even when filtered out."},{"method":"GET","path":"/api/v1/projects/:projectId","description":"Fetch one project with optional targets/search results."},{"method":"GET","path":"/api/v1/projects/:projectId/targets","description":"List active included targets for a project."},{"method":"POST","path":"/api/v1/projects/:projectId/targets","description":"Add people to a project shortlist."},{"method":"DELETE","path":"/api/v1/projects/:projectId/targets","description":"Remove people from a project shortlist."},{"method":"GET","path":"/api/v1/projects/:projectId/metrics","description":"Fetch outreach response rates and status counts for a project."},{"method":"PATCH","path":"/api/v1/projects/:projectId","description":"Rename or update basic project fields."},{"method":"PUT","path":"/api/v1/projects/:projectId/templates","description":"Update saved project outreach/referral/engagement templates."},{"method":"POST","path":"/api/v1/projects/:projectId/templates/generate","description":"Generate saved project templates from project context."},{"method":"POST","path":"/api/v1/projects/:projectId/messages/generate","description":"Generate personalized messages against saved project templates."},{"method":"GET","path":"/api/v1/network/summary","description":"Confirm the vantage-point user's social-graph ingestion status (LinkedIn / Gmail / X / Instagram / Super Carl connections) before relying on graph-aware filters."}],"legacy_schema_endpoint":{"path":"/public/docs/mcp","note":"Serves the MCP tool-schema JSON for inspection and tooling. This is NOT the connector URL — point your MCP client at /mcp instead."},"notes":["`people_search` first pass: use `query` with `preview:true`; add `filter_updates` only for user-confirmed hard canonical patches, not semantic guesses like inferred role families, AI keywords, or qualitative phrases such as \"small product teams\". Review/deep-dive: copy the entire `recommended_next_call.args.filters` or `search_metadata.filters.advanced` object into `filters` with `preview:false`; do not reconstruct a partial subset. Full `query`+`filters` calls are blocked; preview `query`+`filters` calls are tolerated by treating `filters` as `filter_updates`.","`people_search` AdvancedFilters supports has_current_experience:false for no-current-role / no-new-role-yet refinements; coverage depends on profile experience-date freshness.","`company_search` with preview:true returns a company search_id that can be passed into filters.companies.include_company_search_id or exclude_company_search_id for people searches.","`people_search` and `people_lookup_batch` accept relationship_detail:\"summary\" or \"intro_paths\" for social proximity, mutuals, and warm-intro paths. Read calls never start LinkedIn mutual research; use social_proximity_research for explicit fresh mutual research.","MCP tools map onto the REST endpoints via `preview` / `with_people` flags; there is exactly one implementation of each operation.","`posts_search` is the direct activity/post surface for \"posting about\", \"liked/commented on\", \"reposted\", target-company engagement, date windows, and reaction/comment thresholds. For literal mention requests use `filters.posts.mentioned`; for soft topic/signal intent use `filters.posts.additional_context_keywords_core/supporting` with `keyword_match_mode:\"soft\"`. It returns matching rows plus `people_search_binding`; execute that binding when you need full profile filters, relationship detail, or deduped people review.","Use `communication_read` for cached precheck/history/status reads. Use `send_communication` when fresh provider history or recipient resolution is required, or for draft/send/cancel writes; mode=\"send\" is destructive, idempotency-deduped, and requires user_confirmed=true unless dry_run=true.","Use `project_read` for project list/status/targets/metrics/send-readiness and Google Sheet sync status. Use `project_action` for mutations, including add/remove targets, drafting, activation, and Google Sheet create/update/refresh under mode=\"google_sheet_sync\".","For multi-step MCP workflows, carry stable ids forward: pass the returned agent_session_id on every related search/project/sheet/watch/communication call, and pass returned project_id / current_session_project_id into later project_action calls when operating on a specific project.","`super_carl_action` with action_id=\"claim_bonus_credits\" grants the one-time MCP recruiting launch bonus when a user asks for free/bonus Super Carl credits; return the before/after credit counts and tell repeat claimers it is one-time. `super_carl_action` with action_id=\"report_feedback\" is the feedback loop for this MCP itself — call it when you hit API friction, unexpected response shapes, bugs, or explicit user frustration / feature requests. It writes into the shared feedback table the Super Carl team triages and does NOT require user_confirmed.","`get_product_help` covers any \"where do I…\" / \"how do I…\" question about Super Carl itself; it returns the topic markdown plus the current user's live state for that area (integration sessions, sync status, notification toggles, timezone, plan tier, availability). Pass topic=\"index\" first if you don't know which topic fits."],"usage_rubric":{"flag_model":"Use `people_search` and `company_search` with `preview: true` (default) to count matches and iterate on filters cheaply. Set `preview: false` ONCE the filter feels right to fetch enriched rows. `jobs_search` returns usable job rows by default; set `with_people: true` when the user wants to know which jobs they have a path into. `posts_search` returns post/activity rows by default; set `with_people: true` when the user asks who posted/liked/commented/reposted, then execute `people_search_binding` for full profile review.","typical_flow":["1. User asks a natural-language question ('who do I know that ...')","2. Call people_search with { query, preview: true }. If you must pin hard user-confirmed constraints on that first pass, add canonical filter_updates; otherwise let the natural-language translator map roles, skills, and company descriptors. Look at total_count.","3. If total_count is 0, say so and suggest relaxing filters.","4. If total_count is too large (>100 or so), narrow with filter_updates or copy search_metadata.filters.advanced into filters and call people_search again with preview: true.","5. Once total_count is reasonable (~1-100), call people_search with { filters, preview: false } using the copied entire canonical filters object, not top-level query, so you don't re-parse the description or drop translated constraints. Render the returned rows."],"direct_lookup":"For a single known person, pass people_search { linkedin_profile_url } or { linkedin_username } — direct lookup ignores `preview` and filters.","jobs_flow":"jobs_search returns usable rows (title, company, network block) by default. Set with_people: true when the user wants the 'which jobs do I have a path into' shape — results group by company with 1st/2nd-degree people inlined at each.","posts_flow":"posts_search returns matching post/activity rows by default. Use filters.posts.mentioned for hard/literal \"posts mentioning X\"; use filters.posts.additional_context_keywords_core/supporting with keyword_match_mode:\"soft\" for broader topic/signal searches such as \"who is hiring\". Other fields: action_types, min_reactions/min_comments/min_engagement, published_within_days, target_companies/target_people/target_urls. Set with_people:true for a quick deduped people set, or execute the returned people_search_binding and add network/title/location/company filters structurally.","communications_flow":"Use communication_read for cached precheck/history/status reads. Call send_communication mode=\"history\" only when fresh provider history or recipient resolution is required. Use send_communication mode=\"draft\" when the user should review exact copy first; Super Carl stores the draft on the MCP session assignment target and expands [JoinLink]/[SchedulingLink] so the agent sees the final links. Use mode=\"send\" only when the user has approved delivery; Gmail requires subject.","project_flow":"Use project_read mode=\"list\" or agent_session.status to find the active project id; when agent_session_id is bound, list returns current_session_project/current_session_project_id even if the generic list is empty. Copy returned agent_session_id/project_id values into subsequent calls instead of reusing names or titles. Use project_read mode=\"targets\" to show active included targets, mode=\"metrics\" to report outreach response rates, mode=\"send_readiness\" to summarize review state, and mode=\"google_sheet_sync_status\" for output-sheet status. Use project_action mode=\"google_sheet_sync\" for sheet create/update/refresh actions. Use project_action mode=\"update_message\" or mode=\"generate_messages\" to draft target messages and mode=\"activate\" after explicit send approval. When the user asks you to draft outreach/messages/best asks for selected people, save the useful project state too: add_targets for the selected people, then update_message review_action=\"save\" for exact reviewed-later drafts. A target with outreach_status=\"queued_send\" was already queued for immediate single-target delivery by the user (app \"Send now\"); treat it as in flight like \"sending\" — do not re-draft, re-send, or include it in a bulk activate. Use agent_session mode=\"list\" to list/resume sessions and mode=\"switch_project\" with agent_session_id + project_id when the user wants this MCP session to work against a specific existing project."},"curl_examples":"# Discover the authorization server + JWKS\ncurl -s https://api.supercarl.ai/.well-known/oauth-protected-resource\ncurl -s https://api.supercarl.ai/.well-known/oauth-authorization-server\n\n# Dynamic Client Registration (RFC 7591)\ncurl -X POST https://api.supercarl.ai/oauth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"client_name\": \"My MCP Client\",\n    \"redirect_uris\": [\"https://my-client.example/callback\"],\n    \"token_endpoint_auth_method\": \"none\"\n  }'\n\n# Smoke-test /mcp with an API key (no OAuth required for scripts)\ncurl -X POST https://api.supercarl.ai/mcp \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'","privacy_policy":"https://supercarl.ai/privacy","terms_of_service":"https://supercarl.ai/terms","support_contact":"support@supercarl.ai","directory_status":"preparing_submission"},"credit_enforcement":{"overview":"Super Carl charges credits for billable actions. Every authenticated response on enforced routes carries X-Carl-Credits-* headers; when the account owner hits the ceiling, mutating endpoints return HTTP 402 with a credits_exhausted body and MCP tool calls return a structured tool error.","docs_url":"https://supercarl.ai/docs#credits","policy":{"window_days":30,"window_semantics":"The window begins at the timestamp of your first billable action inside the current window and closes 30 days later. When the ledger has no events inside the window, window_start and reset_at are both null and no reset timestamp is emitted until the next billable action.","pool_scope":"Credits are pooled per account owner. Team seats and delegated calls draw from the owner's pool.","tiers":[{"tier":"free","credit_cap":5,"window_days":30},{"tier":"starter","credit_cap":50,"window_days":30,"price_usd":8,"estimated_detailed_searches":500},{"tier":"starter_annual","credit_cap":50,"window_days":30,"price_usd":6.4,"estimated_detailed_searches":500},{"tier":"pro","credit_cap":1000,"window_days":30},{"tier":"annual","credit_cap":1000,"window_days":30},{"tier":"team","credit_cap":1000,"window_days":30}],"admin_bypass":"Admin users bypass the block entirely — headers still emit, but 402 responses are never returned for them."},"debit_actions":[{"area":"People search (full)","action_type":"search","action_subtype":"results","sources":["POST /api/v1/search/people","POST /search (in-app)"]},{"area":"People search preview","action_type":"search","action_subtype":"preview","sources":["POST /api/v1/search/people/preview","peopleSearchPreviewTool (agents / MCP)"]},{"area":"Company search preview","action_type":"search","action_subtype":"preview","sources":["POST /api/v1/companies/search/preview","companySearchPreviewTool (agents / MCP)"]},{"area":"Job search (preview / with-people)","action_type":"search","action_subtype":"preview","sources":["POST /api/v1/search/jobs/preview","POST /api/v1/search/jobs/with-people"]},{"area":"Post/activity search (preview / with-people)","action_type":"search","action_subtype":"preview","sources":["POST /api/v1/search/posts/preview","POST /api/v1/search/posts/with-people"]},{"area":"Campaign export","action_type":"search","action_subtype":"export","sources":["campaignGenerationRoutes (outreach campaign data-set export)"]},{"area":"Outreach delivery","action_type":"outreach","action_subtype":"on_platform | off_platform","sources":["Assignment worker post-send (LinkedIn + Super Carl direct message)"]},{"area":"Voice sessions","action_type":"voice_minutes","action_subtype":null,"sources":["Recorded when a voice session ends (actual duration)"]},{"area":"LLM token usage","action_type":"tokens","action_subtype":"openai","sources":["tokenUsageService (every OpenAI call)"]}],"response_headers":{"applies_to":"Every authenticated response on routes wired to the enforceCreditCeiling pre-handler (full public search + enrich + campaign-export surface). Headers emit on successful responses and on the 402 exhaustion response.","headers":[{"name":"X-Carl-Credits-Tier","type":"string","example":"free","omitted_when":null,"description":"Account-owner tier slug. One of free, starter, starter_annual, pro, annual, team."},{"name":"X-Carl-Credits-Limit","type":"integer","example":"5","omitted_when":"Tier is unlimited (limit === null).","description":"Credit cap for the current window."},{"name":"X-Carl-Credits-Used","type":"integer","example":"4","omitted_when":null,"description":"Credits consumed in the current window. 0 when the window is empty."},{"name":"X-Carl-Credits-Remaining","type":"integer","example":"1","omitted_when":"Tier is unlimited (remaining === null).","description":"limit minus used, clamped at 0."},{"name":"X-Carl-Credits-Reset-At","type":"string (RFC 3339)","example":"2026-05-14T17:22:03.000Z","omitted_when":"Window is empty (no usage yet — window_start is null).","description":"When the current window closes."},{"name":"X-Carl-Credits-Window-Days","type":"integer","example":"30","omitted_when":null,"description":"Window length in days. Always present."}]},"exhaustion_response":{"http_status":402,"body_shape":"CreditsExhaustedError","example":{"error":"credits_exhausted","message":"You've used all 5 credits in your current credit period.","tier":"free","limit":5,"used":5,"remaining":0,"reset_at":"2026-05-14T17:22:03.000Z","upgrade_url":"https://supercarl.ai/upgrade","docs_url":"https://supercarl.ai/docs#credits"},"client_detection_field":"error","client_detection_value":"credits_exhausted","notes":["Key off the `error` field for client branching on HTTP responses.","The parallel MCP structured error uses `error_code` rather than `error` — see mcp_error below.","Clients should open upgrade_url to let the user upgrade."]},"mcp_error":{"overview":"MCP has no HTTP-header surface at the tool layer, so credit metadata travels inside tool responses. Successful tool calls carry structuredContent.credits; over-limit tool calls return a tool error.","success_annotation":{"shape":"CreditsAnnotation","example":{"structuredContent":{"credits":{"tier":"free","limit":5,"used":4,"remaining":1,"reset_at":"2026-05-14T17:22:03.000Z"}}}},"over_limit_response":{"shape":"McpCreditsExhaustedError","text_template":"Your Super Carl credits are used up. You've used {used}/{limit} credits in your current credit period. Share {upgrade_url}; free users can upgrade to Starter for 50 credits per month. Credits refresh on {reset_date} (in ~{days_left} days).","example":{"isError":true,"content":[{"type":"text","text":"Your Super Carl credits are used up. You've used 5/5 credits in your current credit period — credits refresh on 2026-05-14 (in ~21 days).\n\nAction required: tell the user they are out of Super Carl credits and cannot run more searches, outreach, or enrichment until they upgrade or wait for the reset. Share this upgrade link with them: https://supercarl.ai/upgrade Upgrading to Starter gives them 50 credits per month.\n\nUpgrade: https://supercarl.ai/upgrade\nDocs: https://supercarl.ai/docs#credits"}],"structuredContent":{"error_code":"credits_exhausted","tier":"free","limit":5,"used":5,"remaining":0,"reset_at":"2026-05-14T17:22:03.000Z","upgrade_url":"https://supercarl.ai/upgrade"}},"client_detection_field":"structuredContent.error_code","client_detection_value":"credits_exhausted"}},"status_endpoints":[{"endpoint":"GET /api/v1/credits/status","auth":"X-API-Key","description":"API-key authenticated rolling-window status. Mirrors the X-Carl-Credits-* headers. Safe to poll.","response_shape":"CreditStatusResponse"},{"endpoint":"GET /users/me/credits/status","auth":"session JWT","description":"Session-authenticated variant used by the in-app out-of-credits modal and balance banner. Identical response shape; Cache-Control: no-store so retries after upgrade see fresh values.","response_shape":"CreditStatusResponse"}],"upgrade_url":"https://supercarl.ai/upgrade"},"data_dictionary":{"notes":["Fields marked optional may be omitted. Unknown fields can appear as the schema evolves.","Search responses include the internal person object plus normalized top-level fields when available.","Use description for natural-language searches; query is a legacy alias. The text is auto-translated into AdvancedFilters by default. Use filters/search_metadata to supply explicit structured constraints.","Direct LinkedIn lookup accepts linkedin_username (vanity), linkedin_profile_url, or linkedin_url. Use the profile URL path when your upstream workflow already has full LinkedIn URLs.","Search rows with evidence_format=json already include declarative evidence for alignment to requested filters. Direct LinkedIn lookup and batch direct lookup are for loading the latest available Super Carl profile data for known LinkedIn identities, not for independent certification of identity or employment; do not describe lookup as verifying or confirming employment.","If a row lacks a LinkedIn identity or lookup cannot resolve, do not recover with broad keyword-only people search. Re-resolve the employer with company search, then run people search with company_search_id binding plus companies.include_current_only=true and job_titles.current_only=true; ask for disambiguation when the company cannot be resolved confidently.","If you send keywords, they are merged into filters.additional_context. Prefer filters.additional_context (or additional_context_keywords) instead.","Resolved filters (including description translation) are echoed back in search_metadata.filters.advanced.","Set include_evidence_text=true on people search/preview/enrich to inline aggregated profile evidence text, or include_evidence_json=true for structured evidence. evidence_format=text|json|both is shorthand; evidence_format=reasons opts into LLM-built match_reasons on full people searches. For large preview-row paging, use preview + skip_match_reasons=true / evidence_format=none. evidence_text_mode=base returns compact embedding-ready text; evidence_text_mode=full adds company and recent-post context.","People-search responses can include requester-relative social proximity summary fields on each Person row. Detailed evidence and connector-path payloads are documented in the Social proximity section and authenticated user models below.","When a search returns zero results due to insufficient persona profile context, search_metadata.no_results_reason and no_results_reason_code can explain why.","Company search previews return search_id values that can be used in filters.companies.include_company_search_id/exclude_company_search_id for people searches. If a company search resolves to more than 10k companies, the top-ranked 10k companies are applied and surfaced as capped in search_metadata.company_search_filters.","Company search responses include company_resolution with status=resolved|ambiguous|unresolved|set, a deduplicated candidates[] (collapsed by linkedin_slug → domain → normalized name), candidate_count (deduped), raw_candidate_count (pre-dedupe), and a brand_name_match boolean. Proceed to people_search when status=resolved. Treat status=ambiguous or unresolved as needing a domain/LinkedIn URL or user selection before binding a people search; status=unresolved with reason=no_brand_name_match means the resolver returned hits but none overlapped the queried brand, which is the right time to ask for the canonical URL. For descriptor/set searches, status=set means the search_id is intentionally a company set.","Company search preview supports result_mode=preview|detailed and a resolve_only=true flag. resolve_only drops the companies[] array entirely and returns just company_resolution + search_id — use it for cheap named-company disambiguation passes when iterating over a brand list. Detailed mode expands each company row with canonical URLs, funding/stage metadata, and optional evidence_text built from stored company records and recent posts.","Public docs also publish static corpus and refresh-cadence metadata in data_scale so agent integrations can plan around dataset shape without hitting expensive live stats.","Use GET /api/v1/credits to inspect the shared account credit pool, current-key usage counters, live search rate card, and operation-level billing semantics.","Use GET /api/v1/credits/status for a lightweight rolling-window status (tier, limit, used, remaining, reset_at). Every authenticated response also carries X-Carl-Credits-* headers with the same values. See credit_enforcement in this schema for the full policy, the 402 credits_exhausted body, and the MCP over-limit tool error.","Communications are exposed as non-assignment communication records with normalized status, events, webhook delivery metadata, and artifact links.","Projects are the public API name for assignment workspaces. Project endpoints expose the same target list, response metrics, template update, template generation, and personalized-message generation operations used by product flows.","Company search numeric ranges accept either numbers or shorthand strings (examples: 500K, 25M, 1.2B).","AdvancedFilters fields below are generated from the backend canonical schema used by preview/search tools to avoid drift."],"models":[{"name":"CreditsResponse","description":"Response payload from GET /api/v1/credits.","fields":[{"name":"success","type":"boolean","required":true,"description":"Whether the request succeeded."},{"name":"owner_user_id","type":"uuid","required":true,"description":"Billing account owner id for the shared credit pool."},{"name":"credit_pool_scope","type":"string","required":true,"description":"Scope of the shared credit pool. Current value: account_owner."},{"name":"range","type":"object","required":true,"description":"Resolved reporting window.","shape":{"key":"string","start":"string|null","end":"string|null"}},{"name":"current_api_key","type":"CurrentApiKey","required":true,"description":"Metadata for the authenticated API key."},{"name":"current_key_usage","type":"CurrentApiKeyUsage","required":true,"description":"Recorded credit-event counters for the authenticated API key within the selected range."},{"name":"account_credit_pool.totals","type":"CreditPoolTotals","required":true,"description":"Shared account-level usage totals across app and API activity."},{"name":"account_credit_pool.breakdown","type":"CreditUsageBreakdownEntry[]","required":true,"description":"Account-level usage grouped by action_type + action_subtype."},{"name":"rate_card.conversion_rules","type":"CreditConversionRule[]","required":true,"description":"Active conversion rules relevant to the public search API."},{"name":"rate_card.cost_rates","type":"CreditCostRate[]","required":true,"description":"Active cost rates relevant to the public search API."},{"name":"billing_semantics","type":"CreditBillingSemanticsEntry[]","required":true,"description":"Operation-level billing behavior for the public API surface."},{"name":"notes","type":"string[]","required":false,"description":"Additional billing notes for integrators."}]},{"name":"CreditStatusResponse","description":"Response from GET /api/v1/credits/status and GET /users/me/credits/status. Mirrors the X-Carl-Credits-* response headers.","fields":[{"name":"tier","type":"string","required":true,"description":"Account-owner tier slug. One of free, starter, starter_annual, pro, annual, team."},{"name":"limit","type":"number|null","required":true,"description":"Credit cap for the current window. null when the tier is unlimited."},{"name":"used","type":"number","required":true,"description":"Credits consumed in the current window. 0 when the window is empty."},{"name":"remaining","type":"number|null","required":true,"description":"limit - used, clamped at 0. null when the tier is unlimited."},{"name":"window_start","type":"string|null","required":true,"description":"RFC 3339 timestamp of the first billable action in the current window. null when the window is empty."},{"name":"window_days","type":"number","required":true,"description":"Window length in days. Currently 30 for every tier."},{"name":"reset_at","type":"string|null","required":true,"description":"RFC 3339 timestamp when the current window closes. null when the window is empty."},{"name":"as_of","type":"string","required":true,"description":"RFC 3339 timestamp the status was computed at."}]},{"name":"CreditsExhaustedError","description":"HTTP 402 response body returned when the account owner is at or over the credit ceiling and CREDIT_ENFORCEMENT_ENABLED is on.","fields":[{"name":"error","type":"string","required":true,"description":"Stable machine-readable code. Always \"credits_exhausted\" for this response. Key off this for client branching."},{"name":"message","type":"string","required":true,"description":"Human-readable summary including the cap and window length."},{"name":"tier","type":"string","required":true,"description":"Account-owner tier slug at the time of the block."},{"name":"limit","type":"number","required":true,"description":"Credit cap for the current window."},{"name":"used","type":"number","required":true,"description":"Credits consumed in the current window."},{"name":"remaining","type":"number","required":true,"description":"Always 0 on this response."},{"name":"reset_at","type":"string|null","required":false,"description":"RFC 3339 window-close timestamp. May be null in edge cases where usage has been cleared."},{"name":"upgrade_url","type":"string","required":true,"description":"Open this to let the user upgrade. Currently https://supercarl.ai/upgrade."},{"name":"docs_url","type":"string","required":true,"description":"Deep-link back to the credits docs section."}]},{"name":"CreditsAnnotation","description":"Block appended to structuredContent on every successful MCP tool response so clients can render balance hints.","fields":[{"name":"tier","type":"string","required":true,"description":"Account-owner tier slug."},{"name":"limit","type":"number|null","required":true,"description":"Credit cap for the current window. null when unlimited."},{"name":"used","type":"number","required":true,"description":"Credits consumed in the current window."},{"name":"remaining","type":"number|null","required":true,"description":"limit - used, clamped at 0. null when unlimited."},{"name":"reset_at","type":"string|null","required":true,"description":"RFC 3339 window-close timestamp. null when the window is empty."}]},{"name":"McpCreditsExhaustedError","description":"MCP tool error returned when the account owner is at or over the credit ceiling. MCP has no HTTP-header surface at the tool layer, so credit metadata travels inside the tool response.","fields":[{"name":"isError","type":"boolean","required":true,"description":"Always true."},{"name":"content","type":"object[]","required":true,"description":"Single-element array with a text block. content[0].text includes used/limit, window length, upgrade URL, and a refresh-date phrase."},{"name":"structuredContent.error_code","type":"string","required":true,"description":"\"credits_exhausted\". Key off this for client branching (note: the HTTP 402 body uses `error` instead)."},{"name":"structuredContent.tier","type":"string","required":true,"description":"Account-owner tier slug."},{"name":"structuredContent.limit","type":"number","required":true,"description":"Credit cap for the current window."},{"name":"structuredContent.used","type":"number","required":true,"description":"Credits consumed in the current window."},{"name":"structuredContent.remaining","type":"number","required":true,"description":"Always 0."},{"name":"structuredContent.reset_at","type":"string|null","required":false,"description":"RFC 3339 window-close timestamp."},{"name":"structuredContent.upgrade_url","type":"string","required":true,"description":"Open in a browser to upgrade."}]},{"name":"CurrentApiKey","description":"Authenticated API key metadata returned by GET /api/v1/credits.","fields":[{"name":"id","type":"uuid","required":true,"description":"API key id."},{"name":"name","type":"string|null","required":false,"description":"Display name for the API key."},{"name":"key_prefix","type":"string|null","required":false,"description":"Non-secret API key prefix."},{"name":"scopes","type":"string[]","required":true,"description":"Granted scopes on the key."},{"name":"status","type":"string|null","required":false,"description":"Current API key status."},{"name":"last_used_at","type":"string|null","required":false,"description":"Last-used timestamp after the current request is recorded."},{"name":"created_at","type":"string|null","required":false,"description":"Creation timestamp."}]},{"name":"CurrentApiKeyUsage","description":"Recorded search credit-event counters for one API key.","fields":[{"name":"credits_used","type":"number","required":true,"description":"Snapshot credits consumed by recorded credit events for this key."},{"name":"units","type":"number","required":true,"description":"Recorded units consumed by this key."},{"name":"preview_searches","type":"number","required":true,"description":"Count of preview search credit events."},{"name":"full_searches","type":"number","required":true,"description":"Count of full-search credit events."},{"name":"linkedin_lookups","type":"number","required":true,"description":"Count of LinkedIn lookup credit events."}]},{"name":"CreditPoolTotals","description":"Account-level totals for the shared credit pool.","fields":[{"name":"units","type":"number","required":true,"description":"Total recorded units in the selected range."},{"name":"snapshot_credits","type":"number","required":true,"description":"Credits charged at the time each event was recorded."},{"name":"current_credits","type":"number","required":true,"description":"Credits recomputed against the currently active conversion rules."},{"name":"snapshot_cost","type":"number","required":true,"description":"Underlying cost snapshot in billing currency units."}]},{"name":"CreditUsageBreakdownEntry","description":"Breakdown row for account_credit_pool.breakdown.","fields":[{"name":"action_type","type":"string|null","required":false,"description":"Primary credit action type."},{"name":"action_subtype","type":"string|null","required":false,"description":"Credit action subtype."},{"name":"units","type":"number","required":true,"description":"Recorded units for this action bucket."},{"name":"snapshot_credits","type":"number","required":true,"description":"Credits recorded at event time."},{"name":"current_credits","type":"number","required":true,"description":"Credits recomputed against the active rule set."},{"name":"snapshot_cost","type":"number","required":true,"description":"Underlying cost snapshot in billing currency units."},{"name":"applied_rule","type":"CreditConversionRule|null","required":false,"description":"Active conversion rule currently applied to this action bucket."}]},{"name":"CreditConversionRule","description":"Active conversion rule relevant to the public API.","fields":[{"name":"action_type","type":"string|null","required":false,"description":"Credit action type."},{"name":"action_subtype","type":"string|null","required":false,"description":"Credit action subtype."},{"name":"units_per_credit","type":"number|null","required":false,"description":"How many units correspond to one credit."},{"name":"credits_per_unit","type":"number|null","required":false,"description":"How many credits are charged per unit."},{"name":"effective_at","type":"string|null","required":false,"description":"Rule effective timestamp."},{"name":"expires_at","type":"string|null","required":false,"description":"Rule expiration timestamp when set."},{"name":"description","type":"string|null","required":false,"description":"Human-readable rule description."}]},{"name":"CreditCostRate","description":"Active internal cost rate relevant to the public API.","fields":[{"name":"action_type","type":"string|null","required":false,"description":"Credit action type."},{"name":"action_subtype","type":"string|null","required":false,"description":"Credit action subtype."},{"name":"model","type":"string|null","required":false,"description":"Associated model or null for generic search operations."},{"name":"cost_per_unit","type":"number|null","required":false,"description":"Underlying cost per unit in the given currency."},{"name":"currency","type":"string|null","required":false,"description":"Billing currency code."},{"name":"effective_at","type":"string|null","required":false,"description":"Rate effective timestamp."},{"name":"expires_at","type":"string|null","required":false,"description":"Rate expiration timestamp when set."},{"name":"description","type":"string|null","required":false,"description":"Human-readable rate description."}]},{"name":"CreditBillingSemanticsEntry","description":"Billing behavior for one public API operation.","fields":[{"name":"operation","type":"string","required":true,"description":"Stable operation identifier."},{"name":"endpoint","type":"string","required":true,"description":"HTTP method + path for the operation."},{"name":"scopes","type":"string[]","required":true,"description":"Required API key scopes for the operation."},{"name":"billing_mode","type":"credit_event|updates_existing_search_event|not_recorded_separately","required":true,"description":"How the operation interacts with credit accounting."},{"name":"action_type","type":"string|null","required":false,"description":"Credit action type when a credit event is recorded."},{"name":"action_subtype","type":"string|null","required":false,"description":"Credit action subtype when a credit event is recorded."},{"name":"note","type":"string","required":true,"description":"Practical explanation of the billing behavior."}]},{"name":"CommunicationChannelCapability","description":"Per-channel sendability record returned by POST /api/v1/communications/capabilities.","fields":[{"name":"channel","type":"string","required":true,"description":"Channel identifier."},{"name":"can_send","type":"boolean","required":true,"description":"Whether the channel is currently sendable."},{"name":"reason_code","type":"string|null","required":false,"description":"Machine-readable readiness reason."},{"name":"reason","type":"string|null","required":false,"description":"Human-readable readiness explanation."},{"name":"action_required","type":"string|null","required":false,"description":"Follow-up action needed before sending, when any."},{"name":"fallback_channels","type":"string[]","required":false,"description":"Other channels that are currently sendable."}]},{"name":"CommunicationEvent","description":"Append-only event emitted for a communication lifecycle.","fields":[{"name":"id","type":"uuid","required":true,"description":"Event id."},{"name":"communication_id","type":"uuid","required":true,"description":"Communication id."},{"name":"sequence","type":"number","required":true,"description":"Per-communication sequence number."},{"name":"event_type","type":"string","required":true,"description":"Event type such as validated, queued, task_progress, requires_action, task_stage_changed, artifact_added, completed, or failed."},{"name":"status","type":"string|null","required":false,"description":"Communication status at the time of the event."},{"name":"message","type":"string|null","required":false,"description":"Human-readable event message."},{"name":"payload","type":"object","required":false,"description":"Event payload."},{"name":"artifact_filename","type":"string|null","required":false,"description":"Artifact filename when the event attached an artifact."},{"name":"artifact_source","type":"string|null","required":false,"description":"Artifact source label."},{"name":"created_at","type":"string","required":true,"description":"Event timestamp."}]},{"name":"CommunicationTask","description":"Linked task summary when the communication is backed by async work.","fields":[{"name":"id","type":"uuid","required":true,"description":"Task id."},{"name":"type","type":"string|null","required":false,"description":"Task type."},{"name":"stage","type":"string|null","required":false,"description":"Current task stage."},{"name":"job_id","type":"string|null","required":false,"description":"Browser orchestrator job id when available."}]},{"name":"CommunicationReasoningLookup","description":"Lookup payload for related reasoning context.","fields":[{"name":"context_type","type":"string|null","required":false,"description":"Reasoning context type."},{"name":"context_id","type":"string|null","required":false,"description":"Reasoning context id."},{"name":"task_id","type":"uuid|null","required":false,"description":"Associated task id."},{"name":"entry_id","type":"uuid|null","required":false,"description":"Primary reasoning entry id when available."}]},{"name":"CommunicationArtifact","description":"Communication artifact metadata, usually backed by a browser screenshot.","fields":[{"name":"filename","type":"string","required":true,"description":"Artifact filename."},{"name":"source","type":"string|null","required":false,"description":"Artifact source label."},{"name":"url","type":"string","required":true,"description":"API-relative artifact URL."}]},{"name":"CommunicationWebhook","description":"Request-scoped webhook delivery summary stored on a communication.","fields":[{"name":"url","type":"string|null","required":false,"description":"Webhook URL for this communication, when configured."},{"name":"delivery_attempts","type":"number","required":true,"description":"Number of webhook delivery attempts."},{"name":"last_attempt_at","type":"string|null","required":false,"description":"Timestamp of the last delivery attempt."},{"name":"last_status","type":"string|null","required":false,"description":"Latest webhook delivery status."},{"name":"last_error","type":"string|null","required":false,"description":"Latest webhook error summary."}]},{"name":"Communication","description":"Generic non-assignment communication record returned by the communications API.","fields":[{"name":"id","type":"uuid","required":true,"description":"Communication id."},{"name":"owner_user_id","type":"uuid","required":true,"description":"Billing account owner id."},{"name":"acting_user_id","type":"uuid","required":true,"description":"Actual acting user id after delegate resolution."},{"name":"api_key_id","type":"uuid|null","required":false,"description":"API key id that created the communication."},{"name":"channel","type":"string","required":true,"description":"Channel identifier."},{"name":"target_user_id","type":"uuid|null","required":false,"description":"Resolved target user id when available."},{"name":"target_summary","type":"object","required":false,"description":"Resolved target identity snapshot."},{"name":"request_payload","type":"object","required":false,"description":"Sanitized request snapshot."},{"name":"dry_run","type":"boolean","required":true,"description":"Whether the communication was a dry run."},{"name":"status","type":"queued|running|requires_action|completed|failed|canceled","required":true,"description":"Normalized communication status."},{"name":"result","type":"object","required":false,"description":"Channel-specific result payload with normalized outcome values like sent, invited, referral_requested, duplicate_prevented, or dry_run."},{"name":"task","type":"CommunicationTask|null","required":false,"description":"Linked task summary when the send is async."},{"name":"reasoning_lookup","type":"CommunicationReasoningLookup","required":false,"description":"Reasoning lookup payload."},{"name":"events","type":"CommunicationEvent[]","required":false,"description":"Recent event log entries."},{"name":"artifacts","type":"CommunicationArtifact[]","required":false,"description":"Artifact list for the communication."},{"name":"webhook","type":"CommunicationWebhook","required":false,"description":"Webhook delivery summary."},{"name":"completed_at","type":"string|null","required":false,"description":"Terminal timestamp when applicable."},{"name":"created_at","type":"string","required":true,"description":"Creation timestamp."},{"name":"updated_at","type":"string","required":true,"description":"Last update timestamp."}]},{"name":"Project","description":"Public API name for a Super Carl assignment workspace. Older internal fields may still use assignment/campaign names.","fields":[{"name":"id","type":"uuid","required":true,"description":"Project id. This is the assignment id used by legacy product routes."},{"name":"creator_user_id","type":"uuid","required":true,"description":"Project owner user id."},{"name":"title","type":"string|null","required":false,"description":"User-facing project name."},{"name":"description","type":"string|null","required":false,"description":"Project goal or search description."},{"name":"status","type":"string|null","required":false,"description":"Project state such as draft, active, paused, completed, or archived."},{"name":"total_targets","type":"number","required":false,"description":"Count of included non-owner targets."},{"name":"messages_sent","type":"number","required":false,"description":"Targets with sent outreach statuses."},{"name":"responses","type":"number","required":false,"description":"Targets with responded/engaged states."},{"name":"email_subject_template","type":"string|null","required":false,"description":"Saved Gmail/email subject template."},{"name":"outreach_message_prompt","type":"string|null","required":false,"description":"Saved outreach-message template."},{"name":"engagement_meta_prompt","type":"string|null","required":false,"description":"Saved engagement/meta prompt."},{"name":"engagement_prompt","type":"string|null","required":false,"description":"Saved engagement prompt."},{"name":"referral_intro_prompt","type":"string|null","required":false,"description":"Saved connector/referral intro template."},{"name":"referral_forward_note_prompt","type":"string|null","required":false,"description":"Saved referral-forward note template."},{"name":"template_fingerprint","type":"string|null","required":false,"description":"Hash of template inputs used to detect stale generated messages."},{"name":"targets","type":"ProjectTarget[]","required":false,"description":"Inline targets when include_targets=true."},{"name":"created_at","type":"string","required":false,"description":"Creation timestamp."},{"name":"updated_at","type":"string","required":false,"description":"Last update timestamp."}]},{"name":"ProjectTarget","description":"Included target row in a Super Carl project.","fields":[{"name":"id","type":"uuid","required":true,"description":"Assignment target row id. Use this in target_ids for /messages/generate."},{"name":"campaign_id","type":"uuid","required":true,"description":"Project/assignment id."},{"name":"target_user_id","type":"uuid","required":true,"description":"Target user id."},{"name":"user_name","type":"string|null","required":false,"description":"Resolved target display name."},{"name":"user_headline","type":"string|null","required":false,"description":"Resolved target headline/bio."},{"name":"linkedin_profile_url","type":"string|null","required":false,"description":"LinkedIn profile URL when known."},{"name":"outreach_status","type":"string|null","required":false,"description":"Project outreach status for this target."},{"name":"recipient_status","type":"string|null","required":false,"description":"Recipient engagement/reply status for this target."},{"name":"generated_message","type":"string|null","required":false,"description":"Generated personalized outreach body when present."},{"name":"approval_status","type":"string|null","required":false,"description":"Draft approval state."},{"name":"has_previous_correspondence","type":"boolean","required":false,"description":"Whether Carl can see previous correspondence with this target."},{"name":"previous_correspondence_count","type":"number","required":false,"description":"Visible previous correspondence count."}]},{"name":"ProjectMetrics","description":"Response metrics returned by GET /api/v1/projects/:projectId/metrics.","fields":[{"name":"project_id","type":"uuid","required":true,"description":"Project id."},{"name":"total_targets","type":"number","required":true,"description":"Included non-owner targets."},{"name":"messages_sent","type":"number","required":true,"description":"Targets counted as sent/contacted."},{"name":"responses","type":"number","required":true,"description":"Targets counted as responded/engaged."},{"name":"response_rate","type":"number|null","required":true,"description":"responses / messages_sent, null when messages_sent is zero."},{"name":"target_response_rate","type":"number|null","required":true,"description":"responses / total_targets, null when total_targets is zero."},{"name":"views_count","type":"number","required":true,"description":"Targets with recipient_viewed_at."},{"name":"schedule_link_clicks","type":"number","required":true,"description":"Targets with schedule funnel/click/open signals."},{"name":"schedule_link_click_rate","type":"number|null","required":true,"description":"schedule_link_clicks / messages_sent, null when messages_sent is zero."},{"name":"outreach_status_counts","type":"object","required":true,"description":"Counts by outreach_status."},{"name":"recipient_status_counts","type":"object","required":true,"description":"Counts by recipient_status."}]},{"name":"SearchRequest","description":"Payload for /api/v1/search/people and /api/v1/search/people/preview.","fields":[{"name":"description","type":"string","required":false,"description":"Preferred natural language search description (auto-translated into AdvancedFilters unless filters/search_metadata are provided). Echoed back in search_metadata.description_snapshot."},{"name":"query","type":"string","required":false,"description":"Legacy alias for description. Use description instead."},{"name":"keywords","type":"string|string[]","required":false,"description":"Deprecated. When provided, merged into filters.additional_context; prefer filters.additional_context (or additional_context_keywords)."},{"name":"linkedin_username","type":"string","required":false,"description":"Optional LinkedIn username (vanity handle) to run a direct lookup. If provided, it ignores description/query/filters."},{"name":"linkedin_profile_url","type":"string","required":false,"description":"Optional full LinkedIn profile URL for direct lookup. Use this when your upstream workflow already has profile URLs instead of vanity handles."},{"name":"linkedin_url","type":"string","required":false,"description":"Alias for linkedin_profile_url, accepted for direct lookup."},{"name":"limit","type":"number","required":false,"description":"Number of results to return (default 20)."},{"name":"offset","type":"number","required":false,"description":"Results offset (default 0)."},{"name":"filters","type":"object","required":false,"description":"Advanced filters (see AdvancedFilters). Supplying this skips auto-translation of description."},{"name":"search_metadata","type":"object","required":false,"description":"Optional metadata payload including filters and search context."},{"name":"include_evidence_text","type":"boolean","required":false,"description":"Inline aggregated profile evidence text on each returned Person row."},{"name":"include_evidence_json","type":"boolean","required":false,"description":"Inline structured profile evidence JSON on each returned Person row. More verbose than evidence_text."},{"name":"evidence_format","type":"string","required":false,"description":"Evidence shorthand: none|text|json|both. text maps to include_evidence_text, json maps to include_evidence_json."},{"name":"evidence_text_mode","type":"string","required":false,"description":"Evidence text density (base|full). base is compact embedding text; full adds company blocks and recent posts."},{"name":"evidence_posts_limit","type":"number","required":false,"description":"Maximum recent posts included when evidence_text_mode=full (default 20, max 50)."},{"name":"delegate_user_id","type":"uuid","required":false,"description":"Run the search as an allocated team member (billing stays with owner)."},{"name":"exclude_user_ids","type":"string[]","required":false,"description":"Exclude specific user ids."},{"name":"connections_only","type":"boolean","required":false,"description":"Limit to first-degree network."},{"name":"scope","type":"string","required":false,"description":"Optional network scope override."},{"name":"target_name","type":"string","required":false,"description":"Optional name lookup/autocomplete hint. When provided, description/query translation is skipped."},{"name":"include_filter_stats","type":"boolean","required":false,"description":"Include filter statistics in the response."},{"name":"suggestion_probes","type":"object","required":false,"description":"Optional probes for suggestion generation."},{"name":"sort_by","type":"string","required":false,"description":"Sort key (e.g. relevance)."},{"name":"sort_order","type":"string","required":false,"description":"Sort order (asc|desc)."},{"name":"defer_enrichment","type":"boolean","required":false,"description":"Skip enrichment for faster responses. Full searches with evidence_format=reasons override this because that mode intentionally builds review-tier match reasons."},{"name":"skip_match_reasons","type":"boolean","required":false,"description":"Skip LLM match reasons to reduce backend work and payload size. Preview searches force this behavior; full searches with evidence_format=reasons override it."}]},{"name":"SearchResponse","description":"Response from full or preview search requests.","fields":[{"name":"success","type":"boolean","required":true,"description":"Whether the search succeeded."},{"name":"search_id","type":"string|null","required":false,"description":"Search identifier for enrichment."},{"name":"enrichable","type":"boolean","required":false,"description":"True when enrichment is available."},{"name":"users","type":"Person[]","required":true,"description":"Search results."},{"name":"pagination","type":"Pagination","required":true,"description":"Pagination data."},{"name":"search_metadata","type":"SearchMetadata","required":false,"description":"Search context and filters."},{"name":"no_results_reason","type":"string|null","required":false,"description":"Optional deterministic explanation for zero-result responses."},{"name":"linkedin_unavailable","type":"boolean","required":false,"description":"LinkedIn data unavailable."},{"name":"linkedin_error","type":"string|null","required":false,"description":"LinkedIn error message."},{"name":"viewer_network","type":"ViewerNetworkState","required":false,"description":"Caller-scoped network state attached on the MCP layer so agents can answer sync/session questions in-band rather than hedging or making a separate get_product_help call. Includes synced LinkedIn snapshot stats (used by network/reachability filters) and live LinkedIn session state (gates live actions only)."},{"name":"network_filter_status","type":"object","required":false,"description":"MCP interpretation for hard-network zeros or explicit boost-mode degree requests. Distinguishes indexing lag, scope-limited zeros, and broad boost totals that are not connection counts."}]},{"name":"ViewerNetworkState","description":"Compact snapshot of the calling user's integration state. The \"synced data\" facet (linkedin_sync_data) governs what network/worked-with/shared-school/reachability filters can be applied; the \"session\" facet (linkedin_session) governs live LinkedIn actions like send-message and accept-invite. The two are independent: a user can search their synced 1st-degree network even with an expired session.","fields":[{"name":"linkedin_sync_data","type":"LinkedinSyncData","required":false,"description":"Synced LinkedIn snapshot in our DB. Its second-degree count is derived from shared Super Carl connections, not LinkedIn's full native graph."},{"name":"linkedin_session","type":"LinkedinSession","required":false,"description":"Live LinkedIn browser session held by the extension."},{"name":"super_carl_network","type":"SuperCarlNetworkSummary","required":false,"description":"Super Carl claimed-invite graph counts."},{"name":"network_degree_scope","type":"NetworkDegreeScope","required":false,"description":"Canonical definition and coverage counts for derived network degrees."},{"name":"gmail","type":"GmailIntegrationSummary","required":false,"description":"Gmail integration state."},{"name":"network_filters_available","type":"string[]","required":false,"description":"Explicit list of network/relationship filters the caller can apply right now (e.g. [\"1st\",\"2nd\",\"worked_with\",\"shared_school\"])."},{"name":"notes","type":"string[]","required":false,"description":"Plain-English nudges the agent should treat as canonical (sync-vs-session distinction)."}]},{"name":"LinkedinSyncData","description":"Synced LinkedIn snapshot stats. Network-degree, worked-with, shared-school, and reachability filters read this — search works whenever available is true, even if the live session has expired.","fields":[{"name":"available","type":"boolean","required":true,"description":"True if a completed sync exists or first_degree_count > 0."},{"name":"first_degree_count","type":"number","required":true,"description":"Synced 1st-degree LinkedIn connections."},{"name":"second_degree_count","type":"number","required":true,"description":"Profiles in the derived LinkedIn-labeled 2nd-degree scope shared through claimed Super Carl connections. This is not LinkedIn's full native 2nd-degree graph."},{"name":"sync_run_status","type":"string|null","required":false,"description":"Most recent linkedin_connections_runs row status (completed, running, failed, etc.)."},{"name":"last_sync_completed_at","type":"string|null","required":false,"description":"ISO timestamp of the most recent successful sync."},{"name":"failure_reason","type":"string|null","required":false,"description":"Reason from the most recent sync run if it failed."}]},{"name":"NetworkDegreeScope","description":"Coverage contract for requester-relative degree fields and job/company network overlays.","fields":[{"name":"second_degree","type":"SecondDegreeScope","required":false,"description":"How Super Carl derives the viewer's searchable 2nd-degree graph."},{"name":"row_field_semantics","type":"object","required":false,"description":"Legend clarifying that connection_degree/network_degree describe requester-relative graph membership, while is_linkedin_connection and connection_status describe direct relationships only."}]},{"name":"SecondDegreeScope","description":"Super Carl 2nd-degree coverage derived through claimed Super Carl connections that have shared their networks.","fields":[{"name":"model","type":"string","required":true,"description":"Stable scope identifier: claimed_super_carl_shared_networks."},{"name":"claimed_introducer_count","type":"number","required":true,"description":"Claimed Super Carl connections whose shared networks can extend the viewer's graph."},{"name":"shared_profile_count","type":"number","required":true,"description":"Deduplicated profiles in the combined Super Carl-derived 2nd-degree graph."},{"name":"searchable_shared_profile_count","type":"number","required":true,"description":"Combined shared 2nd-degree profiles currently searchable in the profile index."},{"name":"shared_linkedin_profile_count","type":"number","required":true,"description":"Profiles currently present in the shared LinkedIn-labeled 2nd-degree graph."},{"name":"searchable_shared_linkedin_profile_count","type":"number","required":true,"description":"Shared 2nd-degree profiles currently searchable in the profile index."},{"name":"shared_super_carl_profile_count","type":"number","required":true,"description":"Profiles currently present in the claimed-invite 2nd-degree graph."},{"name":"searchable_shared_super_carl_profile_count","type":"number","required":true,"description":"Claimed-invite 2nd-degree profiles currently searchable in the profile index."},{"name":"full_linkedin_graph_imported","type":"boolean","required":true,"description":"Always false: Super Carl does not import LinkedIn's full native 2nd-degree graph."},{"name":"grow_network","type":"object","required":true,"description":"Network → Add Connection route and guidance for inviting key LinkedIn contacts to expand shared reachability."},{"name":"research_target_mutuals","type":"object","required":true,"description":"Target-specific social_proximity_research guidance for investigating possible LinkedIn mutual paths outside the current shared graph."},{"name":"note","type":"string","required":true,"description":"Plain-English explanation of the coverage boundary."}]},{"name":"LinkedinSession","description":"Live LinkedIn browser session held by the extension. Required only for live actions (send message, accept invite, fresh scrape, continue sync). Does NOT gate search.","fields":[{"name":"active","type":"boolean","required":true,"description":"True iff connection_state is \"connected\"."},{"name":"connection_state","type":"string|null","required":false,"description":"Raw connection state from browser_sessions."},{"name":"expires_at","type":"string|null","required":false,"description":"ISO timestamp when the session expires."},{"name":"note","type":"string","required":false,"description":"Human-readable summary of what the session does/does not unlock."}]},{"name":"SuperCarlNetworkSummary","description":"Super Carl claimed-invite graph counts.","fields":[{"name":"first_degree_count","type":"number","required":true,"description":"Number of claimed Super Carl invites for the caller."}]},{"name":"GmailIntegrationSummary","description":"Gmail integration state.","fields":[{"name":"connected","type":"boolean","required":true,"description":"True if a Gmail account record exists with an email."},{"name":"status","type":"string|null","required":false,"description":"Account status from user_gmail_accounts."}]},{"name":"Pagination","description":"Pagination details for result sets.","fields":[{"name":"limit","type":"number","required":true,"description":"Page size."},{"name":"offset","type":"number","required":true,"description":"Result offset."},{"name":"total","type":"number","required":true,"description":"Total matching results."},{"name":"hasMore","type":"boolean","required":false,"description":"More results available."}]},{"name":"Person","description":"Primary person record returned by searches, including requester-relative reachability and social proximity summary fields when available.","fields":[{"name":"id","type":"uuid","required":true,"description":"User id."},{"name":"name","type":"string","required":true,"description":"Full name."},{"name":"username","type":"string","required":false,"description":"Handle/username."},{"name":"picture","type":"string","required":false,"description":"Profile image URL."},{"name":"headline","type":"string","required":false,"description":"Headline or summary."},{"name":"company","type":"string","required":false,"description":"Company name."},{"name":"current_title","type":"string","required":false,"description":"Current job title."},{"name":"current_company","type":"string","required":false,"description":"Current employer."},{"name":"current_experience_selection_source","type":"string","required":false,"description":"How the current role was selected for display (for example, matched current role vs fallback)."},{"name":"matched_current_experience","type":"MatchedCurrentExperience","required":false,"description":"Metadata for the displayed current role (aligned with current_title/current_company)."},{"name":"matched_role_experience","type":"MatchedRoleExperience","required":false,"description":"Optional best role-match evidence when it differs from the displayed current role (can be historical)."},{"name":"location","type":"string","required":false,"description":"Location string."},{"name":"bio","type":"string","required":false,"description":"User bio."},{"name":"bio_ai","type":"string","required":false,"description":"AI-generated bio."},{"name":"linkedin_url","type":"string","required":false,"description":"LinkedIn profile URL."},{"name":"supercarl_url","type":"string","required":false,"description":"Super Carl profile URL (when username is available)."},{"name":"years_experience_months","type":"number|null","required":false,"description":"Total career experience in months when available."},{"name":"current_role_tenure_months","type":"number|null","required":false,"description":"Current-role tenure in months when available."},{"name":"average_role_tenure_months","type":"number|null","required":false,"description":"Average tenure per role in months when available."},{"name":"connections_count","type":"number|null","required":false,"description":"LinkedIn/CoreSignal connection count when available."},{"name":"followers_count","type":"number|null","required":false,"description":"LinkedIn/CoreSignal follower count when available."},{"name":"education","type":"array","required":false,"description":"Indexed education entries when available."},{"name":"languages","type":"array","required":false,"description":"Profile languages when available."},{"name":"recommendations_count","type":"number|null","required":false,"description":"LinkedIn/CoreSignal recommendation count when available."},{"name":"evidence_text","type":"string","required":false,"description":"Optional aggregated evidence text when include_evidence_text=true on search/preview/enrich."},{"name":"evidence_text_mode","type":"string","required":false,"description":"Evidence text density returned for evidence_text (base|full)."},{"name":"evidence_posts_included","type":"number","required":false,"description":"Count of recent posts included in evidence_text when mode=full."},{"name":"evidence_companies_included","type":"number","required":false,"description":"Count of company detail blocks included in evidence_text when mode=full."},{"name":"instagram_url","type":"string","required":false,"description":"Instagram URL."},{"name":"connection_degree","type":"number|null","required":false,"description":"Connection degree (1,2,3)."},{"name":"connection_status","type":"string","required":false,"description":"Connection status."},{"name":"has_previous_correspondence","type":"boolean","required":false,"description":"Whether the requester has visible prior correspondence with this resolved user across synced/API channels."},{"name":"previous_correspondence_count","type":"number","required":false,"description":"Count of visible prior correspondence records for this requester/target pair."},{"name":"previous_correspondence_last_sent_at","type":"string|null","required":false,"description":"Most recent prior correspondence timestamp when available."},{"name":"mutual_connections_count","type":"number","required":false,"description":"Mutual connections count surfaced on people-search responses."},{"name":"mutual_connections","type":"PersonSummary[]","required":false,"description":"Mutual connections."},{"name":"social_proximity_score","type":"number|null","required":false,"description":"Requester-relative 0-100 summary score. This mirrors search_score from the authenticated social-proximity models."},{"name":"social_proximity_band","type":"very_warm|warm|some_signal|weak|null","required":false,"description":"Machine-friendly band derived from social_proximity_score."},{"name":"social_proximity_tier","type":"string|null","required":false,"description":"Human label for social_proximity_band (Very warm, Warm, Some signal, Weak)."},{"name":"best_intro_path_type","type":"supercarl_referral|manual_linkedin_intro|null","required":false,"description":"Best available intro path inferred from mutual connector availability."},{"name":"score_version","type":"number|null","required":false,"description":"Social proximity score config version. Current version: 7."},{"name":"match_reasons","type":"string[]|null","required":false,"description":"Enrichment match reasons."},{"name":"match_reasons_companies","type":"array","required":false,"description":"Company match reasons."},{"name":"requires_linkedin_messaging","type":"boolean","required":false,"description":"LinkedIn messaging required."},{"name":"is_supercarl_user","type":"boolean","required":false,"description":"Has Super Carl account."},{"name":"is_linkedin_only","type":"boolean","required":false,"description":"LinkedIn-only profile."},{"name":"profile_loading_status","type":"string","required":false,"description":"Profile enrichment status."},{"name":"profile_intersections","type":"object","required":false,"description":"Shared background summary."},{"name":"tags","type":"string[]","required":false,"description":"Tags and labels."},{"name":"referral_status","type":"string","required":false,"description":"Referral workflow status."},{"name":"referral_status_reason","type":"string","required":false,"description":"Referral status detail."}]},{"name":"PersonSummary","description":"Compact person summary used for mutual connections.","fields":[{"name":"id","type":"uuid","required":true,"description":"User id."},{"name":"name","type":"string","required":true,"description":"Full name."},{"name":"picture","type":"string","required":false,"description":"Profile image URL."},{"name":"username","type":"string","required":false,"description":"Handle/username."}]},{"name":"MatchedCurrentExperience","description":"Details about the role used for current title/company display.","fields":[{"name":"title","type":"string|null","required":false,"description":"Selected title."},{"name":"company","type":"string|null","required":false,"description":"Selected company."},{"name":"is_current","type":"boolean","required":false,"description":"Whether the selected role is current."},{"name":"selection_source","type":"string|null","required":false,"description":"Selection reason label (for example, search_matched_current_role)."},{"name":"match_score","type":"number|null","required":false,"description":"Deterministic match score used for ranking."},{"name":"matched_terms","type":"object|null","required":false,"description":"Matched term groups (preferred titles/companies, query terms, keywords)."}]},{"name":"MatchedRoleExperience","description":"Optional matched role evidence that can represent a historical role.","fields":[{"name":"title","type":"string|null","required":false,"description":"Matched title."},{"name":"company","type":"string|null","required":false,"description":"Matched company."},{"name":"is_current","type":"boolean","required":false,"description":"Whether the matched role is current."},{"name":"selection_source","type":"string|null","required":false,"description":"Selection reason label (for example, search_matched_role_history)."},{"name":"match_score","type":"number|null","required":false,"description":"Deterministic match score used for ranking."},{"name":"matched_terms","type":"object|null","required":false,"description":"Matched term groups (preferred titles/companies, query terms, keywords)."}]},{"name":"ProfileSnapshot","description":"Response from /api/v1/profiles/:id.","fields":[{"name":"id","type":"uuid","required":true,"description":"User id."},{"name":"name","type":"string","required":true,"description":"Full name."},{"name":"username","type":"string","required":false,"description":"Handle/username."},{"name":"picture","type":"string","required":false,"description":"Profile image URL."},{"name":"bio","type":"string|null","required":false,"description":"Bio summary."},{"name":"location","type":"string|null","required":false,"description":"Location string."},{"name":"linkedin_url","type":"string|null","required":false,"description":"LinkedIn profile URL."},{"name":"supercarl_url","type":"string|null","required":false,"description":"Super Carl profile URL."},{"name":"created_at","type":"string","required":false,"description":"ISO timestamp for creation."},{"name":"last_active","type":"string|null","required":false,"description":"Last active timestamp."}]},{"name":"ProfileChunksResponse","description":"Response from /api/v1/profiles/:id/chunks.","fields":[{"name":"success","type":"boolean","required":true,"description":"Whether the request succeeded."},{"name":"user_id","type":"uuid","required":true,"description":"User id."},{"name":"chunks","type":"ProfileChunk[]","required":true,"description":"Cached profile chunks and posts."}]},{"name":"ProfileChunk","description":"Structured chunk describing profile experiences, education, or posts.","fields":[{"name":"id","type":"uuid","required":true,"description":"Chunk id."},{"name":"chunk_type","type":"string","required":true,"description":"Chunk type (headline, summary, profile_location, experience, education, post, repost)."},{"name":"chunk_text","type":"string","required":true,"description":"Text for the chunk."},{"name":"chunk_metadata","type":"ExperienceChunkMetadata|EducationChunkMetadata|PostChunkMetadata|object","required":false,"description":"Structured metadata for the chunk. Experience chunks include title/company/date fields and tenure_months when available."},{"name":"chunk_order","type":"number","required":false,"description":"Order of the chunk."},{"name":"created_at","type":"string","required":false,"description":"ISO timestamp for the chunk."},{"name":"company_id","type":"uuid|null","required":false,"description":"Company id when applicable."}]},{"name":"ExperienceChunkMetadata","description":"Structured metadata for experience chunks returned by /api/v1/profiles/:id/chunks.","fields":[{"name":"title","type":"string|null","required":false,"description":"Role title."},{"name":"company","type":"string|null","required":false,"description":"Employer name."},{"name":"location","type":"string|null","required":false,"description":"Role location text."},{"name":"starts_at","type":"object|null","required":false,"description":"Structured start date object when available."},{"name":"ends_at","type":"object|null","required":false,"description":"Structured end date object when available."},{"name":"start_year","type":"number|null","required":false,"description":"Start year."},{"name":"start_month","type":"number|null","required":false,"description":"Start month."},{"name":"end_year","type":"number|null","required":false,"description":"End year."},{"name":"end_month","type":"number|null","required":false,"description":"End month."},{"name":"is_current","type":"boolean","required":false,"description":"Whether this is the current role."},{"name":"date_range","type":"string|null","required":false,"description":"Readable date range label."},{"name":"tenure_months","type":"number|null","required":false,"description":"Computed tenure in months for the role when dates are available."},{"name":"description","type":"string|null","required":false,"description":"Role description text."},{"name":"logo_url","type":"string|null","required":false,"description":"Company logo URL when available."},{"name":"company_linkedin_profile_url","type":"string|null","required":false,"description":"LinkedIn company URL when available."},{"name":"company_id","type":"uuid|null","required":false,"description":"Resolved company id when available."},{"name":"experience_source_key","type":"string|null","required":false,"description":"Stable source key for the experience row when available."},{"name":"experience_source_type","type":"string|null","required":false,"description":"Experience source type (for example synced or manual)."},{"name":"manual_experience_id","type":"string|null","required":false,"description":"Manual experience id when the role came from a manual override."},{"name":"manual_override","type":"boolean","required":false,"description":"Whether the role was manually overridden."}]},{"name":"EducationChunkMetadata","description":"Structured metadata for education chunks.","fields":[{"name":"school","type":"string|null","required":false,"description":"School or institution name."},{"name":"degree_name","type":"string|null","required":false,"description":"Degree name."},{"name":"field_of_study","type":"string|null","required":false,"description":"Field of study."},{"name":"start_year","type":"number|null","required":false,"description":"Start year."},{"name":"end_year","type":"number|null","required":false,"description":"End year."},{"name":"starts_at","type":"object|null","required":false,"description":"Structured start date object when available."},{"name":"ends_at","type":"object|null","required":false,"description":"Structured end date object when available."},{"name":"date_range","type":"string|null","required":false,"description":"Readable date range label."}]},{"name":"PostChunkMetadata","description":"Structured metadata for post and repost chunks.","fields":[{"name":"post_url","type":"string|null","required":false,"description":"Canonical post URL when available."},{"name":"share_url","type":"string|null","required":false,"description":"Share URL when available."},{"name":"post_date","type":"string|null","required":false,"description":"Normalized post date."},{"name":"post_date_raw","type":"string|null","required":false,"description":"Original post date string when preserved."},{"name":"post_platform","type":"string|null","required":false,"description":"Inferred post platform."},{"name":"activity_action_type","type":"string|null","required":false,"description":"Resolved activity action type when the row is an activity rather than an authored post."},{"name":"activity_target_name","type":"string|null","required":false,"description":"Resolved activity target name when available."},{"name":"dimension_tags","type":"string[]","required":false,"description":"Optional dimension tags."},{"name":"topic_tags","type":"string[]","required":false,"description":"Optional topic tags."}]},{"name":"ProfileText","description":"Profile text payload for /api/v1/profiles/:id/text.","fields":[{"name":"mode","type":"string","required":true,"description":"Text mode (base|full)."},{"name":"text","type":"string","required":true,"description":"Aggregated profile text ready for embedding."},{"name":"posts_included","type":"number","required":false,"description":"Number of posts included (full density)."},{"name":"companies_included","type":"number","required":false,"description":"Number of companies with detail blocks (full density)."}]},{"name":"JobNetworkOverlayStatus","description":"Readiness and scope for per-job viewer-network counts. A zero is conclusive only when status is ready and zero_counts_are_conclusive is true; unavailable means unknown.","fields":[{"name":"status","type":"string","required":true,"description":"ready, partial, unavailable, not_requested, or not_applicable."},{"name":"ready","type":"boolean","required":true,"description":"Whether the per-job overlay count lookup completed for every returned company id."},{"name":"zero_counts_are_conclusive","type":"boolean","required":true,"description":"True only when numeric zeros are known zeros in the declared scope."},{"name":"scope","type":"string","required":true,"description":"current_super_carl_shared_network_only; never LinkedIn-wide."},{"name":"second_degree_model","type":"string","required":true,"description":"claimed_super_carl_shared_networks."},{"name":"full_linkedin_graph_imported","type":"boolean","required":true,"description":"Always false; the overlay is not LinkedIn's full native second-degree graph."},{"name":"requested_company_count","type":"number","required":true,"description":"Returned company ids requested from the overlay."},{"name":"covered_company_count","type":"number","required":true,"description":"Returned company ids with an overlay summary. When status is partial, these summaries are lower bounds rather than complete counts."},{"name":"company_alias_expansion_complete","type":"boolean","required":true,"description":"Whether exact employer-id aliases were fully resolved before interpreting missing buckets as zero."},{"name":"recommended_actions","type":"object[]","required":true,"description":"Graph-growth and selected-target mutual-research alternatives."}]},{"name":"JobPosting","description":"Job posting row returned by /api/v1/search/jobs/preview. Each row is decorated with a network block summarizing 1st/2nd-degree connections at the posting company.","fields":[{"name":"id","type":"uuid","required":true,"description":"Job posting id."},{"name":"company_id","type":"uuid","required":false,"description":"Resolved company id when available."},{"name":"company_name","type":"string","required":false,"description":"Company name."},{"name":"title","type":"string","required":true,"description":"Job title."},{"name":"description","type":"string","required":false,"description":"Job description text."},{"name":"location","type":"string","required":false,"description":"Full location string."},{"name":"city","type":"string","required":false,"description":"City when parsed."},{"name":"state","type":"string","required":false,"description":"State/region when parsed."},{"name":"country","type":"string","required":false,"description":"Country when parsed."},{"name":"department","type":"string","required":false,"description":"Department when provided."},{"name":"seniority","type":"string","required":false,"description":"Seniority level when classified."},{"name":"management_level","type":"string","required":false,"description":"Management level when classified."},{"name":"employment_type","type":"string","required":false,"description":"Employment type (full-time, contract, etc.)."},{"name":"accepts_remote","type":"boolean","required":false,"description":"Provider-supplied remote-work signal. This remains separate from the derived workplace classification."},{"name":"workplace_type","type":"string","required":true,"description":"Derived work arrangement: remote, hybrid, onsite, or unknown."},{"name":"days_in_office_per_week","type":"number|null","required":false,"description":"Exact required office days per week when the posting states one."},{"name":"days_in_office_per_week_min","type":"number|null","required":false,"description":"Minimum required office days per week when the posting states a range."},{"name":"days_in_office_per_week_max","type":"number|null","required":false,"description":"Maximum required office days per week when the posting states a range."},{"name":"workplace_type_confidence","type":"string","required":false,"description":"Classification confidence: high, medium, or low."},{"name":"workplace_type_source","type":"string","required":false,"description":"Classification provenance: model, source_only, or none."},{"name":"workplace_type_evidence","type":"string|null","required":false,"description":"Short verbatim evidence from the job source supporting the classification."},{"name":"workplace_type_evidence_source","type":"string|null","required":false,"description":"Source field containing the evidence, such as description, location, benefits, or title."},{"name":"workplace_type_evidence_scope","type":"string|null","required":false,"description":"Whether the evidence applies to this position, a broader company policy, or is unknown."},{"name":"workplace_type_evidence_url","type":"string|null","required":false,"description":"Posting or source URL associated with the evidence when available."},{"name":"workplace_type_conditions","type":"string[]","required":false,"description":"Concise qualifications or conditions attached to the arrangement."},{"name":"date_posted","type":"string","required":false,"description":"ISO date the job was posted."},{"name":"valid_through","type":"string","required":false,"description":"ISO date the listing expires."},{"name":"primary_url","type":"string","required":false,"description":"Canonical posting URL when known."},{"name":"network","type":"object","required":false,"description":"Viewer-relative network summary at the posting company. Check counts_ready/zero_counts_are_conclusive; unavailable counts are null rather than fabricated zeros."}]},{"name":"JobsWithPeopleGroup","description":"One company bucket returned by /api/v1/search/jobs/with-people, pairing matching jobs with the viewer's 1st/2nd-degree people at that company.","fields":[{"name":"company_id","type":"uuid","required":true,"description":"Company id for the group."},{"name":"company_name","type":"string","required":false,"description":"Company name."},{"name":"jobs","type":"JobPosting[]","required":true,"description":"Matching job postings at this company."},{"name":"people","type":"Person[]","required":true,"description":"1st/2nd-degree connections the viewer has at this company (capped by people_per_company)."}]},{"name":"ActivityPost","description":"Post/activity row returned by /api/v1/search/posts/preview and /api/v1/search/posts/with-people.","fields":[{"name":"id","type":"string","required":true,"description":"Stable activity/post id."},{"name":"activity_id","type":"string|null","required":false,"description":"Activity id in the activities index."},{"name":"url","type":"string|null","required":false,"description":"Canonical post/activity URL when known."},{"name":"user_id","type":"uuid|null","required":false,"description":"Resolved Super Carl profile id for person actors when available."},{"name":"actor_entity_type","type":"string","required":false,"description":"person or company."},{"name":"author_name","type":"string|null","required":false,"description":"Post actor/author display name."},{"name":"author_profile_url","type":"string|null","required":false,"description":"Actor LinkedIn profile URL when person-authored."},{"name":"action_type","type":"string|null","required":false,"description":"post, repost, comment, like, reaction, etc."},{"name":"body_text","type":"string|null","required":false,"description":"Truncated post body."},{"name":"hashtags","type":"string[]","required":false,"description":"Hashtags extracted from the post."},{"name":"mention_names","type":"string[]","required":false,"description":"Mention display names extracted from the post."},{"name":"reaction_count","type":"number","required":false,"description":"Reaction/like count."},{"name":"comment_count","type":"number","required":false,"description":"Comment count."},{"name":"engagement_count","type":"number","required":false,"description":"reaction_count + comment_count when available."},{"name":"observed_at","type":"string|null","required":false,"description":"Published/observed timestamp used for recency filters."},{"name":"target","type":"object","required":false,"description":"Target post/person/company fields for reposts, comments, likes, and reactions."},{"name":"highlights","type":"object|null","required":false,"description":"Search highlights when text query matched."}]},{"name":"PostMatchedPerson","description":"Deduped person row derived from matching ActivityPost actors/authors.","fields":[{"name":"user_id","type":"uuid|null","required":false,"description":"Resolved Super Carl profile id when available."},{"name":"name","type":"string|null","required":false,"description":"Person display name."},{"name":"headline","type":"string|null","required":false,"description":"Author headline when present in activity data."},{"name":"linkedin_url","type":"string|null","required":false,"description":"LinkedIn profile URL."},{"name":"matched_post_count","type":"number","required":true,"description":"Number of matching posts on the returned page for this person."},{"name":"total_reactions","type":"number","required":true,"description":"Sum of reaction counts across matched posts on the returned page."},{"name":"total_comments","type":"number","required":true,"description":"Sum of comment counts across matched posts on the returned page."},{"name":"total_engagement","type":"number","required":true,"description":"Sum of engagement counts across matched posts on the returned page."},{"name":"latest_post_at","type":"string|null","required":false,"description":"Most recent matched post timestamp."},{"name":"matched_posts","type":"ActivityPost[]","required":false,"description":"Compact matched-post evidence snippets."}]},{"name":"SearchMetadata","description":"Search context and applied filters.","fields":[{"name":"strategy","type":"string","required":false,"description":"Search strategy identifier."},{"name":"search_backend","type":"string","required":false,"description":"Backend that served the search."},{"name":"description_snapshot","type":"string","required":false,"description":"Original description/query text used to generate filters (echoed for transparency)."},{"name":"lookup","type":"object","required":false,"description":"LinkedIn lookup metadata (profile index status, optional refresh status, warnings)."},{"name":"filters","type":"object","required":false,"description":"Filter object and summaries."},{"name":"filters.summary","type":"string","required":false,"description":"Human summary of filters."},{"name":"filters.applied","type":"string[]","required":false,"description":"Applied filter labels."},{"name":"filters.advanced","type":"AdvancedFilters","required":false,"description":"Advanced filter payload."},{"name":"filters.stats","type":"object","required":false,"description":"Optional filter stats."},{"name":"company_search_filters","type":"object","required":false,"description":"Resolution metadata for include/exclude company_search_id joins (applied/capped/dropped, totals, limits)."},{"name":"no_results_reason","type":"string|null","required":false,"description":"Optional reason message for zero-result responses."},{"name":"no_results_reason_code","type":"string|null","required":false,"description":"Optional machine-readable code for no_results_reason."}]},{"name":"SocialProximityEvidence","description":"Deduped evidence item returned by authenticated social-proximity endpoints.","fields":[{"name":"label","type":"string","required":true,"description":"Human-readable evidence label."},{"name":"category","type":"string","required":true,"description":"Evidence category (direct_relationship, profile_overlap, reciprocal_communication, public_activity, mutual_connections, cross_network)."},{"name":"source","type":"string|null","required":false,"description":"Optional source network or system tag for the evidence item."}]},{"name":"SocialProximityComponents","description":"Component-level score breakdown stored in summary.metadata.components.","fields":[{"name":"direct_relationship","type":"number","required":true,"description":"Direct relationship component."},{"name":"profile_overlap","type":"number","required":true,"description":"Profile overlap component."},{"name":"reciprocal_communication","type":"number","required":true,"description":"Reciprocal communication component."},{"name":"public_activity","type":"number","required":true,"description":"Public activity component."},{"name":"mutual_connections_baseline","type":"number","required":true,"description":"Mutual-connections component used for baseline_score."},{"name":"mutual_connections_researched","type":"number|null","required":false,"description":"Mutual-connections component after fresh LinkedIn mutual research."},{"name":"mutual_connections_search","type":"number","required":true,"description":"Mutual-connections component actually used for search_score."},{"name":"cross_network","type":"number","required":true,"description":"Cross-network corroboration component."}]},{"name":"SocialProximitySummary","description":"Authenticated requester-relative social proximity summary for one target.","fields":[{"name":"score_version","type":"number","required":true,"description":"Score config version used for this summary."},{"name":"baseline_score","type":"number","required":true,"description":"Baseline 0-100 score."},{"name":"baseline_tier","type":"string","required":true,"description":"Machine tier key for baseline_score."},{"name":"baseline_band","type":"string","required":true,"description":"Machine band for baseline_score."},{"name":"researched_score","type":"number|null","required":false,"description":"Refined score once LinkedIn mutual research is available."},{"name":"researched_tier","type":"string|null","required":false,"description":"Machine tier key for researched_score."},{"name":"researched_band","type":"string|null","required":false,"description":"Machine band for researched_score."},{"name":"search_score","type":"number","required":true,"description":"Score surfaced to people search and ranking."},{"name":"search_band","type":"string","required":true,"description":"Machine band for search_score."},{"name":"evidence","type":"SocialProximityEvidence[]","required":false,"description":"Deduped evidence labels sorted by strongest contribution and recency."},{"name":"metadata.components","type":"SocialProximityComponents","required":false,"description":"Component-level score breakdown."},{"name":"metadata.direct_sources","type":"string[]","required":false,"description":"All direct relationship sources detected for the pair."},{"name":"metadata.strongest_direct_source","type":"string|null","required":false,"description":"Direct source that contributed the strongest direct-relationship score."},{"name":"metadata.mutual_connections","type":"object","required":false,"description":"Mutual-connection counts, overlap ratios, and research metadata."},{"name":"metadata.direct_relationship","type":"object","required":false,"description":"Normalized direct-relationship timestamps and verification metadata."},{"name":"linkedin_connection_date","type":"string|null","required":false,"description":"Top-level copy of metadata.direct_relationship.linkedin_connection_date."},{"name":"linkedin_connected_at","type":"string|null","required":false,"description":"Normalized LinkedIn direct-connection timestamp when available."},{"name":"linkedin_connection_last_verified","type":"string|null","required":false,"description":"Last LinkedIn verification timestamp when available."},{"name":"computed_at","type":"string|null","required":false,"description":"Timestamp when the summary was computed."},{"name":"researched_computed_at","type":"string|null","required":false,"description":"Timestamp when the researched score was last computed."}]},{"name":"SocialProximitySummaryEntry","description":"Entry returned by POST /users/social-proximity/summaries for one target user.","fields":[{"name":"subject_user_id","type":"uuid","required":true,"description":"Requested target user id."},{"name":"summary","type":"SocialProximitySummary|null","required":false,"description":"Social proximity summary for the requested target."}]},{"name":"SocialProximitySummaryResponse","description":"Response payload from POST /users/social-proximity/summaries.","fields":[{"name":"success","type":"boolean","required":true,"description":"Whether the request succeeded."},{"name":"owner_user_id","type":"uuid","required":true,"description":"Requester user id."},{"name":"summaries","type":"SocialProximitySummaryEntry[]","required":true,"description":"Per-target summary payloads."}]},{"name":"SocialProximityScoreCard","description":"Compact baseline or researched score card returned by the detail endpoint.","fields":[{"name":"score","type":"number","required":true,"description":"0-100 score for this card."},{"name":"tier","type":"string","required":true,"description":"Human-readable tier label."},{"name":"tier_key","type":"string","required":true,"description":"Machine tier key."},{"name":"band","type":"string","required":true,"description":"Machine band."},{"name":"evidence","type":"SocialProximityEvidence[]","required":false,"description":"Evidence list associated with this score card."}]},{"name":"SocialProximityConnector","description":"Candidate mutual connector returned by the detail endpoint.","fields":[{"name":"id","type":"uuid","required":true,"description":"Connector user id."},{"name":"name","type":"string","required":true,"description":"Connector name."},{"name":"picture","type":"string|null","required":false,"description":"Connector picture URL."},{"name":"username","type":"string|null","required":false,"description":"Connector username."},{"name":"headline","type":"string|null","required":false,"description":"Connector headline or bio."},{"name":"linkedin_url","type":"string|null","required":false,"description":"Connector LinkedIn URL."},{"name":"connector_type","type":"supercarl|linkedin_only","required":true,"description":"Underlying connector type used for path scoring."},{"name":"action_mode","type":"supercarl_referral|manual_linkedin_intro","required":true,"description":"How the intro should be executed."},{"name":"path_score","type":"number","required":true,"description":"Connector path score (0-100)."},{"name":"social_proximity_score","type":"number","required":true,"description":"Viewer -> connector search_score mirror."},{"name":"social_proximity_band","type":"string","required":true,"description":"Band for social_proximity_score."},{"name":"social_proximity_tier","type":"string","required":true,"description":"Human tier label for social_proximity_score."},{"name":"viewer_social_proximity_score","type":"number","required":true,"description":"Viewer -> connector search_score."},{"name":"target_social_proximity_score","type":"number","required":true,"description":"Connector -> target search_score."},{"name":"evidence_highlights","type":"string[]","required":false,"description":"Up to four deduped evidence labels for the viewer -> connector leg."},{"name":"intersection_highlights","type":"string[]","required":false,"description":"Up to four deduped evidence labels for the connector -> target leg."}]},{"name":"SocialProximityResearchStatus","description":"LinkedIn mutual-research workflow status returned by the detail endpoint.","fields":[{"name":"status","type":"string","required":true,"description":"Research status (not_started, running, completed, failed)."},{"name":"current_start_index","type":"number","required":true,"description":"Current pagination start index."},{"name":"page_size","type":"number","required":true,"description":"Research page size."},{"name":"pages_fetched","type":"number","required":true,"description":"Pages fetched so far."},{"name":"profiles_discovered","type":"number","required":true,"description":"Profiles discovered so far."},{"name":"has_more","type":"boolean","required":true,"description":"Whether more research pages remain."},{"name":"exhausted","type":"boolean","required":true,"description":"Whether the current research run is fully exhausted."},{"name":"next_page_number","type":"number","required":true,"description":"Next page number to fetch."},{"name":"browser_job_id","type":"string|null","required":false,"description":"Linked browser orchestration job id."},{"name":"reasoning_context_type","type":"string","required":true,"description":"Reasoning context type used by the research flow."},{"name":"reasoning_context_id","type":"uuid","required":true,"description":"Reasoning context id (target user id)."},{"name":"updated_at","type":"string|null","required":false,"description":"Last status update timestamp."},{"name":"last_error","type":"string|null","required":false,"description":"Last raw research error, if any."},{"name":"failure_reason","type":"string|null","required":false,"description":"Normalized failure reason."},{"name":"recovery_action","type":"string|null","required":false,"description":"Suggested recovery action."},{"name":"requires_linkedin_session","type":"boolean","required":true,"description":"Whether the current failure requires a LinkedIn browser session."},{"name":"message","type":"string|null","required":false,"description":"User-facing status message."}]},{"name":"SocialProximityDetail","description":"Response payload from GET /users/:targetUserId/social-proximity and POST /users/:targetUserId/social-proximity/research.","fields":[{"name":"baseline","type":"SocialProximityScoreCard","required":true,"description":"Baseline score card."},{"name":"researched","type":"SocialProximityScoreCard|null","required":false,"description":"Researched score card when fresh LinkedIn mutual research is available."},{"name":"evidence","type":"SocialProximityEvidence[]","required":false,"description":"Convenience alias of the baseline evidence list."},{"name":"connectors_supercarl","type":"SocialProximityConnector[]","required":false,"description":"Mutual connectors that support a SuperCarl referral."},{"name":"connectors_linkedin_manual","type":"SocialProximityConnector[]","required":false,"description":"Mutual connectors that support a manual LinkedIn intro."},{"name":"research_status","type":"SocialProximityResearchStatus","required":true,"description":"LinkedIn mutual-research status."},{"name":"score_version","type":"number","required":true,"description":"Score config version used for the payload."}]},{"name":"AdvancedFilters","description":"Structured filters for search.","fields":[{"name":"connection_degrees","type":"string[]","required":false,"description":"Network connection proximity (1st, 2nd, 3rd+)."},{"name":"exclude_connection_degrees","type":"string[]","required":false,"description":"Network connection proximity to exclude. Use [\"1st\"] for requests like \"exclude first-degree LinkedIn connections\"; only 1st/2nd are backed by searchable network bitmaps."},{"name":"job_titles","type":"object","required":false,"description":"Job titles to include/exclude and matching behavior.","shape":{"include":"string[]","exclude":"string[]","mode":"boost|must","exact":"boolean","current_only":"boolean","exclude_current_only":"boolean","match_scope":"broad|anchored_prefix|exact"}},{"name":"hiring","type":"object","required":false,"description":"Boost or filter people who work at companies hiring for specific roles (based on ingested job postings).","shape":{"mode":"boost|must","job_titles":"string[]","locations":"string[]","accepts_remote":"boolean|null"}},{"name":"locations","type":"object","required":false,"description":"Location includes/excludes and radius.","shape":{"include":"string[]","exclude":"string[]","radius_miles":"number","strict":"boolean","scope":"current|any_experience"}},{"name":"timezones","type":"object","required":false,"description":"Timezone proximity filter (UTC offset-based).","shape":{"timezone":"string|null","within_hours":"number|null"}},{"name":"companies","type":"object","required":false,"description":"Companies to include/exclude and current-vs-history scope.","shape":{"include":"string[]","exclude":"string[]","include_current_only":"boolean","exclude_current_only":"boolean","include_company_search_id":"string|null","include_company_search_boost_id":"string|null","include_clauses":"unknown","exclude_company_search_id":"string|null"}},{"name":"experience_clauses","type":"unknown","required":false,"description":"Composite experience clauses that bind titles and companies to the same experience row."},{"name":"industries","type":"string[]","required":false,"description":"Industry sectors (canonicalized using the taxonomy service)."},{"name":"years_experience","type":"object","required":false,"description":"Total years of professional experience.","shape":{"min":"number|null","max":"number|null"}},{"name":"connections_count","type":"object","required":false,"description":"LinkedIn/CoreSignal connections count range.","shape":{"min":"number|null","max":"number|null"}},{"name":"followers_count","type":"object","required":false,"description":"LinkedIn/CoreSignal followers count range.","shape":{"min":"number|null","max":"number|null"}},{"name":"education","type":"object","required":false,"description":"Education filters over schools, degrees, fields of study, and graduation year.","shape":{"schools":"string[]","degrees":"string[]","fields_of_study":"string[]","graduation_year":"object","mode":"must|boost"}},{"name":"languages","type":"object","required":false,"description":"Language filters from profile language fields.","shape":{"include":"string[]","proficiency":"string[]","mode":"must|boost"}},{"name":"recommendations","type":"object","required":false,"description":"LinkedIn recommendation filters.","shape":{"any":"boolean","mentioned":"string","recommenders":"string[]","mode":"must|boost"}},{"name":"average_role_tenure_months","type":"object","required":false,"description":"Average tenure per role (months). Current role is included only when it exceeds prior-role average.","shape":{"min":"number|null","max":"number|null"}},{"name":"current_role_tenure_months","type":"object","required":false,"description":"Tenure in current role (months).","shape":{"min":"number|null","max":"number|null","include_no_current_experience":"boolean"}},{"name":"recent_short_stints","type":"object","required":false,"description":"Recent short-stint pattern representation. Use for constraints such as \"last 2-3 jobs have been short stints\" or \"avoid recent job hoppers\".","shape":{"max_role_tenure_months":"number|null","min_count":"number|null","within_recent_roles":"number|null","exclude":"boolean","mode":"must|boost"}},{"name":"current_role_started_within_days","type":"number|null","required":false,"description":"Coarse recency filter — match people whose CURRENT role started within the last N days. Use for \"started a new job in the last week / past 2 days / recently\" queries. Coverage on the underlying experience start_date is partial; null values do not match, so this favors precision over recall."},{"name":"linkedin_connected_within_days","type":"number|null","required":false,"description":"Viewer-scoped LinkedIn first-degree connection recency — match people the viewer connected with on LinkedIn within the last N days. Use for \"new LinkedIn connections\", \"recently added connections\", or daily connection-change scans. Pair with connection_degrees:[\"1st\"] and network_filter_mode:\"filter\"; this is connection date, not job-change date."},{"name":"linkedin_connected_after","type":"string|null","required":false,"description":"Inclusive ISO date/datetime lower bound for the viewer->person LinkedIn connection date. Use for ranged first-degree network map requests such as connections added since 2026-05-01."},{"name":"linkedin_connected_before","type":"string|null","required":false,"description":"Inclusive ISO date/datetime upper bound for the viewer->person LinkedIn connection date. Use with linkedin_connected_after for connection-date ranges."},{"name":"has_current_experience","type":"boolean|null","required":false,"description":"If false, match profiles with no active/current experience row and at least one ended experience; use for \"no current role\", \"no new role yet\", \"between jobs\", or \"most recent role has an end date\" queries. If true, require at least one active/current experience. Coverage depends on profile experience freshness."},{"name":"sort_by","type":"unknown","required":false,"description":"Result-ranking dimension for comparative/superlative wording only; null when no ranking is requested."},{"name":"sort_order","type":"unknown","required":false,"description":"Direction for sort_by; null when sort_by is null."},{"name":"company_size","type":"object","required":false,"description":"Person-side fast filter on current/historical employer headcount. Reads denormalized company_employee_counts_{current,all} arrays indexed on every profile, so it does not require resolving a company-id set and runs as a single profile-index range clause. Use this for \"people at sub-200-employee companies\", \"candidates at companies with 11-50 employees\", and similar headcount-bounded sourcing. By default profiles whose employer headcount is UNKNOWN are still included (ranked below known-in-range matches) because small/boutique employers frequently lack published headcount; set include_unknown:false to require a verified in-range headcount.","shape":{"min":"number|null","max":"number|null","current_only":"boolean","include_unknown":"boolean"}},{"name":"company_revenue","type":"object","required":false,"description":"Person-side fast filter on current/historical employer revenue (USD). Reads denormalized company_revenue_{current,all} arrays on every profile, so no company-id resolution step is needed. Use this for \"people at $10M-$100M revenue companies\" and similar revenue-bounded sourcing. Profiles whose employer has no revenue data are filtered out.","shape":{"min":"number|null","max":"number|null","current_only":"boolean"}},{"name":"posts","type":"object","required":false,"description":"Structured filters over LinkedIn posts and engagement activity, including text, action type, engagement thresholds, date windows, and target entities.","shape":{"mode":"boost|must","any":"boolean","mentioned":"string","keyword_match_mode":"soft|hard","additional_context_keywords":"string[]","additional_context_keywords_core":"string[]","additional_context_keywords_supporting":"string[]","action_types":"string[]","min_reactions":"number|null","min_comments":"number|null","min_engagement":"number|null","published_within_days":"number|null","published_after":"string|null","published_before":"string|null","target_companies":"string[]","target_people":"string[]","target_urls":"string[]"}},{"name":"network_filter_mode","type":"boost|filter|ignore|connected_to","required":false,"description":"How to weight the user’s network in search results."},{"name":"connected_to","type":"string[]","required":false,"description":"User IDs whose 1st-degree network should be searched when network_filter_mode=connected_to."},{"name":"exclude_connected_to","type":"string[]","required":false,"description":"User IDs whose 1st-degree network should be excluded. Use for third-person negative connection-owner requests like \"not connected to John Doe\"; this does not change network_filter_mode."},{"name":"personas","type":"object","required":false,"description":"Persona anchors for similarity-based boosting/downranking and shared-employer filtering.","shape":{"more_like":"string[]","less_like":"string[]","worked_with":"string[]"}},{"name":"diversify_by_company","type":"boolean","required":false,"description":"If true, collapse results so each company appears at most once (where possible). Omit to use default heuristics."},{"name":"additional_context","type":"string","required":false,"description":"Free-form text describing nuance that does not map to structured filters."},{"name":"keyword_match_mode","type":"soft|hard","required":false,"description":"Whether top-level profile keyword fields are soft ranking/context evidence or a hard profile-text eligibility filter. Use hard only when the user explicitly requires profiles to mention at least one of the keyword terms."},{"name":"additional_context_keywords","type":"string[]","required":false,"description":"Profile keyword hints used to expand or refine context matching."},{"name":"additional_context_keywords_core","type":"string[]","required":false,"description":"Core profile keyword hints that should strongly influence matching."},{"name":"additional_context_keywords_supporting","type":"string[]","required":false,"description":"Supporting keyword hints that broaden recall without being mandatory."},{"name":"included_networks","type":"string[]","required":false,"description":"Networks to search (e.g., super_carl, linkedin, gmail, contacts, x, instagram)."},{"name":"reachable_via","type":"string[]","required":false,"description":"Require that results are reachable through the selected channels."},{"name":"instagram_direction","type":"none|following|followers|mutual|any","required":false,"description":"Restrict to the viewer’s Instagram follow graph: \"following\" = people you follow, \"followers\" = people who follow you, \"mutual\" = both, \"any\" = connected either way (use when an IG connection is implied but direction is unspecified), \"none\" = no IG follow constraint (default). Composes with all other filters, e.g. founders you follow on IG."},{"name":"x_direction","type":"none|following|followers|mutual|any","required":false,"description":"Restrict to the viewer’s X (Twitter) follow graph: \"following\" = people you follow, \"followers\" = people who follow you, \"mutual\" = both, \"any\" = connected either way (use when an X connection is implied but direction is unspecified), \"none\" = no X follow constraint (default). Composes with all other filters, e.g. founders who follow you on X."}]},{"name":"CompanySearchPreviewRequest","description":"Payload for /api/v1/companies/search/preview.","fields":[{"name":"query","type":"string","required":false,"description":"Natural language company query."},{"name":"filters","type":"CompanySearchFilters","required":false,"description":"Structured company filters. Numeric range fields accept number or shorthand strings (e.g., 500K, 2.5M, 1B). When provided, these override NLP extraction."},{"name":"preview_limit","type":"number","required":false,"description":"Preview size (default 10, max 25)."},{"name":"result_mode","type":"string","required":false,"description":"preview returns lightweight company rows; detailed expands each row with richer company metadata."},{"name":"include_evidence_text","type":"boolean","required":false,"description":"Inline doc-grounded evidence text for each returned company."},{"name":"evidence_post_limit","type":"number","required":false,"description":"Maximum recent company posts included in evidence_text (default 2, max 5)."},{"name":"delegate_user_id","type":"uuid","required":false,"description":"Run the company search as an allocated team member."}]},{"name":"CompanySearchFilters","description":"Structured filters for company search previews. Numeric ranges accept number or shorthand string input.","fields":[{"name":"location","type":"object","required":false,"description":"HQ location filters.","shape":{"country":"string|null","state":"string|null"}},{"name":"industries","type":"string[]","required":false,"description":"Industry labels."},{"name":"company_tags","type":"string[]","required":false,"description":"Company tags/keywords."},{"name":"company_type","type":"string[]","required":false,"description":"Company types (public, private, etc)."},{"name":"company_stage","type":"string[]","required":false,"description":"Company stages (Series A, Growth stage)."},{"name":"company_sub_stage","type":"string[]","required":false,"description":"Company sub-stages."},{"name":"company_status","type":"string[]","required":false,"description":"Company statuses (active, acquired, etc)."},{"name":"industry_keywords","type":"string[]","required":false,"description":"Industry keyword hints."},{"name":"company_headcount","type":"object","required":false,"description":"Headcount range.","shape":{"min":"number|string|null","max":"number|string|null"}},{"name":"founded_year","type":"object","required":false,"description":"Founded year range.","shape":{"min":"number|string|null","max":"number|string|null"}},{"name":"funding","type":"object","required":false,"description":"Funding constraints.","shape":{"stages":"string[]","min_amount":"number|string|null","max_amount":"number|string|null","date_range":"{ start: string|null, end: string|null }"}},{"name":"revenue","type":"object","required":false,"description":"Annual revenue range.","shape":{"min":"number|string|null","max":"number|string|null"}},{"name":"headcount_growth","type":"object","required":false,"description":"Headcount growth percent over time.","shape":{"period":"monthly|quarterly|yearly","min_percent":"number|string|null","max_percent":"number|string|null"}},{"name":"hiring_growth","type":"object","required":false,"description":"Hiring growth percent over time.","shape":{"period":"monthly|quarterly|yearly","min_percent":"number|string|null","max_percent":"number|string|null"}},{"name":"job_postings","type":"object","required":false,"description":"Active job postings range.","shape":{"min":"number|string|null","max":"number|string|null"}},{"name":"website_traffic","type":"object","required":false,"description":"Monthly website visits range.","shape":{"min":"number|string|null","max":"number|string|null"}},{"name":"technologies","type":"string[]","required":false,"description":"Technologies used."},{"name":"job_keyword_hints","type":"string[]","required":false,"description":"Job keyword hints for evidence."}]},{"name":"CompanySearchPreviewCompany","description":"Company row returned by company search. Preview mode returns the base fields; detailed mode adds the richer fields below.","fields":[{"name":"id","type":"uuid|string","required":false,"description":"Company id."},{"name":"name","type":"string","required":false,"description":"Company name."},{"name":"description","type":"string","required":false,"description":"Short description."},{"name":"industries","type":"string[]","required":false,"description":"Industry labels."},{"name":"company_tags","type":"string[]","required":false,"description":"Company tags."},{"name":"location","type":"string","required":false,"description":"HQ location."},{"name":"country","type":"string","required":false,"description":"HQ country."},{"name":"employee_count","type":"number|null","required":false,"description":"Employee count."},{"name":"active_job_postings_count","type":"number|null","required":false,"description":"Active job postings."},{"name":"canonical_name","type":"string|null","required":false,"description":"Canonical company name (detailed mode)."},{"name":"normalized_name","type":"string|null","required":false,"description":"Normalized company name key (detailed mode)."},{"name":"website_url","type":"string|null","required":false,"description":"Canonical company website (detailed mode)."},{"name":"linkedin_company_url","type":"string|null","required":false,"description":"LinkedIn company URL (detailed mode)."},{"name":"size_range","type":"string|null","required":false,"description":"Employee size bucket (detailed mode)."},{"name":"revenue_usd","type":"number|null","required":false,"description":"Revenue estimate in USD (detailed mode)."},{"name":"is_b2b","type":"boolean|null","required":false,"description":"Whether the company is classified as B2B (detailed mode)."},{"name":"founded_year","type":"number|string|null","required":false,"description":"Founded year when available."},{"name":"company_type","type":"string[]","required":false,"description":"Company type labels (detailed mode)."},{"name":"company_stage","type":"string[]","required":false,"description":"Stage labels (detailed mode)."},{"name":"company_sub_stage","type":"string[]","required":false,"description":"Sub-stage labels (detailed mode)."},{"name":"company_status","type":"string[]","required":false,"description":"Status labels (detailed mode)."},{"name":"technologies","type":"string[]","required":false,"description":"Technology keywords (detailed mode)."},{"name":"office_locations","type":"string[]","required":false,"description":"Known office locations (detailed mode)."},{"name":"last_funding_round_name","type":"string|null","required":false,"description":"Most recent funding round name."},{"name":"last_funding_round_type","type":"string|null","required":false,"description":"Most recent funding round type."},{"name":"last_funding_round_amount_raised","type":"number|null","required":false,"description":"Most recent funding amount raised."},{"name":"last_funding_round_announced_date","type":"string|null","required":false,"description":"Most recent funding round announcement date."},{"name":"match_evidence","type":"object","required":false,"description":"Structured market/hiring/preference evidence generated during company matching."},{"name":"evidence_text","type":"string","required":false,"description":"Optional doc-grounded evidence text when include_evidence_text=true."}]},{"name":"CompanySearchPreviewResponse","description":"Response payload for company search previews. companies[] rows vary by result_mode.","fields":[{"name":"success","type":"boolean","required":true,"description":"Whether the preview succeeded."},{"name":"companies","type":"CompanySearchPreviewCompany[]","required":true,"description":"Company results."},{"name":"pagination","type":"Pagination","required":true,"description":"Pagination details."},{"name":"filters","type":"CompanySearchFilters","required":false,"description":"Resolved filters."},{"name":"annotationPayload","type":"object","required":false,"description":"Search id + preview metadata."}]},{"name":"ErrorResponse","description":"Standard error payload.","fields":[{"name":"error","type":"string","required":true,"description":"Error message."},{"name":"code","type":"string","required":false,"description":"Error code."},{"name":"upgrade_url","type":"string","required":false,"description":"Upgrade URL for paid access."},{"name":"owner","type":"object","required":false,"description":"Account owner details when access is restricted.","shape":{"id":"uuid","name":"string","email":"string"}}]}]},"examples":[{"title":"Credit summary","category":"credits","description":"Inspect the shared account credit pool, current API key usage, active search rate card, and billing semantics.","request":{"range":"30d"},"response":{"success":true,"owner_user_id":"owner_user_123","credit_pool_scope":"account_owner","range":{"key":"last_30_days","start":"2026-03-05T00:00:00.000Z","end":"2026-04-03T23:59:59.999Z"},"current_api_key":{"id":"api_key_123","name":"Production sourcing worker","key_prefix":"carl_abcd1234","scopes":["search","enrich","profiles-read","communications"],"status":"active","last_used_at":"2026-04-03T18:12:55.000Z","created_at":"2026-03-15T10:00:00.000Z"},"current_key_usage":{"credits_used":184,"units":184,"preview_searches":72,"full_searches":98,"linkedin_lookups":14},"account_credit_pool":{"totals":{"units":421,"snapshot_credits":421,"current_credits":421,"snapshot_cost":126.3},"breakdown":[{"action_type":"search","action_subtype":"results","units":210,"snapshot_credits":210,"current_credits":210,"snapshot_cost":63,"applied_rule":{"action_type":"search","action_subtype":"results","units_per_credit":1,"credits_per_unit":1,"effective_at":"2026-03-01T00:00:00.000Z","expires_at":null,"description":"Full search credits"}}]},"rate_card":{"conversion_rules":[{"action_type":"search","action_subtype":"preview","units_per_credit":2,"credits_per_unit":0.5,"effective_at":"2026-03-01T00:00:00.000Z","expires_at":null,"description":"Preview search credits"},{"action_type":"search","action_subtype":"results","units_per_credit":1,"credits_per_unit":1,"effective_at":"2026-03-01T00:00:00.000Z","expires_at":null,"description":"Full search credits"}],"cost_rates":[{"action_type":"search","action_subtype":"preview","model":null,"cost_per_unit":0.15,"currency":"usd","effective_at":"2026-03-01T00:00:00.000Z","expires_at":null,"description":"Preview search internal cost"}]},"billing_semantics":[{"operation":"people_search_results","endpoint":"POST /api/v1/search/people","scopes":["search"],"billing_mode":"credit_event","action_type":"search","action_subtype":"results","note":"Creates a full-search credit usage event."},{"operation":"people_search_enrich","endpoint":"POST /api/v1/search/people/enrich","scopes":["enrich"],"billing_mode":"updates_existing_search_event","action_type":"search","action_subtype":"results","note":"Enrich updates the original full-search activity record and does not create a second standalone credit usage event."}],"notes":["All API usage draws from the same account credit pool as in-app searches.","current_key_usage reflects recorded credit events for this API key within the selected range."]},"curl":"curl -X GET \"https://api.supercarl.ai/api/v1/credits?range=30d\" \\\n  -H \"X-API-Key: <YOUR_API_KEY>\""},{"title":"Communication capabilities","category":"communications","description":"Inspect which outbound channels are currently available for the acting user and target.","request":{"x_profile_url":"https://x.com/benkeighran"},"response":{"owner_user_id":"owner_user_123","acting_user_id":"seat_user_456","is_delegate":true,"resolved_target":{"id":"user_123","name":"Sample Person","x_profile_url":"https://x.com/benkeighran","recipient_email":"sample@example.com"},"channels":[{"channel":"x_send_message","can_send":true,"reason_code":"ready","reason":"The acting user has an X browser session and the target resolves to an X profile.","action_required":null,"fallback_channels":["gmail_send"]}],"supercarl":{"direct_message_available":false,"invite_available":false,"referral_available":true,"candidate_connectors":[{"id":"connector_123","name":"Warm Connector","action_mode":"supercarl_referral","path_score":87}]}},"curl":"curl -X POST https://api.supercarl.ai/api/v1/communications/capabilities \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"x_profile_url\": \"https://x.com/benkeighran\"\n  }'"},{"title":"LinkedIn durable draft","category":"communications","description":"Save an MCP-session outreach draft without sending. Link macros are expanded before the draft is returned and stored for review.","request":{"mode":"draft","channel":"linkedin_send_message","agent_session_id":"agent_session_uuid","linkedin_profile_url":"https://www.linkedin.com/in/target-person/","message":"Worth connecting on this? [JoinLink]"},"response":{"id":"communication_123","channel":"linkedin_send_message","status":"completed","dry_run":true,"result":{"outcome":"drafted","draft":{"message":"Worth connecting on this? https://supercarl.ai/join/mdale/o/abc123","assignment_id":"assignment_uuid","assignment_target_id":"assignment_target_uuid"}}},"curl":"curl -X POST https://api.supercarl.ai/api/v1/communications \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"mode\": \"draft\",\n    \"channel\": \"linkedin_send_message\",\n    \"agent_session_id\": \"agent_session_uuid\",\n    \"linkedin_profile_url\": \"https://www.linkedin.com/in/target-person/\",\n    \"message\": \"Worth connecting on this? [JoinLink]\"\n  }'"},{"title":"X dry-run send","category":"communications","description":"Create a dry-run X communication record and inspect it later through the status endpoint or SSE stream.","request":{"channel":"x_send_message","x_profile_url":"https://x.com/benkeighran","message":"Quick note from Super Carl.","dry_run":true},"response":{"id":"communication_123","channel":"x_send_message","status":"completed","result":{"outcome":"dry_run"},"task":null,"reasoning_lookup":{"context_type":null,"context_id":null,"task_id":null,"entry_id":null},"events":[{"sequence":1,"event_type":"validated","status":"queued"},{"sequence":3,"event_type":"completed","status":"completed","message":"Dry run completed without sending."}],"artifacts":[],"webhook":{"url":null,"delivery_attempts":0,"last_attempt_at":null,"last_status":null,"last_error":null}},"curl":"curl -X POST https://api.supercarl.ai/api/v1/communications \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"channel\": \"x_send_message\",\n    \"x_profile_url\": \"https://x.com/benkeighran\",\n    \"message\": \"Quick note from Super Carl.\",\n    \"dry_run\": true\n  }'"},{"title":"LinkedIn lookup","category":"people-search","description":"Lookup a profile by LinkedIn username or full LinkedIn profile URL.","request":{"linkedin_profile_url":"https://www.linkedin.com/in/reidhoffman/"},"response":{"success":true,"search_id":null,"enrichable":false,"users":[{"id":"user_123","name":"Sample Person","linkedin_url":"https://www.linkedin.com/in/reidhoffman","supercarl_url":"https://supercarl.ai/profile/reidhoffman"}],"search_metadata":{"strategy":"linkedin_lookup","lookup":{"created":false,"profile_index_status":"indexed","enrichment":{"status":"skipped"}}}},"curl":"curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"linkedin_profile_url\": \"https://www.linkedin.com/in/reidhoffman/\"\n  }'"},{"title":"Profile chunks (cached)","category":"profiles","description":"Fetch cached profile chunks without refreshing.","request":null,"response":{"success":true,"user_id":"user_123","chunks":[{"id":"chunk_1","chunk_type":"experience","chunk_text":"Head of Growth at ExampleCo Description: Built outbound and lifecycle growth programs.","chunk_metadata":{"title":"Head of Growth","company":"ExampleCo","start_year":2022,"start_month":1,"end_year":null,"end_month":null,"is_current":true,"date_range":"Jan 2022 - Present","tenure_months":51,"company_id":"company_123"}},{"id":"chunk_2","chunk_type":"post","chunk_text":"Hiring GTM operators who know how to build repeatable pipeline in healthcare SaaS.","chunk_metadata":{"post_url":"https://www.linkedin.com/feed/update/urn:li:activity:123","post_date":"2026-03-01","post_platform":"linkedin"}}]},"curl":"curl -X GET https://api.supercarl.ai/api/v1/profiles/user_123/chunks?posts_limit=10 \\\n  -H \"X-API-Key: <YOUR_API_KEY>\""},{"title":"Profile text","category":"profiles","description":"Fetch profile text ready for LLM embeddings.","request":null,"response":{"success":true,"user_id":"user_123","text":{"mode":"full","text":"Headline: Growth leader at ExampleCo\nSummary: ...","posts_included":5,"companies_included":2}},"curl":"curl -X GET https://api.supercarl.ai/api/v1/profiles/user_123/text?mode=full&posts_limit=5 \\\n  -H \"X-API-Key: <YOUR_API_KEY>\""},{"title":"Description search (auto-translated)","category":"people-search","description":"Run a natural language description that is auto-translated into AdvancedFilters.","request":{"description":"VP of Sales at mid-size companies in San Francisco","limit":10,"offset":0},"response":{"success":true,"search_id":"8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4","enrichable":true,"users":[{"id":"user_123","name":"Sample Person","headline":"VP of Sales at ExampleCo","location":"San Francisco Bay Area","linkedin_url":"https://linkedin.com/in/example","mutual_connections_count":6,"social_proximity_score":58,"social_proximity_band":"warm","social_proximity_tier":"Warm","best_intro_path_type":"supercarl_referral","score_version":7}],"pagination":{"limit":10,"offset":0,"total":125,"hasMore":true},"search_metadata":{"search_backend":"es","description_snapshot":"VP of Sales at mid-size companies in San Francisco","filters":{"summary":"VP of Sales in San Francisco at mid-size companies","advanced":{"job_titles":{"include":["VP of Sales"],"exclude":[],"mode":"must","exact":false,"current_only":true},"locations":{"include":["San Francisco Bay Area"],"exclude":[],"radius_miles":50,"strict":false,"scope":"current"}}}}},"curl":"curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"description\": \"VP of Sales at mid-size companies in San Francisco\",\n    \"limit\": 10,\n    \"offset\": 0\n  }'"},{"title":"Full people search","category":"people-search","description":"Run a full search with explicit AdvancedFilters and inline evidence_text for evaluator-friendly matching context.","request":{"description":"Head of Growth in New York","limit":10,"offset":0,"include_evidence_text":true,"evidence_text_mode":"full","evidence_posts_limit":5,"filters":{"job_titles":{"include":["Head of Growth"],"exclude":[],"mode":"must","exact":false,"current_only":true},"locations":{"include":["New York, NY"],"exclude":[],"radius_miles":25,"strict":false,"scope":"current"}}},"response":{"success":true,"search_id":"8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4","enrichable":true,"users":[{"id":"user_123","name":"Sample Person","headline":"Growth lead at ExampleCo","location":"New York, NY","linkedin_url":"https://linkedin.com/in/example","years_experience_months":121,"current_role_tenure_months":39,"average_role_tenure_months":34,"evidence_text":"Profile:\nHeadline: Growth lead at ExampleCo\n\nExperience:\nHead of Growth at ExampleCo\nDates: Jan 2023 - Present\nCompany details: Size: 201-500; Industries: SaaS, Marketing Tech\nVP Growth at EarlierCo\nDates: Feb 2020 - Dec 2022\nCompany details: Size: 51-200; Industries: Healthcare, SaaS\n\nRecent posts:\nPost 1 | 2026-03-01: Building repeatable pipeline with healthcare revenue teams.","evidence_text_mode":"full","evidence_posts_included":5,"evidence_companies_included":2,"has_previous_correspondence":true,"previous_correspondence_count":3,"previous_correspondence_last_sent_at":"2026-04-01T12:00:00.000Z","mutual_connections_count":3,"social_proximity_score":41,"social_proximity_band":"some_signal","social_proximity_tier":"Some signal","best_intro_path_type":"manual_linkedin_intro","score_version":7}],"pagination":{"limit":10,"offset":0,"total":125,"hasMore":true},"search_metadata":{"search_backend":"es","description_snapshot":"Head of Growth in New York","filters":{"summary":"Head of Growth in New York","advanced":{"job_titles":{"include":["Head of Growth"],"exclude":[],"mode":"must","exact":false,"current_only":true},"locations":{"include":["New York, NY"],"exclude":[],"radius_miles":25,"strict":false,"scope":"current"}}}}},"curl":"curl -X POST https://api.supercarl.ai/api/v1/search/people \\\n  -H \"X-API-Key: <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"description\": \"Head of Growth in New York\",\n    \"limit\": 10,\n    \"offset\": 0,\n    \"include_evidence_text\": true,\n    \"evidence_text_mode\": \"full\",\n    \"evidence_posts_limit\": 5,\n    \"filters\": {\n      \"job_titles\": {\n        \"include\": [\"Head of Growth\"],\n        \"exclude\": [],\n        \"mode\": \"must\",\n        \"exact\": false,\n        \"current_only\": true\n      },\n      \"locations\": {\n        \"include\": [\"New York, NY\"],\n        \"exclude\": [],\n        \"radius_miles\": 25,\n        \"strict\": false,\n        \"scope\": \"current\"\n      }\n    }\n  }'"},{"title":"Social proximity detail","category":"social-proximity","description":"Inspect authenticated score breakdown, evidence, connector paths, and LinkedIn mutual research status for one target.","request":null,"response":{"baseline":{"score":58,"tier":"Warm","tier_key":"warm","band":"warm","evidence":[{"label":"Connected on LinkedIn","category":"direct_relationship","source":"linkedin"},{"label":"Very high LinkedIn mutual overlap","category":"mutual_connections","source":"linkedin"}]},"researched":{"score":63,"tier":"Warm","tier_key":"warm","band":"warm","evidence":[{"label":"Connected on LinkedIn","category":"direct_relationship","source":"linkedin"},{"label":"Very high LinkedIn mutual overlap","category":"mutual_connections","source":"linkedin"},{"label":"Many shared SuperCarl mutuals","category":"mutual_connections","source":"supercarl"}]},"evidence":[{"label":"Connected on LinkedIn","category":"direct_relationship","source":"linkedin"},{"label":"Very high LinkedIn mutual overlap","category":"mutual_connections","source":"linkedin"}],"connectors_supercarl":[{"id":"user_456","name":"Mutual Connector","connector_type":"supercarl","action_mode":"supercarl_referral","path_score":67.2,"social_proximity_score":61,"social_proximity_band":"warm","social_proximity_tier":"Warm","viewer_social_proximity_score":61,"target_social_proximity_score":76,"evidence_highlights":["Connected on SuperCarl"],"intersection_highlights":["Very high LinkedIn mutual overlap"]}],"connectors_linkedin_manual":[],"research_status":{"status":"completed","current_start_index":0,"page_size":10,"pages_fetched":3,"profiles_discovered":17,"has_more":false,"exhausted":true,"next_page_number":4,"browser_job_id":null,"reasoning_context_type":"social_proximity_research","reasoning_context_id":"user_123","updated_at":"2026-03-17T12:00:00.000Z","last_error":null,"failure_reason":null,"recovery_action":null,"requires_linkedin_session":false,"message":"LinkedIn mutual research is up to date."},"score_version":7},"curl":"curl -X GET https://api.supercarl.ai/users/<TARGET_USER_ID>/social-proximity \\\n  -H \"Authorization: Bearer <JWT_TOKEN>\""},{"title":"Preview search","category":"people-search","description":"Run a lightweight preview search (auto-translated description, not enrichable).","request":{"description":"VP of Sales","limit":5,"offset":0},"response":{"success":true,"search_id":null,"enrichable":false,"users":[],"pagination":{"limit":5,"offset":0,"total":40,"hasMore":true}}},{"title":"Enrich search results","category":"people-search","description":"Re-run a previous search_id and enrich the current page of results. Add target_user_id if you only want one user.","request":{"search_id":"8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4","limit":10,"offset":0},"response":{"success":true,"search_id":"8c7fbf1a-5db5-4b15-9c76-6f4b3be3f7f4","enrichment":{"duration_ms":842,"mode":"page","target_user_id":null},"users":[{"id":"user_123","name":"Sample Person","match_reasons":["Matched title: Head of Growth","Location: New York"]}]}},{"title":"Company search preview","category":"companies","description":"Search companies in detailed mode with inline evidence_text for downstream ranking or eval workflows.","request":{"query":"AI infrastructure companies in California with 200+ employees hiring SREs","result_mode":"detailed","include_evidence_text":true,"evidence_post_limit":2,"filters":{"company_headcount":{"min":"200","max":null},"funding":{"min_amount":"5M","max_amount":null},"revenue":{"min":"25M","max":"1B"}},"preview_limit":10},"response":{"success":true,"companies":[{"id":"company_123","name":"Example GPU Systems","canonical_name":"Example GPU Systems","website_url":"https://examplegpu.com","linkedin_company_url":"https://www.linkedin.com/company/examplegpu","industries":["AI Infrastructure"],"company_tags":["MLOps","Cloud"],"location":"San Francisco, CA","employee_count":320,"active_job_postings_count":12,"match_evidence":{"matching_job_titles":["Site Reliability Engineer","Platform Engineer"]},"evidence_text":"Company: Example GPU Systems\nDescription: Builds AI infrastructure for enterprise workloads.\nTechnologies: CUDA, Kubernetes\nRecent posts:\nPost 1 | 2026-03-01: Hiring SREs to scale GPU clusters."}],"pagination":{"limit":10,"offset":0,"total":42,"hasMore":true},"filters":{"location":{"country":"United States","state":"California"},"company_headcount":{"min":200,"max":null},"job_keyword_hints":["SRE"]},"annotationPayload":{"preview":{"search_id":"company_search_abc","total_count":42}},"company_resolution":{"intent":"company_set","status":"set","can_bind_people_search":true,"recommended_next_action":"use_search_id_as_company_set"}}},{"title":"People search joined to company search","category":"companies","description":"Use a company search_id as a people-search filter (include or exclude).","request":{"description":"Find engineering leaders at those companies","filters":{"companies":{"include_company_search_id":"company_search_abc"}}},"response":{"success":true,"search_id":"people_search_xyz","users":[],"pagination":{"limit":20,"offset":0,"total":120,"hasMore":true},"search_metadata":{"company_search_filters":{"include":{"search_id":"company_search_abc","applied":true,"capped":false,"dropped":false,"total":4200,"limit":10000}}}}},{"title":"Profile snapshot","category":"profiles","description":"Fetch a profile snapshot by user id.","request":null,"response":{"id":"user_123","name":"Sample Person","username":"sampleperson","bio":"Growth leader.","location":"New York, NY","linkedin_url":"https://linkedin.com/in/example"}}],"social_proximity":{"version":7,"overview":"Social proximity is a requester-relative relationship score. Public people-search responses can expose summary relationship fields and opt-in structured relationship detail; social-proximity detail surfaces expose score breakdowns, evidence, connector paths, and LinkedIn mutual-research status.","api_surfaces":[{"name":"People search summary fields","auth_mode":"api_key","auth_header":"X-API-Key","endpoints":["POST /api/v1/search/people","POST /api/v1/search/people/preview","POST /api/v1/search/people/enrich"],"model":"Person","note":"These values are relative to the searching account owner or delegate_user_id. Existing scalar fields remain available when hydrated. Request relationship_detail for the structured relationship object used by MCP/API agents.","request_parameters":[{"name":"relationship_detail","type":"none|summary|intro_paths","required":false,"description":"Opt-in relationship payload. summary adds relationship.social_proximity, relationship.mutual_connections, and best_intro_path_type. intro_paths also adds relationship.social_map.entries[] as the unified path list, ranked confirmed connector path detail, research_status, possible_intro_status, and possible_intro_paths for first-degree worked-with overlap \"may know\" paths. Omit to preserve the legacy lean/default payload."},{"name":"intro_path_limit","type":"number","required":false,"description":"Maximum confirmed-mutual intro paths returned when relationship_detail=intro_paths. Default 3, server max 20. This does not cap the async scored mutual-connector pool; relationship.intro_paths_status.ranking_status, ranking_pending, and ranking_queue_* fields tell you whether confirmed path order is final."},{"name":"possible_intro_limit","type":"number","required":false,"description":"Maximum first-degree worked-with overlap paths returned in relationship.possible_intro_paths and relationship.social_map path_type=\"experience_intersection\". Default 20, server max 100."},{"name":"possible_intro_offset","type":"number","required":false,"description":"Zero-based offset into first-degree worked-with overlap paths for pagination."},{"name":"mutual_connection_limit","type":"number","required":false,"description":"Maximum relationship.mutual_connections.preview entries returned for this page. Default 50 on direct/detail calls, server max 500."},{"name":"mutual_connection_offset","type":"number","required":false,"description":"Zero-based offset into relationship.mutual_connections.preview for paging persisted/researched mutual connectors."}],"fields":[{"name":"social_proximity_score","type":"number|null","required":false,"description":"0-100 requester-relative score used for ranking and reachability summaries. This mirrors search_score: researched_score when fresh LinkedIn mutual research exists, otherwise baseline_score."},{"name":"social_proximity_band","type":"very_warm|warm|some_signal|weak|null","required":false,"description":"Machine-friendly band derived from social_proximity_score."},{"name":"social_proximity_tier","type":"string|null","required":false,"description":"Human label for social_proximity_band (Very warm, Warm, Some signal, Weak)."},{"name":"best_intro_path_type","type":"supercarl_referral|manual_linkedin_intro|null","required":false,"description":"Best intro mode inferred from mutual connector availability. SuperCarl referral is preferred when a SuperCarl mutual path exists."},{"name":"score_version","type":"number|null","required":false,"description":"Scoring config version. Current version: 7."},{"name":"mutual_connections_count","type":"number","required":false,"description":"Count of surfaced mutual connectors on the result row."},{"name":"mutual_connections","type":"PersonSummary[]","required":false,"description":"Subset of mutual connectors shown inline on search results."},{"name":"relationship","type":"RelationshipDetail|null","required":false,"description":"Structured requester-relative relationship payload returned when relationship_detail is summary or intro_paths."}]},{"name":"API-key social-proximity research","auth_mode":"api_key","auth_header":"X-API-Key","endpoints":["POST /api/v1/relationships/social-proximity/research","GET /api/v1/relationships/social-proximity/research/status"],"model":"SocialProximityResearchResponse","note":"Explicitly starts LinkedIn mutual research for one target when recent cached research is unavailable. The status endpoint is read-only and never starts or refreshes research. Search/read endpoints never auto-start research.","request_parameters":[{"name":"target_user_id","type":"string","required":true,"description":"Target Super Carl user id."},{"name":"delegate_user_id","type":"string","required":false,"description":"Permitted teammate user id to act as."},{"name":"page_limit","type":"number","required":false,"description":"Optional LinkedIn mutual pages to request."},{"name":"page_size","type":"number","required":false,"description":"Optional LinkedIn mutual page size."},{"name":"reset","type":"boolean","required":false,"description":"Request restart for previous/stale research; recent completed research is still reused within the server cooldown."},{"name":"intro_path_limit","type":"number","required":false,"description":"Maximum returned confirmed-mutual intro paths, default 3 and max 20."},{"name":"possible_intro_limit","type":"number","required":false,"description":"Maximum first-degree worked-with overlap paths, default 20 and max 100."},{"name":"possible_intro_offset","type":"number","required":false,"description":"Zero-based offset into first-degree worked-with overlap paths."},{"name":"mutual_connection_limit","type":"number","required":false,"description":"Maximum relationship.mutual_connections.preview entries returned for this page, default 50 and max 500."},{"name":"mutual_connection_offset","type":"number","required":false,"description":"Zero-based offset into the persisted mutual-connection list."}],"fields":[{"name":"relationship","type":"RelationshipDetail|null","required":false,"description":"Current structured relationship and intro-path payload."},{"name":"research","type":"object","required":true,"description":"Start/continue result from the LinkedIn mutual research workflow."},{"name":"detail.research_status","type":"SocialProximityResearchStatus","required":false,"description":"Current research status and recovery guidance."}]},{"name":"Authenticated summaries endpoint","auth_mode":"jwt","auth_header":"Authorization: Bearer <token>","endpoints":["POST /users/social-proximity/summaries"],"model":"SocialProximitySummaryResponse","note":"Returns baseline/search scores, evidence, component metadata, and direct-relationship timestamps for each requested target.","fields":[{"name":"summaries[].summary.search_score","type":"number","required":true,"description":"Primary score used by search ranking and banding."},{"name":"summaries[].summary.metadata.components","type":"SocialProximityComponents","required":false,"description":"Component-level score breakdown used to produce the total."},{"name":"summaries[].summary.metadata.mutual_connections","type":"object","required":false,"description":"Mutual-connection counts, overlap ratios, research readiness, and baseline-vs-researched metadata."},{"name":"summaries[].summary.metadata.direct_relationship","type":"object","required":false,"description":"Normalized direct-relationship timestamps (LinkedIn and SuperCarl) used for evidence and recency bonus handling."},{"name":"summaries[].summary.evidence","type":"SocialProximityEvidence[]","required":false,"description":"Deduped evidence list sorted by strongest score contribution and recency."}]},{"name":"Authenticated detail and research endpoints","auth_mode":"jwt","auth_header":"Authorization: Bearer <token>","endpoints":["GET /users/:targetUserId/social-proximity","POST /users/:targetUserId/social-proximity/research"],"model":"SocialProximityDetail","note":"Returns connector path scoring, researched score variants, evidence highlights, and the current LinkedIn mutual-research workflow state.","fields":[{"name":"baseline","type":"SocialProximityScoreCard","required":true,"description":"Baseline score card using local graph evidence and missing-research fallback rules."},{"name":"researched","type":"SocialProximityScoreCard|null","required":false,"description":"Refined score card after fresh LinkedIn mutual research is available."},{"name":"connectors_supercarl","type":"SocialProximityConnector[]","required":false,"description":"Mutual connectors who can support a SuperCarl referral path."},{"name":"connectors_linkedin_manual","type":"SocialProximityConnector[]","required":false,"description":"Mutual connectors that require a manual LinkedIn intro path."},{"name":"research_status","type":"SocialProximityResearchStatus","required":true,"description":"Current LinkedIn mutual-research state and recovery guidance."}]}],"score_resolution":{"clamp_range":"All totals are clamped to the inclusive range 0-100.","baseline_formula":"baseline_score = direct_relationship + profile_overlap + reciprocal_communication + public_activity + mutual_connections_baseline + cross_network","researched_formula":"researched_score = direct_relationship + profile_overlap + reciprocal_communication + public_activity + mutual_connections_researched + cross_network","search_formula":"search_score = researched_score ?? baseline_score","note":"Search responses expose search_score only. The authenticated detail surface exposes baseline and researched score cards separately."},"tiers":[{"min_score":75,"tier":"very_warm","band":"very_warm","label":"Very warm"},{"min_score":50,"tier":"warm","band":"warm","label":"Warm"},{"min_score":25,"tier":"some_signal","band":"some_signal","label":"Some signal"},{"min_score":0,"tier":"weak","band":"weak","label":"Weak"}],"components":[{"key":"direct_relationship","label":"Direct relationship","max_points":35,"evidence_category":"direct_relationship","component_fields":["metadata.components.direct_relationship","metadata.direct_relationship","evidence[]"],"description":"Scores the strongest direct connection source only, then adds a recency bonus when that connection or verification is recent.","scoring":{"strongest_source_only":true,"base_by_source":[{"source":"supercarl","evidence_label":"Connected on SuperCarl","points":24},{"source":"linkedin","evidence_label":"Connected on LinkedIn","points":17},{"source":"gmail","evidence_label":"In your address book","points":15},{"source":"x","evidence_label":"Connected through X","points":10},{"source":"instagram","evidence_label":"Connected on Instagram","points":10}],"recency_bonus":{"within_30_days":6,"within_90_days":3}},"evidence_mapping":[{"label":"Connected on SuperCarl","when":"Strongest direct source = supercarl","source":"supercarl"},{"label":"Connected on LinkedIn","when":"Strongest direct source = linkedin","source":"linkedin"},{"label":"In your address book","when":"Strongest direct source = gmail","source":"gmail"},{"label":"Connected through X","when":"Strongest direct source = x","source":"x"},{"label":"Connected on Instagram","when":"Strongest direct source = instagram","source":"instagram"},{"label":"Recent connection or verification","when":"Strongest direct source was connected or verified within 90 days","source":null}]},{"key":"profile_overlap","label":"Profile overlap","max_points":30,"evidence_category":"profile_overlap","component_fields":["metadata.components.profile_overlap","evidence[]"],"description":"Scores shared professional context such as current company, prior company history, timeline overlap, school background, and geography.","scoring":{"same_small_company":18,"same_large_company_with_domain_or_leadership":16,"same_large_company_weak":8,"prior_company":8,"shared_current_industry":{"points":2,"max_company_industry_count":5,"excluded_industry_labels":["Software Development","IT Services and IT Consulting","Technology, Information and Internet","Financial Services","Business Consulting and Services","Advertising Services","Venture Capital and Private Equity Principals","Information Technology & Services","Investment Management","Higher Education","Human Resources Services","Computer and Network Security","Hospitals and Health Care","Real Estate","Retail","Non-profit Organizations","Technology","Staffing and Recruiting","Entertainment","Retail Apparel and Fashion","Information and Internet","Marketing Services","Professional Training and Coaching","Entertainment Providers","Government Administration"]},"timeline_overlap_tiers":[{"minMonths":36,"score":9},{"minMonths":12,"score":7},{"minMonths":1,"score":5}],"shared_company_timeline_bonus_tiers":[{"minMonths":36,"score":10},{"minMonths":12,"score":8},{"minMonths":1,"score":6}],"school":4,"geography":3,"small_company_exec_bonus":3},"evidence_mapping":[{"label":"Same current company (...)","when":"Current company matches","source":null},{"label":"Same current company (...) with domain or leadership overlap","when":"Current company matches and a stronger large-company corroboration signal exists","source":null},{"label":"Both hold leadership roles at the same company","when":"Small-company exec bonus applied","source":null},{"label":"Shared current industry (...)","when":"Specific current industry overlap applied","source":null},{"label":"Shared company history at ...","when":"Prior shared company applied","source":null},{"label":"Overlapping time at ...","when":"Timeline overlap tiers applied","source":null},{"label":"Shared school background ...","when":"School overlap applied","source":null},{"label":"Same city","when":"Top geography overlap is same_city","source":null},{"label":"Similar geography","when":"Geography overlap applied without same-city match","source":null}]},{"key":"reciprocal_communication","label":"Reciprocal communication","max_points":15,"evidence_category":"reciprocal_communication","component_fields":["metadata.components.reciprocal_communication","evidence[]"],"description":"Scores direct message exchange on SuperCarl. Reciprocal conversations score materially higher than one-way outreach.","scoring":{"max_points":15,"formula_notes":["Reciprocal message exchange uses a higher base, additional volume credit, and a balance bonus.","One-way outreach is capped lower."]},"evidence_mapping":[{"label":"Exchanged messages on SuperCarl","when":"Both users have sent messages to each other","source":"supercarl"},{"label":"One-way SuperCarl outreach","when":"Only one user has messaged the other","source":"supercarl"}]},{"key":"public_activity","label":"Public activity","max_points":20,"evidence_category":"public_activity","component_fields":["metadata.components.public_activity","evidence[]"],"description":"Scores post-level interactions such as likes, comments, reposts, and mentions, with decay for older activity and a multiplier for mutual activity.","scoring":{"max_points":20,"weights":{"like":2,"reaction":2,"comment":4,"reply":5,"repost":5,"mention":5},"mutual_multiplier":3},"evidence_mapping":[{"label":"Mutual social activity across posts","when":"Both users have public interactions toward each other","source":"linkedin_or_activity_source"},{"label":"One-way likes or reactions","when":"Strongest public activity is a like or reaction","source":null},{"label":"One-way comments on posts","when":"Strongest public activity is a comment","source":null},{"label":"Reposted social content","when":"Strongest public activity is a repost","source":null},{"label":"Mentioned in social activity","when":"Strongest public activity is a mention","source":null}]},{"key":"mutual_connections","label":"Mutual connections","max_points":20,"evidence_category":"mutual_connections","component_fields":["metadata.components.mutual_connections_baseline","metadata.components.mutual_connections_researched","metadata.components.mutual_connections_search","metadata.mutual_connections","evidence[]"],"description":"Scores shared connector overlap from LinkedIn and SuperCarl. When fresh LinkedIn mutual research is missing, a baseline floor is used so known graph overlap still contributes to search ranking.","scoring":{"max_points":20,"missing_linkedin_research_baseline":10,"known_graph_evidence_label":"Some graph overlap, LinkedIn mutual not yet researched","missing_research_label":"LinkedIn mutual overlap has not been fully researched yet","linkedin_score_tiers":[{"minOverlapRatio":0.02,"minMutualCount":10,"score":20,"evidenceLabel":"Very high LinkedIn mutual overlap"},{"minOverlapRatio":0.01,"minMutualCount":10,"score":15,"evidenceLabel":"Strong LinkedIn mutual overlap"},{"minOverlapRatio":0.002,"minMutualCount":5,"score":10,"evidenceLabel":"Meaningful LinkedIn mutual overlap"},{"minOverlapRatio":0.001,"minMutualCount":10,"score":5,"evidenceLabel":"Some LinkedIn mutual overlap"},{"minOverlapRatio":0,"minMutualCount":3,"score":2,"evidenceLabel":"A few LinkedIn mutuals"},{"minOverlapRatio":0,"minMutualCount":1,"score":1,"evidenceLabel":"At least one LinkedIn mutual"}],"supercarl_bonus_tiers":[{"minCount":10,"score":5,"evidenceLabel":"Many shared SuperCarl mutuals"},{"minCount":5,"score":3,"evidenceLabel":"Several shared SuperCarl mutuals"},{"minCount":2,"score":2,"evidenceLabel":"A few shared SuperCarl mutuals"},{"minCount":1,"score":1,"evidenceLabel":"Shared SuperCarl mutuals"}]},"evidence_mapping":[{"label":"Some graph overlap, LinkedIn mutual not yet researched","when":"Local graph overlap exists but fresh LinkedIn mutual research is not ready","source":"linkedin"},{"label":"Very high LinkedIn mutual overlap","when":"Researched LinkedIn overlap meets minMutualCount=10 and minOverlapRatio=0.02","source":"linkedin"},{"label":"Strong LinkedIn mutual overlap","when":"Researched LinkedIn overlap meets minMutualCount=10 and minOverlapRatio=0.01","source":"linkedin"},{"label":"Meaningful LinkedIn mutual overlap","when":"Researched LinkedIn overlap meets minMutualCount=5 and minOverlapRatio=0.002","source":"linkedin"},{"label":"Some LinkedIn mutual overlap","when":"Researched LinkedIn overlap meets minMutualCount=10 and minOverlapRatio=0.001","source":"linkedin"},{"label":"A few LinkedIn mutuals","when":"Researched LinkedIn overlap meets minMutualCount=3 and minOverlapRatio=0","source":"linkedin"},{"label":"At least one LinkedIn mutual","when":"Researched LinkedIn overlap meets minMutualCount=1 and minOverlapRatio=0","source":"linkedin"},{"label":"Many shared SuperCarl mutuals","when":"SuperCarl mutual count >= 10","source":"supercarl"},{"label":"Several shared SuperCarl mutuals","when":"SuperCarl mutual count >= 5","source":"supercarl"},{"label":"A few shared SuperCarl mutuals","when":"SuperCarl mutual count >= 2","source":"supercarl"},{"label":"Shared SuperCarl mutuals","when":"SuperCarl mutual count >= 1","source":"supercarl"}]},{"key":"cross_network","label":"Cross-network corroboration","max_points":10,"evidence_category":"cross_network","component_fields":["metadata.components.cross_network","evidence[]"],"description":"Adds credit when the same relationship is corroborated across more than one direct network source.","scoring":{"per_additional_source":5,"max_points":10},"evidence_mapping":[{"label":"Cross-network corroboration","when":"Two or more direct relationship sources are present","source":null}]}],"evidence":{"ordering":"Evidence entries are deduped and sorted by descending score weight, then by recency.","shape":{"label":"string","category":"direct_relationship|profile_overlap|reciprocal_communication|public_activity|mutual_connections|cross_network","source":"string|null"},"categories":[{"key":"direct_relationship","description":"Strongest direct relationship source plus optional recency evidence."},{"key":"profile_overlap","description":"Shared professional, educational, and geographic context."},{"key":"reciprocal_communication","description":"Message exchange on SuperCarl."},{"key":"public_activity","description":"Likes, comments, reposts, mentions, and mutual post activity."},{"key":"mutual_connections","description":"Local and researched mutual connector overlap across LinkedIn and SuperCarl."},{"key":"cross_network","description":"Extra corroboration when multiple direct networks confirm the relationship."}]},"path_scoring":{"description":"Connector path scoring ranks confirmed mutual introduction candidates for the authenticated detail endpoints. It blends viewer->connector and connector->target social proximity, then adds an actionability bonus for SuperCarl connectors. Ranking runs asynchronously and is cached; read responses may include provisional/unranked paths until intro_paths_status.ranking_pending is false. Returned path limits do not cap the candidate pool scored for ranking; caps/timeouts and ranking_queue_* stale-queue fields are surfaced in intro_paths_status. API/MCP clients should prefer relationship.social_map.entries[] as the unified list: confirmed mutual connectors use path_type=\"confirmed_mutual\", while possible \"may know\" paths sourced from first-degree viewer connections that pass the worked_with target profile-intersection filter use path_type=\"experience_intersection\" and are not confirmed mutuals.","formula":"path_score = viewer_connector.search_score * viewerConnectorWeight + connector_target.search_score * connectorTargetWeight + optional supercarlActionabilityBonus","weights":{"viewer_connector":0.6,"connector_target":0.4},"supercarl_actionability_bonus":4,"max_points":100,"surfaced_on":["GET /users/:targetUserId/social-proximity -> connectors_supercarl[]","GET /users/:targetUserId/social-proximity -> connectors_linkedin_manual[]","POST /api/v1/search/people relationship_detail=intro_paths -> users[].relationship.social_map.entries[]","POST /api/v1/search/people relationship_detail=intro_paths -> users[].relationship.intro_paths[]","POST /api/v1/search/people relationship_detail=intro_paths -> users[].relationship.possible_intro_paths[]","POST /api/v1/relationships/social-proximity/research -> relationship.social_map.entries[]","POST /api/v1/relationships/social-proximity/research -> relationship.intro_paths[]","POST /api/v1/relationships/social-proximity/research -> relationship.possible_intro_paths[]"]}},"filters":{"intentDetection":"\nINTENT DETECTION SIGNALS (check these patterns FIRST):\n- **JOB SEEKER signals**: \"looking for a [ROLE] role\", \"seeking [ROLE] position\", \"[ROLE] job\", \"I am looking for a [ROLE]\", \"find me a [ROLE] role\", \"find me a [ROLE] position\", \"find me a [ROLE] job\", \"find me a [ROLE] opportunity\", \"job search\", \"career opportunity\", \"open to [ROLE] roles\"\n- **RECRUITER/HIRING signals**: \"find [ROLE]s\", \"hire [ROLE]s\", \"source [ROLE]s\", \"looking for candidates\", \"build a team\", \"recruit\", \"staffing\"\n- **SALES/BD signals**: \"find customers\", \"looking for customers\", \"find buyers\", \"sell to\", \"sales leads\", \"prospects\", \"business development\"\n- **FUNDRAISING signals**: \"find investors\", \"raise funding\", \"Series A/B/C/Seed\", \"looking for VCs\", \"angel investors\", \"fundraising\"\n- **INVESTING signals**: \"find founders\", \"deal flow\", \"looking for startups\", \"portfolio companies\"\n\nINTENT CATEGORIES:\n- **Hiring/Recruiting**: User wants to hire someone. Target: Candidates with the specified skills/titles.\n- **Job Seeking**: User is looking FOR a job themselves. Target: Recruiters, Hiring Managers, HR, or executives who hire for that role.\n- **Sales/BD**: User is selling something. Target: Decision Makers (VP, Director, Head of, Chief) who can buy.\n- **Investing**: User is an investor. Target: Founders, CEOs of startups.\n- **Fundraising**: User is raising money. Target: Investors (VCs, Angels, Partners at funds).","roleReversal":"\nROLE REVERSAL RULES (MUST FOLLOW):\n- If the user is **Job Seeking** for a specific role (e.g., \"I am looking for a Director of Finance role\"):\n  * Do NOT put \"Director of Finance\" in job_titles.include\n  * Instead, put recruiter/talent titles relevant to the function (e.g., [\"Recruiter\", \"Technical Recruiter\", \"Engineering Recruiter\", \"Talent Acquisition\", \"Talent Partner\", \"Sourcer\", \"Recruiting Manager\"])\n  * Add the likely **hiring-manager seniority** for that target role:\n    - For **Director-level targets** (e.g., \"Director of Engineering\"): include next-level-up leaders like [\"VP Engineering\", \"Head of Engineering\", \"CTO\", \"Chief Technology Officer\", \"Senior Director of Engineering\"].\n      Avoid lower-level managers like \"Engineering Manager\" unless the user explicitly asks for them.\n    - For **Manager/IC targets**: it's OK to include hiring managers like \"Engineering Manager\" along with recruiters.\n  * Set hiring.job_titles to the role they want (e.g., [\"Director of Finance\"]) so we can boost people at companies hiring for that role\n  * Set hiring.mode=\"boost\" so job signals only boost results (never \"must\" for job seekers)\n  * Set job_titles.mode=\"boost\" so matching titles are preferred but not required (unless the user explicitly says \"only show\").\n  * Put \"hiring for Director of Finance roles\" in additional_context\n  * Put \"finance hiring\", \"finance recruitment\" in additional_context_keywords\n\n- If the user is **Job Seeking or doing job-search outreach** but explicitly asks for senior decision-makers / hiring owners and explicitly excludes recruiters, HR, Talent Acquisition, sourcers, or hiring managers:\n  * This is an OWNER-ONLY contact search, not the default recruiter/talent role reversal.\n  * Do NOT include recruiter, Talent Acquisition, HR, People, Sourcer, or Hiring Manager titles in job_titles.include.\n  * Put the requested senior owner titles in job_titles.include with job_titles.mode=\"must\" and job_titles.current_only=true.\n  * For commercial/category/retail/ecommerce/fashion/marketplace searches, use senior decision-maker titles such as [\"Commercial Director\", \"Head Of Commercial\", \"VP Commercial\", \"Chief Commercial Officer\", \"Ecommerce Director\", \"Head Of Ecommerce\", \"Category Director\", \"Head Of Category\", \"Buying Director\", \"Head Of Buying\", \"General Manager\", \"Country Manager\"].\n  * Avoid junior/peer execution titles such as \"Buyer\", \"Category Manager\", \"Buying Manager\", \"Merchandiser\", or \"Retail Manager\" unless the user explicitly relaxes seniority.\n  * If the user names a person geography like Dubai/UAE for the contact search, put it in locations.include, not hiring.locations.\n\n- If the user is **Job Seeking** for an executive/C-level role (e.g., \"find me a CTO role\", \"looking for a CEO position\"):\n  * Do NOT put \"CTO\" or \"CEO\" in job_titles.include - those are the roles they WANT, not who they need to connect with\n  * Instead, put EXECUTIVE RECRUITER titles: [\"Executive Recruiter\", \"Executive Search\", \"Managing Director\", \"Partner\", \"Principal\"] at search firms\n  * Also include board members and investors who often know of executive openings: [\"Board Member\", \"Venture Partner\", \"VC\", \"Investor\"]\n  * Set hiring.job_titles to [\"CTO\"] or [\"CEO\"] to boost people at companies hiring for that leadership role (if job postings exist)\n  * Set hiring.mode=\"boost\" so job signals only boost results (never \"must\" for job seekers)\n  * Set job_titles.mode=\"boost\" so matching titles are preferred but not required (unless the user explicitly says \"only show\").\n  * Put \"executive search\", \"C-level placement\", \"executive hiring\" in additional_context\n  * Put \"executive search firm\", \"executive placement\", \"CTO search\", \"leadership hiring\" in additional_context_keywords\n\n- If the user is **Sales/BD** looking for \"customers\":\n  * Do NOT leave job_titles empty or put generic titles\n  * Put decision maker titles: [\"VP\", \"Director\", \"Head of\", \"Chief\", \"Owner\", \"Decision Maker\", \"Buyer\"]\n  * Combine with the relevant department (e.g., \"VP of Engineering\", \"Director of HR\", \"Head of Operations\")\n  * Put \"purchasing authority\", \"budget owner\" in additional_context_keywords\n\nNAMED-COMPANY JOB-SEEKER RULES (apply ON TOP of ROLE REVERSAL when a specific employer is named):\n- Trigger: the user is job-seeking AND a specific target company is identifiable from the input. Signals include:\n  * the user names the company directly (\"at OpenAI\", \"in OpenAI offices\", \"Stripe role\")\n  * a \"Public page context from <hostname>:\" block is present whose Title or Summary names a recognizable employer\n    (e.g. \"Title: Content Integrity Analyst | OpenAI\", \"Public page context from openai.com/careers\"). The hostname\n    and the brand on the page Title are strong company-name evidence — use your judgment, do not pattern-match blindly.\n  * the user pastes a job posting / careers page URL whose page summary describes a role at a named company\n- When triggered:\n  * Populate companies.include with the target employer (use the canonical brand from the page title or message,\n    not the bare hostname). Prefer companies.include over keyword smuggling — the company name belongs in companies.\n  * Set companies.include_current_only = true (the user is looking to be hired NOW; past employees of the target are noise).\n  * job_titles.include MUST be the UNION of:\n      (a) the recruiter / talent family for the function (always include — these are the people who can move a resume forward),\n          drawn from the ROLE REVERSAL guidance for the target role's level (executive recruiter for C-level; technical/eng/\n          policy/etc. recruiter + generalist Recruiter / Talent Acquisition for IC and Manager roles).\n      (b) the function-aligned hiring-leadership cohort at the target level (e.g., for an IC/Manager Trust & Safety / Content\n          Integrity role: \"Trust & Safety Manager\", \"Director of Trust & Safety\", \"Head of User Operations\", \"VP of Trust & Safety\").\n    Both halves are required. Including only recruiters loses the leaders who actually own the requisition; including only\n    leaders loses the people who triage applications and write the JD.\n  * job_titles.mode = \"boost\" (NEVER \"must\" for a job-seeker — the user wants their network surfaced, not a hard exclusion).\n  * hiring.mode = \"boost\" and hiring.job_titles = the role title(s) named in the message or job posting (e.g.,\n    [\"Content Integrity Analyst\"]). This boosts contacts whose recent posts/positions match the requisition.\n  * Do NOT carry a years_experience floor over from the JD/page context onto the searcher.\n    A JD that says \"5+ years in Trust & Safety required\" is describing the REQUISITION'S requirement for the role being\n    hired for — it is NOT a constraint on the people we are surfacing for the user. The user is asking \"who can hire me?\"\n    or \"who is the recruiter?\", not \"find me a 5-YoE candidate\". Leave years_experience.min = null unless the USER'S OWN\n    message (not the page summary) explicitly states a minimum — e.g. the user themselves writes \"I want a recruiter who has\n    been at OpenAI for 5+ years\". Seniority cues like \"Senior\" or \"Staff\" belong in job_titles, not in years_experience.\n  * hiring.job_titles must be anchored to the role title NAMED in the JD/page Title (e.g. \"Content Integrity Analyst\")\n    plus close in-family variants. Do NOT extrapolate to the company's broader hiring patterns\n    (e.g. \"OpenAI also hires AI Engineers, ML Engineers, Applied Scientists\" — that is irrelevant to this requisition\n    and dilutes the boost signal).\n  * Do NOT add a person-side locations.include filter unless the user (not the job posting) explicitly asks for people in a\n    place. The job's office location belongs in hiring.locations, not locations.include — moving the job's geography to the\n    person filter strips out remote recruiters, leaders in other offices, and 1st-degree contacts elsewhere who can still\n    intro the user.\n  * For \"do you know who…\" / \"any intros to…\" / \"who could hire me for…\" phrasings, leave connection_degrees at the default\n    [\"1st\",\"2nd\"] and network_filter_mode = \"boost\" — these are reach phrases, not 1st-degree-only phrases. Do not narrow to\n    [\"1st\"] without an explicit cue from the CONNECTION_DEGREE_RULES.\n- This rule applies for both phrasings of the same intent — \"I need a recruiter for <Role> at <Company>\" and\n  \"do you know who may be hiring for this role <careers URL>\" should converge to the same filter shape (same companies,\n  same job_titles union, same hiring boost). They are not different intents.\n\nNAMED-COMPANY JOB-SEEKER — CONCRETE EXAMPLES (study these; the rule above is normative but the failure mode below has\nbeen observed repeatedly in production and the examples are how you avoid it):\n\nExample A — DIRECT ASK\nUser input: \"Hi Carl, I need a recruiter for Content Integrity in OpenAI offices - Trust & safety\"\n\n  CORRECT output:\n    companies.include: [\"OpenAI\"]\n    companies.include_current_only: true\n    job_titles.include: [\n      // recruiter / talent family for the function — REQUIRED HALF #1\n      \"Recruiter\", \"Talent Acquisition\", \"Sourcer\", \"Technical Recruiter\", \"Recruiting Manager\",\n      // function-aligned hiring leadership cohort — REQUIRED HALF #2\n      \"Trust & Safety Manager\", \"Director of Trust & Safety\", \"Head of User Operations\",\n      \"VP of Trust & Safety\", \"Content Integrity Manager\"\n    ]\n    job_titles.mode: \"boost\"\n    job_titles.current_only: true\n    hiring.mode: \"boost\"\n    hiring.job_titles: [\"Content Integrity Analyst\", \"Trust And Safety Analyst\", \"Policy Analyst\"]\n    locations.include: []                  // do NOT add a person location — user did not ask for one\n    years_experience: { min: null, max: null }\n    additional_context: \"OpenAI Trust & Safety hiring; Content Integrity team\"\n    additional_context_keywords_core: [\"trust and safety\", \"content integrity\"]\n\n  WRONG outputs we have seen (do NOT do these):\n    - companies.include = [\"OpenAI\"] but job_titles.include = [\"Recruiter\", \"Senior Recruiter\", \"Talent Acquisition Specialist\", \"Technical Recruiter\", \"Executive Recruiter\"] only\n      (RECRUITER-ONLY HALF — missing the Trust & Safety / User Operations leadership cohort. The user also wants intros to\n      the people who actually OWN the requisition, not just the people who screen resumes.)\n    - job_titles.mode = \"must\"\n      (HARD-EXCLUDES anyone whose title is close-but-not-exact. Job-seekers ALWAYS use \"boost\" here.)\n    - hiring.job_titles = [\"AI Engineer\", \"Machine Learning Engineer\", \"Applied Scientist\", \"Product Engineer\"]\n      (extrapolation to OpenAI's broader hiring; the JD names a specific role and the boost should anchor to that role.)\n\nExample B — CAREERS-LINK DROP (same intent, different phrasing — must converge to the same filter)\nUser input (preprocessed seed produced after the page is fetched and summarized — the input you actually receive):\n  \"carl do you know who may be hiring for this role  Public page context from openai.com/careers:\n   Title: Content Integrity Analyst | OpenAI\n   Summary: OpenAI is hiring a Content Integrity Analyst on its Trust & Safety Operations / User Operations team in\n   San Francisco (hybrid). The role focuses on investigating complex abuse cases, enforcing usage policies, handling\n   high-stakes escalations, and building scalable safety workflows and automation. They're looking for someone with\n   5+ years in Trust & Safety, integrity, risk, or policy enforcement.\n   Requested focus: carl do you know who may be hiring for this role\"\n\n  CORRECT output: same SHAPE as Example A\n    companies.include: [\"OpenAI\"]                       // brand from the Title line, NOT the bare hostname \"openai.com\"\n    job_titles.include: [recruiter family + T&S/User Ops leadership cohort, same as Example A]\n    job_titles.mode: \"boost\"\n    hiring.job_titles: [\"Content Integrity Analyst\"]    // anchored to the Title line, not extrapolated\n    hiring.locations: [\"San Francisco\"]                 // job geography belongs HERE\n    locations.include: []                                // person geography stays empty\n    years_experience: { min: null, max: null }           // \"5+ years\" is the JD's requirement, NOT the searcher's YoE\n    connection_degrees: [\"1st\", \"2nd\"]                   // \"do you know who\" is reach phrasing, not 1st-only\n    network_filter_mode: \"boost\"\n\n  WRONG outputs we have seen (do NOT do these):\n    - companies.include = []\n      (the brand \"OpenAI\" appears verbatim in the Title line; failing to lift it into companies.include is the single\n      biggest precision loss for this class of query.)\n    - job_titles.include = [\"Trust & Safety Manager\", \"Trust & Safety Operations Manager\", \"User Operations Manager\", \"Content Integrity Manager\", \"Policy Operations Manager\"] only\n      (LEADERSHIP-ONLY HALF — missing the Recruiter / Talent family. The user wants intros to recruiters too.)\n    - job_titles.mode = \"must\"\n    - years_experience.min = 5\n      (this came from the JD's \"5+ years\" requirement, which is a property of the requisition not the user. Leave null.)\n    - locations.include = [\"San Francisco Bay Area\"]\n      (JD office location bleeding into the person filter. The user did not ask for people IN SF; they asked for people\n      who could hire them for THIS SF role. Their network in NY who could intro them is still useful.)","companyHiringPersonScope":"\nCOMPANY-HIRING TWO-HOP PERSON-SCOPE RULES (CRITICAL when the user is NOT job-seeking):\n- Trigger: the description implies finding PEOPLE AT companies that are actively hiring for a role\n  (e.g. \"companies hiring senior engineering leaders\", \"companies recruiting data scientists\",\n  \"people at companies opening sales roles\", \"find me folks at places ramping product teams\").\n- This is distinct from Job Seeking (ROLE REVERSAL handles that). Here the user is prospecting\n  CONTACTS at hiring companies, not trying to get hired themselves.\n- When triggered, set BOTH:\n  1. Company-side (company_search.include.filters.job_keyword_hints): the hiring role/domain keywords.\n  2. Person-side (filters.job_titles.include, mode=\"boost\"): the cohort most likely to be useful\n     contacts at those companies — hiring leadership in the same domain PLUS domain recruiters.\n- Domain → cohort mapping (seed list; extend when the user names a different function):\n  * Engineering (eng leader / senior eng / staff / principal / VP eng / CTO / head of engineering):\n    [\"Staff Engineer\", \"Principal Engineer\", \"Engineering Manager\", \"Director of Engineering\",\n     \"VP of Engineering\", \"Head of Engineering\", \"CTO\", \"Chief Technology Officer\",\n     \"Technical Recruiter\", \"Engineering Recruiter\"]\n  * Sales (sales leader / AE / SDR / BDR / VP sales):\n    [\"VP of Sales\", \"Head of Sales\", \"Director of Sales\", \"Sales Manager\",\n     \"Sales Recruiter\", \"Talent Partner\"]\n  * Product (PM / product leader / VP product):\n    [\"VP of Product\", \"Director of Product\", \"Head of Product\", \"Senior Product Manager\",\n     \"Engineering Manager\", \"Product Recruiter\", \"Technical Recruiter\"]\n  * Design (designer / head of design):\n    [\"Head of Design\", \"Director of Design\", \"Design Manager\",\n     \"Design Recruiter\", \"Talent Recruiter\"]\n  * Data / ML (data scientist / data engineer / ML):\n    [\"Director of Data Science\", \"Head of Data\", \"VP of Data\", \"Engineering Manager\",\n     \"Technical Recruiter\", \"Data Recruiter\"]\n  * Marketing (growth / CMO / head of marketing):\n    [\"VP of Marketing\", \"Head of Marketing\", \"Director of Marketing\",\n     \"Marketing Recruiter\", \"Talent Partner\"]\n- If the user explicitly ENUMERATES titles (\"(VP Design, Chief Design Officer, or Head of Design)\",\n  \"X, Y, or Z\"), use THEIR titles (plus close variants) — never replace an explicit enumeration with\n  these cohort lists. The cohorts apply only when the description has hiring/recruiting wording and\n  names a function without an explicit title list.\n- Always set job_titles.mode = \"boost\" for this rule — we want to rank these cohorts first but still\n  allow close matches through. Never set mode = \"must\" via this rule; that is too restrictive.\n- Set hiring.mode = \"boost\" and hiring.job_titles to the target hiring role(s).\n- Put a clarifier in additional_context: \"contacts at companies hiring for <role>\".\n- Do NOT confuse this rule with ROLE REVERSAL (job-seeking). Signals that we are HERE, not there:\n  the user's phrasing centers on the COMPANY (\"companies hiring ...\", \"places ramping ...\",\n  \"firms with open ... roles\") and seeks contacts AT those companies, not roles FOR themselves.","connectionDegrees":"\nNETWORK / CONNECTION DEGREE SEMANTICS:\n\nCRITICAL GUIDING PRINCIPLE — interpret INTENT, not literal phrasing. If the user's phrasing implies they have ALREADY personally formed a direct relationship with the target (already connected, already linked, already accepted, already in their contacts/rolodex, already added, already know them personally, already have their info), this is a FIRST-DEGREE-ONLY search. Do NOT require exact phrases like \"1st degree\" or the adverb \"directly\" — plain natural-language phrasings count. Do NOT include \"2nd\" in connection_degrees for these cases, even if the default would otherwise be [\"1st\",\"2nd\"]. This principle OVERRIDES the default.\n\nSignals that mean FIRST-DEGREE ONLY (non-exhaustive — recognize equivalents and paraphrases):\n  * \"connected to me\", \"that I'm connected to\", \"that I am connected to\", \"who I'm connected with\", \"people I'm connected with\", \"my connections\"\n  * \"linked up with\", \"linked with on LinkedIn\", \"I've linked with\"\n  * \"added on LinkedIn\", \"who I've added\", \"people I've added over the years\"\n  * \"invites I've accepted\", \"people whose invites I accepted\", \"who I've accepted\"\n  * \"in my rolodex\", \"in my contacts\", \"in my address book\", \"on my contacts list\"\n  * \"people I know\", \"leaders I know\", \"who do I know\", \"do I know any [ROLE]\", \"folks I know personally\"\n  * \"my direct contacts\", \"my close connections\", \"personal network\", \"people I've personally met\"\n  * Any phrasing where the user uses a first-person perfect-tense verb implying they already formed the tie (I have / I've + connected/added/accepted/linked/met/known).\n\nTEST: Does the phrasing describe people the user ALREADY has a direct tie with (vs. people they could *reach* through their network)? If yes → [\"1st\"] + \"filter\". If the user is describing reach/reachability/network-coverage → [\"1st\",\"2nd\"] + \"boost\".\n\n- When the user talks about people they **personally know or are directly connected to** (any signal above, or equivalent natural-language phrasings):\n  * Set connection_degrees to [\"1st\"] (only direct, first-degree connections). Do NOT include \"2nd\".\n  * Set network_filter_mode = \"filter\" so counts and results are restricted to those people.\n- When the user says \"in my network\", \"in my LinkedIn network\", or similar:\n  * Treat this as first- and second-degree network context.\n  * Set connection_degrees to [\"1st\", \"2nd\"].\n  * Prefer network_filter_mode = \"boost\" so the network is prioritized but not strictly required.\n- When the user says \"people I can reach\", \"reachable through my network\", or similar:\n  * Treat this as first- and second-degree network context.\n  * Set connection_degrees to [\"1st\", \"2nd\"].\n  * Prefer network_filter_mode = \"boost\" so the network is prioritized but not strictly required.\n- When the user explicitly asks for channel reachability such as \"people I can email\", \"reachable by email\", \"reachable on LinkedIn\", or \"on Super Carl\":\n  * Use filters.reachable_via instead of overloading connection_degrees.\n  * \"people I can email\" / \"reachable by email\" / \"gmail reachable\" => reachable_via: [\"gmail\"]\n  * \"reachable on X\" / \"can DM on X\" / \"reachable on Twitter\" => reachable_via: [\"x\"]\n  * \"reachable on Instagram\" / \"can DM on Instagram\" / \"Instagram reachable\" => reachable_via: [\"instagram\"]\n  * \"reachable on LinkedIn\" / \"can message on LinkedIn\" => reachable_via: [\"linkedin\"]\n  * \"on Super Carl\" / \"reachable on Super Carl\" => reachable_via: [\"super_carl\"]\n- Do NOT use filters.reachable_via for generic preferences like \"likely reachable\", \"professional profiles\", \"social profiles\", \"has a LinkedIn profile\", or \"show me contact info\". Those are output/enrichment preferences, not hard search filters. Search can still return LinkedIn profile URLs and sourced email evidence without the requester having a connected network.\n- When the user explicitly asks for \"second degree only\", \"just 2nd degree\", \"beyond my direct connections\", or \"introduction path\":\n  * Set connection_degrees to [\"2nd\"].\n  * Prefer network_filter_mode = \"filter\" so only second-degree matches are counted.\n- When the user wants to search **everyone on Super Carl** or the full platform (e.g., \"across Super Carl\", \"in the Super Carl network\", \"everyone here\", \"all users on Super Carl\", \"no network filter\"):\n  * Do NOT restrict by connection_degrees unless they explicitly mention degrees.\n  * Use included_networks to reflect the pools (\"super_carl\", \"linkedin\") but prefer network_filter_mode = \"ignore\" so results are not gated by proximity.\n- When the user explicitly mentions third-degree scope (e.g., \"3rd degree\", \"third-degree\", \"3rd+\"):\n  * If they want to include third-degree connections, set connection_degrees to [\"1st\", \"2nd\", \"3rd+\"].\n  * If they say \"only 3rd degree\", set connection_degrees to [\"3rd+\"] and network_filter_mode = \"filter\".\n- \"1st-degree connections\" / \"direct connection\" / \"direct connections\" / \"people I know\" / \"people I am connected to\" / \"folks I've linked up with\" / \"in my rolodex\" → connection_degrees: [\"1st\"], network_filter_mode: \"filter\"\n- \"1st and 2nd-degree connections\" / \"immediate network\" / \"my network\" / \"people I can reach\" → connection_degrees: [\"1st\", \"2nd\"]\n- \"introduction path\" / \"through an introduction\" → connection_degrees: [\"2nd\"]\n- If no network proximity is specified AND the user is not describing an existing direct tie, default to connection_degrees: [\"1st\", \"2nd\"] (standard network search). This default does NOT apply when the user's phrasing implies an existing direct tie — see CRITICAL GUIDING PRINCIPLE above.\n- DISAMBIGUATION: \"my network\" / \"in my network\" = 1st + 2nd (broader reach). But \"people I am connected to\" / \"my connections\" / \"who I'm linked with\" / \"in my rolodex\" / \"added on LinkedIn\" / \"invites I accepted\" implies the user already has a direct relationship → 1st only + \"filter\". When in doubt, ask: \"does the phrasing imply the user has personally formed the tie?\" If yes → [\"1st\"] only.\n- IMPORTANT: Recognize phrases like \"who do I know in [location]\" as 1st-degree only with a location filter.","locations":"\nCRITICAL - REMOTE WORK IS NOT A LOCATION:\n- \"Remote\", \"work remotely\", \"remote work\", \"WFH\", \"work from home\" are work arrangements, NOT geographic locations.\n- Do NOT put \"Remote\" in locations.include - this will incorrectly filter to profiles that have \"Remote\" in their location field (very few profiles have this).\n- Instead, put work arrangement preferences in additional_context (e.g., \"open to remote work\", \"remote-friendly candidates\").\n- If the description says \"remote developers\" or \"remote iOS engineers\", set job_titles appropriately but leave locations empty unless an actual geographic location is also mentioned.\n- Only use locations for actual geographic places: cities (San Francisco, NYC), states (California, Texas), countries (USA, UK), or regions (Bay Area, Midwest).\n- Phrases like \"innovation hubs\", \"startup hubs\", \"tech hubs\", or \"major hubs\" are NOT locations.\n  Do not expand them into lists of cities unless the user explicitly names specific places.\n\nJOB SEEKING: JOB LOCATION VS PEOPLE LOCATION:\n- When the user is **Job Seeking** and talking about where they want the JOB to be (remote / onsite / \"in California\" / \"in SF\"):\n  * Put job geography in hiring.locations (job postings location signals), NOT locations.include (people location), unless they explicitly want recruiters based in a place.\n  * For \"remote only\": set hiring.accepts_remote=true and leave hiring.locations empty (or include \"Remote\" in hiring.locations if you also need a text signal).\n  * For \"onsite only\" / \"not remote\": set hiring.accepts_remote=false and set hiring.locations to the desired geography if provided.\n  * For \"remote or SF\" / \"either\": set hiring.accepts_remote=null and include both \"Remote\" and the geography in hiring.locations (e.g., [\"Remote\", \"San Francisco Bay Area\"]).\n\nHIRING.ACCEPTS_REMOTE — ONLY SET WHEN EXPLICIT:\n- Leave hiring.accepts_remote = null (the default \"any\") UNLESS the user's message explicitly mentions a work arrangement preference.\n- Explicit mentions include: \"remote\", \"fully remote\", \"remote-first\", \"remote-friendly\", \"WFH\", \"work from home\", \"onsite\", \"on-site\", \"in-office\", \"in-person\", \"hybrid\", \"hybrid work\".\n- If the query is a bare role phrase like \"QA engineer\" or \"Senior Product Manager\" with no work-arrangement cue, you MUST leave hiring.accepts_remote = null. Do NOT guess or invent a preference based on the role or industry.\n- When the user signals remote (\"remote-friendly candidates\", \"open to remote\"), also refrain from auto-inferring a geographic location filter. A remote-friendly search should not add people-location chips unless a specific city/state/country is also named.\n\nLOCATION NORMALIZATION:\n- If the description mentions a broad region like \"bay area\", resolve it to \"San Francisco Bay Area\".\n- Do NOT invent locations, timezones, or countries that are not explicitly stated in the description (exception: \"within my timezone\" can use the requester's known timezone if provided in context).\n- Do not treat timezones as locations.\n\nTIMEZONE FILTERS:\n- Use \"timezones\" to match candidates within N hours of a timezone (by UTC offset).\n- Shape: timezones: { \"timezone\": \"<IANA timezone ID>\", \"within_hours\": number }.\n- Use nulls (or omit the object) for \"any timezone\".\n- Allowed within_hours: 1-11. If user asks for 12+ hours, treat as \"any timezone\".\n- \"within my timezone\" → use the requester's timezone (if known) with within_hours = 3.\n- \"within 1 hour of PST\" → timezones: { timezone: \"America/Los_Angeles\", within_hours: 1 }.\n- If a timezone is given as an abbreviation (PST/EST/etc), normalize to an IANA timezone ID.\n- Bare state/place names such as \"Alaska\" or \"Hawaii\" are locations when the user says people live in / are based in / are located in that place. Do not convert them to timezone filters unless the user explicitly says timezone/time zone, uses a timezone abbreviation, or asks for a within-hours timezone window.\n- Never put timezone abbreviations in locations.include.","jobTitles":"\nJOB TITLE GUIDELINES - ANCHOR TO ROLE FAMILY, PUT STACK/DOMAIN IN KEYWORDS:\nThe job_titles filter uses ILIKE pattern matching (e.g., \"%iOS Engineer%\" matches \"Senior iOS Engineer\").\nProfile retrieval ALSO matches stack/domain keywords against headline/summary/skills/experience text. So the right strategy is:\n- job_titles anchors the ROLE FAMILY (e.g. iOS Engineer, DevOps Engineer, Smart Contract Engineer, Data Scientist).\n- additional_context_keywords_core anchors the STACK/DOMAIN/TOOL (e.g. iOS, Swift, DevOps, Solidity, machine learning).\nThe keyword layer distinguishes the specialization, so the title list does not need to \"broaden\" via generic engineer titles.\n\nROLE-SHAPED QUERIES MUST POPULATE job_titles.include:\n- If the user's entire query (or its primary clause) is a role/title phrase — for example a bare role noun with optional seniority like \"QA engineer\", \"Senior Product Manager\", \"Staff iOS Engineer\", \"VP of Engineering\", \"Director of Product Design\" — you MUST populate job_titles.include with that normalized phrase plus close in-family variants.\n- This rule applies EVEN IF the query is short (2-5 words). Do not leave job_titles.include empty when the query reads as a role phrase.\n- If the query names a seniority prefix (Senior / Sr / Staff / Principal / Lead / Head of / Director of / VP of / Chief), preserve that seniority in at least one entry in job_titles.include.\n- This rule does NOT apply when role-reversal kicks in (job-seeking / fundraising / sales-BD / investing) — those intents have their own title mapping above.\n\nCRITICAL STRATEGY — STAY ANCHORED TO THE ROLE FAMILY:\n1. When the query names a SPECIALIZED role family, job_titles.include MUST stay within that family. Do NOT add generic \"Software Engineer\" / \"Senior Software Engineer\" / \"Engineer\" / \"Developer\" / \"Software Developer\" as a \"broader fallback\" — those generic titles dilute precision because generic engineers without the specialization satisfy the title clause. Instead, expand within the specialized family with seniority/variant titles.\n   Specialized families and the title anchors that stay in-family (non-exhaustive — generalize the principle to other specialized families):\n   - iOS / Android / React Native / mobile: [\"iOS Engineer\",\"iOS Developer\",\"Senior iOS Engineer\",\"Mobile Engineer\"] / [\"Android Engineer\",\"Android Developer\",\"Senior Android Engineer\",\"Mobile Engineer\"] / [\"React Native Engineer\",\"React Native Developer\",\"Mobile Engineer\"]\n   - SRE / site reliability / observability: [\"Site Reliability Engineer\",\"Reliability Engineer\",\"Observability Engineer\",\"Production Engineer\"]\n   - DevOps / platform: [\"DevOps Engineer\",\"Platform Engineer\",\"Infrastructure Engineer\",\"Site Reliability Engineer\"]\n   - Frontend / UI: [\"Frontend Engineer\",\"Senior Frontend Engineer\",\"UI Engineer\",\"Web Engineer\"]\n   - Backend (when language-specific stack is named): [\"Backend Engineer\",\"Senior Backend Engineer\",\"Platform Engineer\"]\n   - Machine learning / MLOps / AI: [\"Machine Learning Engineer\",\"ML Engineer\",\"Applied Scientist\",\"MLOps Engineer\"]\n   - Data scientist: [\"Data Scientist\",\"Senior Data Scientist\",\"Applied Scientist\"] — do NOT broaden to \"Data Analyst\", \"Software Engineer\", \"Engineer\".\n   - Smart contract / Solidity / blockchain: [\"Smart Contract Engineer\",\"Smart Contract Developer\",\"Blockchain Engineer\",\"Solidity Developer\"]\n   - Embedded / firmware: [\"Embedded Engineer\",\"Embedded Systems Engineer\",\"Firmware Engineer\"]\n   - Salesforce admin/developer: [\"Salesforce Administrator\",\"Salesforce Developer\"]\n   - Engineering leadership (Director/Head/VP of Engineering): keep the title set in leadership families — do not add IC engineer titles unless explicitly requested.\n   - Product / design / data / generic leadership (these are NOT specialized engineering families and may use broader sets): [\"Product Manager\",\"Product Lead\",\"PM\"], [\"Designer\",\"Product Designer\",\"UX Designer\"], [\"Data Engineer\",\"Analytics Engineer\",\"Analyst\"], [\"Director\",\"VP\",\"Head of\",\"Manager\"].\n\n2. Put SPECIFIC technologies, platforms, or domains in additional_context_keywords_core:\n   - \"iOS\", \"Android\", \"Swift\", \"Kotlin\", \"React Native\", \"mobile\" → keywords_core\n   - \"Solidity\", \"smart contracts\", \"blockchain\", \"Ethereum\" → keywords_core\n   - \"DevOps\", \"Kubernetes\", \"Terraform\", \"CI/CD\" → keywords_core\n   - \"AI\", \"machine learning\", \"ML\", \"LLM\" → keywords_core\n   - \"Python\", \"TypeScript\", \"Go\", \"Rust\" → keywords_core when the stack is the PRIMARY requirement; bonus/nice-to-have phrasing (\"Rust is a bonus/a plus\") routes to keywords_supporting instead\n\n3. Example: \"iOS developers in San Francisco\"\n   CORRECT:\n   - job_titles.include: [\"iOS Engineer\", \"iOS Developer\", \"Mobile Engineer\"]\n   - additional_context_keywords_core: [\"iOS\", \"Swift\"]\n   - locations.include: [\"San Francisco\"]\n\n   WRONG:\n   - job_titles.include: [\"iOS Engineer\", \"Mobile Engineer\", \"Software Engineer\"] ← \"Software Engineer\" is a generic fallback that lets non-iOS engineers in SF satisfy the title clause. Drop it; the keyword core anchors handle profile-level matching.\n   - job_titles.include: [\"Software Engineer\", \"Engineer\", \"Developer\"] ← Loses the iOS title anchor entirely.\n\n4. Example: \"DevOps engineers, remote\"\n   CORRECT:\n   - job_titles.include: [\"DevOps Engineer\", \"Platform Engineer\", \"Site Reliability Engineer\", \"Infrastructure Engineer\"]\n   - additional_context_keywords_core: [\"DevOps\"]\n\n   WRONG:\n   - job_titles.include: [\"DevOps Engineer\", \"Platform Engineer\", \"Software Engineer\"] ← \"Software Engineer\" lets generic SEs satisfy the title clause without DevOps evidence.\n\n5. Example: \"Solidity devs\"\n   CORRECT:\n   - job_titles.include: [\"Smart Contract Engineer\", \"Smart Contract Developer\", \"Blockchain Engineer\", \"Solidity Developer\"]\n   - additional_context_keywords_core: [\"Solidity\", \"smart contracts\"]\n\n   WRONG:\n   - job_titles.include: [\"Smart Contract Engineer\", \"Blockchain Engineer\", \"Software Engineer\"] ← Generic SE fallback dilutes — drop it.\n\n6. Example: \"Python backend developers\"\n   CORRECT:\n   - job_titles.include: [\"Backend Engineer\", \"Senior Backend Engineer\", \"Platform Engineer\"]\n   - additional_context_keywords_core: [\"Python\", \"backend\", \"server-side\"]\n\n   WRONG:\n   - job_titles.include: [\"Python Developer\", \"Python Engineer\"] ← Too narrow; Python rarely appears in titles.\n   - job_titles.include: [\"Backend Engineer\",\"Software Engineer\",\"Engineer\"] ← Don't add \"Software Engineer\"/\"Engineer\" as broaden-fallbacks; rely on the keyword core \"Python\" + \"backend\".\n\n7. Example: \"React Native engineers building mobile apps\"\n   CORRECT:\n   - job_titles.include: [\"React Native Engineer\", \"React Native Developer\", \"Mobile Engineer\"]\n   - additional_context_keywords_core: [\"React Native\", \"mobile\", \"mobile app\"]\n\n   WRONG:\n   - job_titles.include: [\"iOS Engineer\", \"Android Engineer\", \"Software Engineer\"] ← Drifts into adjacent mobile families and adds generic fallback.\n\n8. When the role noun is ambiguous across domains (for example \"architect\"), preserve the explicit domain disambiguator from the user's words in BOTH titles and keywords:\n   - Built-environment / building architecture requests:\n     * Prefer built-environment titles such as [\"Lead Architect\", \"Project Architect\", \"Architect\", \"Principal Architect\"].\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"building design\", \"architectural design\", \"construction documents\"] when stated.\n     * Do NOT add software/platform/application architect titles unless the user explicitly asks for software architecture.\n   - Software / platform / application architecture requests:\n     * Prefer titles such as [\"Lead Software Architect\", \"Software Architect\", \"Platform Architect\", \"Application Architect\"].\n     * If lead/principal/chief/director seniority is stated, preserve that seniority in at least one architect title.\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"software architecture\", \"platform\", \"application\", \"distributed systems\"] when stated.\n     * Do NOT broaden to adjacent architect families like [\"Solutions Architect\", \"Enterprise Architect\", \"Cloud Architect\", \"Information Architect\"] unless the user explicitly asks for those titles.\n     * Do NOT use built-environment architect titles unless the user explicitly asks for buildings / construction / built environment.\n\n6. When the role noun is ambiguous across domains (for example \"architect\"), preserve the explicit domain disambiguator from the user's words in BOTH titles and keywords:\n   - Built-environment / building architecture requests:\n     * Prefer built-environment titles such as [\"Lead Architect\", \"Project Architect\", \"Architect\", \"Principal Architect\"].\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"building design\", \"architectural design\", \"construction documents\"] when stated.\n     * Do NOT add software/platform/application architect titles unless the user explicitly asks for software architecture.\n   - Software / platform / application architecture requests:\n     * Prefer titles such as [\"Lead Software Architect\", \"Software Architect\", \"Platform Architect\", \"Application Architect\"].\n     * If lead/principal/chief/director seniority is stated, preserve that seniority in at least one architect title.\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"software architecture\", \"platform\", \"application\", \"distributed systems\"] when stated.\n     * Do NOT broaden to adjacent architect families like [\"Solutions Architect\", \"Enterprise Architect\", \"Cloud Architect\", \"Information Architect\"] unless the user explicitly asks for those titles.\n     * Do NOT use built-environment architect titles unless the user explicitly asks for buildings / construction / built environment.\n\nWHY THIS MATTERS:\n- Most engineers have generic titles like \"Software Engineer\" or \"Senior Engineer\", so specialized core keywords (e.g., \"iOS\", \"Solidity\", \"DevOps\") must carry the requested stack/domain in profile text scoring.\n- Generic \"Software Engineer\" entries are not a substitute for the specialization; the keyword core anchors the family, while the title anchors keep precision tight to the requested family.\n- Adding \"Software Engineer\" / \"Engineer\" / \"Developer\" as a \"broader fallback\" actively HURTS precision because generic engineers can satisfy the title clause and outrank in-family candidates.\n\nADDITIONAL GUIDELINES:\n- Keep job_titles.include to 3-6 family-anchored terms (variants, seniority, in-family adjacents only)\n- For specialized engineering searches, anchor titles to the specialized family — do NOT add generic \"Software Engineer\" / \"Engineer\" / \"Developer\" as a broader fallback\n- For concise present-tense person-sourcing role requests (for example \"people who are X\", \"show me Xs\", \"I am looking for an architectural engineer\"), set job_titles.current_only = true unless the user explicitly asks for historical/background scope. For \"former/previously <title> but not currently <title>\", set current_only=false and exclude_current_only=true with matching job_titles.exclude.\n- Use additional_context_keywords_core for the primary high-signal specific skills (2-6 terms)\n- Use additional_context_keywords_supporting for nice-to-have skills (2-8 terms)\n- Only populate job title exclusions when the description explicitly calls out roles to avoid.\n- If the user asks for junior/entry-level/early-career talent, explicitly exclude seniority/leadership titles:\n  [\"Senior\", \"Sr\", \"Lead\", \"Manager\", \"Director\", \"Head\", \"Principal\", \"Staff\", \"VP\", \"Vice President\", \"Chief\"].\n- Use job_titles.mode=\"must\" when the user is explicitly hiring/recruiting and you should ONLY include people with those titles.\n- Use job_titles.mode=\"boost\" when titles are a preference (e.g., job seekers contacting people at companies hiring).","keywords":"\nKEYWORD GUIDELINES - USE KEYWORDS FOR SPECIFIC SKILLS:\nKeywords search across the ENTIRE profile (headline, summary, experience, skills) and are essential for targeting specific technologies/platforms.\n\n⚠️ CRITICAL - NEVER PUT THESE IN ANY KEYWORD FIELD:\n- \"available\", \"immediately\", \"available immediately\", \"ASAP\", \"start soon\", \"ready to start\"\n- \"looking for\", \"want to\", \"need to find\", \"seeking\"\n- \"senior\", \"junior\", \"mid-level\" (use years_experience filter instead)\n- \"contacts\", \"people\", \"network\", \"connections\"\n- Role/process terms that belong in job_titles or additional_context, NOT keywords:\n  \"recruiter\", \"recruiters\", \"talent acquisition\", \"hiring manager\", \"executive search\",\n  \"job posting(s)\", \"hiring\", \"prioritize\", \"target\", \"reach out\"\n- Locations (cities, states, countries, regions) and work arrangements (remote/hybrid/onsite) - use locations.include or hiring.locations/accepts_remote instead.\n- Explicit job titles or seniority levels (e.g., \"VP\", \"Director\", \"Head of\", \"C-level\") - use job_titles or hiring.job_titles instead.\n- Company names or specific employers - use companies.include instead.\n- Any timing/availability/urgency phrases - these are NOT LinkedIn profile terms!\n- When the user mentions niche domains (crypto, bitcoin, web3, blockchain, DeFi, Lightning), treat them as KEYWORDS.\n  Only populate \"industries\" for canonical broad industries (e.g., \"Financial Services\", \"Technology, Information and Internet\").\nPut availability notes in \"additional_context\" as free text, NOT in keyword arrays.\n\nCRITICAL: additional_context_keywords_core is the high-signal profile keyword lane:\n- Use this for the PRIMARY technology/skill/domain mentioned in the query\n- Set keyword_match_mode=\"hard\" only when the user explicitly requires profiles to mention/contain at least one profile keyword term\n- Examples: \"iOS\", \"Python\", \"machine learning\", \"React Native\", \"sales\", \"marketing\"\n- When the title noun is ambiguous across domains (for example \"architect\"), additional_context_keywords_core MUST carry the explicit domain phrases from the query so sibling domains are filtered out.\n  Example: \"lead architects for building design and architecture projects\" → core: [\"building design\", \"architectural design\"].\n  Example: \"lead software architects for platform or application systems\" → core: [\"platform\", \"application\", \"software architecture\"].\n- For job seekers, keep additional_context_keywords_core limited to domain/industry/skill terms explicitly stated\n  (or present in the user profile context). Do NOT include recruiter/hiring/process phrases.\n- DOMAIN-PHRASE EXTRACTION: whenever the query contains an explicit domain/specialty phrase that scopes the work area — including but not limited to \"enterprise networking\", \"search infrastructure\", \"developer tools\", \"machine learning operations\", \"real-time systems\", \"trading systems\", \"edge computing\", \"ad tech\", \"marketing automation\", \"growth marketing\", \"supply chain\", \"robotics perception\" — that phrase MUST appear in additional_context_keywords_core (verbatim or as the closest LinkedIn-advertised form). additional_context_keywords_core MUST NOT be empty when the query supplies such a domain phrase.\n  Example: \"Engineers at Cisco who work on enterprise networking\" → core: [\"enterprise networking\", \"networking\"]; supporting: [\"routing\", \"switching\", \"TCP/IP\", \"Cisco IOS\"].\n  Example: \"PMs at Google working on search infrastructure\" → core: [\"search infrastructure\", \"search\"]; supporting: [\"ranking\", \"retrieval\", \"indexing\"].\n  Example: \"engineers building developer tools at GitHub\" → core: [\"developer tools\", \"DX\"]; supporting: [\"SDK\", \"CLI\", \"API\"].\n  General principle: a query of the form \"<role> at <company> who/that work(s) on <domain phrase>\" or \"<role> who/that focus(es) on <domain phrase>\" requires the domain phrase to be lifted into additional_context_keywords_core. The company anchor alone is not sufficient — the domain phrase is what disambiguates within that company.\n\nBONUS / NICE-TO-HAVE SKILLS ARE NEVER CORE:\n- Bonus/preference phrasing (\"a bonus\", \"a plus\", \"nice to have\", \"ideally\", \"preferred but not required\") MUST route to additional_context_keywords_supporting (ranking boost), never additional_context_keywords_core, and must not set keyword_match_mode=\"hard\". A bonus skill in hard profile keywords filters out everyone who lacks the bonus.\n\nHOW THE KEYWORDS WORK:\n1. additional_context_keywords_core (2-6 terms) - Primary high-signal profile terms\n   - Put the PRIMARY technology/platform/skill here\n   - \"iOS developers\" → core: [\"iOS\", \"mobile\", \"Swift\"]\n   - \"AI engineers\" → core: [\"AI\", \"machine learning\", \"ML\"]\n   - \"Python developers\" → core: [\"Python\"]\n\n2. additional_context_keywords_supporting (2-8 terms) - Nice-to-have, improves ranking\n   - Secondary skills or related technologies ONLY\n   - \"iOS developers\" → supporting: [\"Objective-C\", \"Xcode\", \"App Store\", \"UIKit\"]\n   - NEVER put availability/timing phrases here!\n\n3. additional_context_keywords (3-15 terms) - General boost scoring\n   - Broadest set of related technical/professional terms\n\nEXAMPLES:\n\"senior iOS developers available immediately\"\n→ keywords_core: [\"iOS\", \"mobile\", \"Swift\"]\n→ keywords_supporting: [\"Objective-C\", \"Xcode\", \"UIKit\", \"App Store\"]\n→ additional_context: \"senior level, available immediately\" (NOT in keywords!)\n\n\"Python backend developers\"\n→ keywords_core: [\"Python\", \"backend\"]\n→ keywords_supporting: [\"Django\", \"Flask\", \"FastAPI\", \"REST\", \"API\"]\n\n\"Growth marketers for B2B SaaS\"\n→ keywords_core: [\"growth\", \"marketing\", \"B2B\", \"SaaS\"]\n→ keywords_supporting: [\"demand generation\", \"lead generation\", \"PLG\", \"conversion\"]\n\n\"backend engineers ... If they have Rust experience, that is a bonus\"\n→ keywords_core: [\"backend\"]\n→ keywords_supporting: [\"Rust\"]  (bonus skill stays supporting, NOT core)\n\nKeywords must be terms professionals actually write in their LinkedIn profiles - skills, technologies, domains, tools.","companySearch":"\nCOMPANY SEARCH FILTERS (Company-first workflows):\n- Company preview searches translate natural language into CompanySearchFilters (see /api/v1/companies/search/preview).\n- When translating PEOPLE descriptions, map company-specific constraints to company_search.\n- Always map canonical company industries and company headcount/size constraints to company_search (not top-level people filters.industries or people filters.company_size).\n- Company-specific constraints include: industries, headcount/size, funding rounds/stage, company stage/status/type, headcount growth, hiring growth, job posting volume, website traffic, technologies, founded year, and revenue.\n- Keep person criteria (role, seniority, person location, experience, skills) in people filters. Only use company search when the description explicitly attributes criteria to the COMPANY.\n- Functional department terms for target people are not company industries. Prompts like \"in-house recruiting decision makers\", \"talent acquisition leaders\", \"people leaders\", or \"HR leaders\" should map recruiting/talent/people/HR to people job_titles/context, not company_search industries, unless the user explicitly asks for recruiting agencies, staffing firms, HR software/services companies, or companies in the recruiting/HR industry.\n- If the description explicitly references company HQ/region (e.g., \"SF-based companies\", \"US companies\"), populate company_search.location. Do NOT move person locations into company search.\n- Do NOT place specific company names into company search; use companies.include/exclude instead.\n- Open-to-work / currently-unemployed intent is not a native company or person boolean and is usually sparse profile/post text. Keep availability terms only as soft people evidence, not additional_context_keywords_core. Prefer company_status/headcount_growth/hiring_growth/job_postings when the user wants company closure, sale, flat growth, contraction, or no-hiring as an availability proxy; run separate passes when recall matters because combining them creates an AND gate.\n- Common fields:\n  * location: { country, state }\n  * industries, company_tags, industry_keywords\n  * company_type, company_stage, company_sub_stage, company_status\n  * company_headcount (min/max)\n  * founded_year (min/max)\n  * funding: { stages, min_amount, max_amount, date_range }\n  * revenue: { min, max }\n  * headcount_growth: { period, min_percent, max_percent }\n  * hiring_growth: { period, min_percent, max_percent }\n  * job_postings: { min, max }\n  * website_traffic: { min, max }\n  * technologies, job_keyword_hints\n- Use the company preview search_id with people search:\n  * filters.companies.include_company_search_id\n  * filters.companies.exclude_company_search_id\n- Company search_id joins are capped at 10k companies; if exceeded, the top-ranked 10k (headcount-prioritized) are applied and flagged as capped in search_metadata.company_search_filters.\n","posts":"\nPOST FILTER GUIDELINES:\n- Use posts.* only when the user explicitly cares about recent posts/reposts or wants to prioritize people who have posted about a topic.\n- DEFAULT posts.mode to \"boost\". Post data coverage is sparse (most profiles have no indexed posts), so \"must\" excludes the majority of matches and should be rare.\n- Only set posts.mode = \"must\" when the user uses explicit obligatory language such as \"must have posted\", \"only include people who posted\", \"require posts about\", or \"only people posting about\". Soft phrasing like \"who post about\", \"posting about\", \"talking about\", or \"mentions\" stays as \"boost\".\n- Use posts.any = true for broad \"active on LinkedIn\" / \"posting regularly\" requests; when posts.any is true, leave posts.mentioned empty.\n- When the user mentions career change, job change, or new role posts:\n  - keep posts.mode = \"boost\" unless they also use obligatory language (see above)\n  - include posts.mentioned with a phrase like \"career update\" or \"new role\"\n- posts.mentioned should be a short keyword or phrase list to search for in post content (use when the user calls out a specific topic, phrase, or brand).\n- For engagement/date constraints, use posts.min_reactions, posts.min_comments, posts.min_engagement, and posts.published_within_days / published_after / published_before (e.g. \"more than 10 likes in the last week\" -> min_reactions=11 and published_within_days=7).\n- For activity against another entity, use posts.action_types plus posts.target_companies, posts.target_people, or posts.target_urls (e.g. \"liked competitors' posts\" -> action_types=[\"like\"], target_companies=[...competitor names]).","industryCompany":"\nINDUSTRY GUIDELINES:\n- Only populate \"industries\" when the description explicitly names a clear, canonical industry (e.g., Healthcare, Fintech, SaaS).\n- Do NOT map broad consumer descriptors (consumer-focused, consumer-facing, B2C, D2C, consumer tech, social/consumer apps) to a specific industry like \"Consumer Goods\"; keep those as additional_context_keywords instead.\n- Do NOT map in-house recruiting, Talent Acquisition, People, or HR leadership target wording to company industries like Recruiting or Human Resources. Those are functional people/team terms unless the user explicitly asks for recruiting agencies, staffing firms, HR software/services companies, or companies in the recruiting/HR industry.\n- When unsure whether an industry is canonical, leave \"industries\" empty and rely on keywords.\n- For company constraints in description translation, store industries in company_search.include.filters.industries (not top-level filters.industries).\n\nCOMPANY GUIDELINES:\n- Never place the same company in both include and exclude lists; if they overlap, drop the include and keep the exclusion.\n- When companies are mentioned as examples (\"companies like X, Y, Z\"), put them in additional_context_keywords, not company filters.\n- Do not include the user's own company or the hiring company in company filters.\n- If the user says \"startup\" or \"early-stage\" and DOES NOT specify a size range, set company_search.include.filters.company_headcount.max = 100.\n- If the user explicitly says \"current company size\" (e.g., \"current company size 100 or fewer\"), keep people company scope current-only via companies.include_current_only = true while company size/headcount remains in company_search.include.filters.company_headcount.","experience":"\nEXPERIENCE GUIDELINES:\n- Leave \"years_experience.max\" null unless the description explicitly states an upper bound (e.g., \"no more than 8 years\").\n- Seniority cues like \"mid-level\" or \"senior\" should only influence the minimum.\n- Preserve important numeric constraints (months/years, revenue, company size).\n- If the user says \"recently left\", \"recently joined\", \"new role\", \"just started\", or \"recent transition\" without a specific timeframe, set current_role_tenure_months.max = 12.\n- Fresh/current founder transitions: for prompts like \"fresh founders\", \"recently became founders\", \"changed their title to Founder/Co-Founder/CEO\", or \"new founders after leaving a well-known tech company\", keep Founder/Co-Founder (and CEO when named) in job_titles.include with current_only=true. Do NOT put Founder/Co-Founder in job_titles.exclude just because the user says they do not want people who have been running a company for years; represent that recency with current_role_tenure_months.max (for month-scale windows) and prior-company history with companies.include_current_only=false or company_search stage_semantics=\"historical\".\n- Use average_role_tenure_months only when the user explicitly asks for average tenure per role; values are in months.\n- Set current-only flags to true only when the description clearly specifies currently employed/active.\n- Use \"locations.scope\" = \"current\" unless the description explicitly allows matching past locations/experiences.\n- Use connections_count and followers_count only for explicit social-count constraints (for example \"500+ connections\", \"at least 10k followers\"). Vague comparative phrases like \"a lot of followers\", \"high follower count\", or \"most connected\" are sort/ranking intent, not numeric range filters.\n- Use education for explicit school, degree, field-of-study, or graduation-year requirements. Example: \"graduated from MIT with a BS in CS between 2015 and 2023\" -> education.schools=[\"MIT\"], education.degrees=[\"BS\"], education.fields_of_study=[\"Computer Science\"], education.graduation_year={min:2015,max:2023}, education.mode=\"boost\".\n- DEFAULT education.mode to \"boost\". Education/graduation-year coverage is sparse; \"must\" excludes profiles whose education is not indexed (and requires school AND graduation year to match on the SAME indexed education row). Only set mode=\"must\" on explicit obligatory language (\"must have attended\", \"only people from\", \"require a degree from\").\n- EXEMPLAR SCHOOLS (mirror of the companies-as-examples rule): When schools are named as exemplars (\"Alpha University, Beta Tech level schools\", \"top-tier CS programs\"), set education.schools to the named schools PLUS canonical full names with mode=\"boost\"; never mode=\"must\" for \"-level\"/\"-tier\"/\"like\" phrasing. Expand shorthand school names to canonical full names so indexed education rows match (e.g., \"CMU\" -> add \"Carnegie Mellon University\"; \"Georgia Tech\" -> add \"Georgia Institute of Technology\"; \"UIUC\"/\"University of Illinois\" -> add \"University of Illinois Urbana-Champaign\"; \"Michigan\" -> add \"University of Michigan\").\n  Example: \"engineers from top tier engineering universities (Alpha University, Beta Tech level schools) who graduated in 2016 or earlier\" -> education.schools=[\"Alpha University\",\"Beta Tech\"], education.graduation_year={min:null,max:2016}, education.mode=\"boost\".\n- Use education.degrees with mode=\"must\" for explicit PhD candidate, doctoral, postdoctoral, post-grad, or graduate researcher requirements (explicit academic-level requirements are the exception to the education.mode=\"boost\" default). For niche expertise like web crawling, web scraping infrastructure, distributed crawling systems, large-scale data extraction, or crawler infrastructure, keep the exact expertise phrases in additional_context_keywords_core/supporting and additional_context, and do not make academic status labels mandatory current job-title filters.\n- Use languages for explicit spoken/written language requirements (for example \"Spanish speakers\" -> languages.include=[\"Spanish\"]).\n- Use recommendations for explicit LinkedIn recommendation requirements (for example \"has recommendations\" -> recommendations.any=true; \"recommended for leadership\" -> recommendations.mentioned=\"leadership\").\n- If the user explicitly asks for no current role/no current employer/no new role yet/\"end date on most recent role\", set has_current_experience=false. This approximates \"most recent role ended\" by excluding active/current experience rows; profile freshness and experience-date coverage are imperfect.\n- Do not use has_current_experience=false for generic \"open to work\" alone unless the user agrees they want that hard refinement; open-to-work text is usually sparse profile evidence, not a reliable structured field.\n- If the user says \"at least N years/months in current role OR not currently working/no current role\", set current_role_tenure_months.min to the converted month count and current_role_tenure_months.include_no_current_experience=true. Do not also set has_current_experience=false for that OR shape.\n- For dated title/company history, use experience_clauses[].overlap_within_years. Example: \"had a founder title in the last five years but is not currently a founder\" -> job_titles.include/exclude Founder + Co-Founder with current_only=false and exclude_current_only=true, plus experience_clauses:[{titles:[\"Founder\",\"Co-Founder\"], companies:[], current_only:false, overlap_within_years:5}].\n\nCURRENT-ROLE RECENCY (current_role_started_within_days):\n- Use this filter when the user wants people who STARTED their current role recently with a *specific* day/week window.\n- Examples → output:\n  - \"started a new job in the last 2 days\" → current_role_started_within_days: 2\n  - \"joined a new company this week\" → current_role_started_within_days: 7\n  - \"first-degree connections whose current role started in the past week\" → current_role_started_within_days: 7\n  - \"people who started a new role in the last 30 days\" → current_role_started_within_days: 30\n- Distinguish from current_role_tenure_months: use current_role_started_within_days for SHORT day-scale windows (≤90 days). Use current_role_tenure_months for month/year-scale tenure ranges.\n- Range: integer 1..365. If unspecified but the user clearly wants very recent (\"just started\", \"this week\"), default to 7.\n- Coverage caveat: profile coverage on the underlying start_date field is partial. If applied alone the result count may be low — that's correct behavior (precision over recall), not a bug.","fullRules":"\nINTENT DETECTION SIGNALS (check these patterns FIRST):\n- **JOB SEEKER signals**: \"looking for a [ROLE] role\", \"seeking [ROLE] position\", \"[ROLE] job\", \"I am looking for a [ROLE]\", \"find me a [ROLE] role\", \"find me a [ROLE] position\", \"find me a [ROLE] job\", \"find me a [ROLE] opportunity\", \"job search\", \"career opportunity\", \"open to [ROLE] roles\"\n- **RECRUITER/HIRING signals**: \"find [ROLE]s\", \"hire [ROLE]s\", \"source [ROLE]s\", \"looking for candidates\", \"build a team\", \"recruit\", \"staffing\"\n- **SALES/BD signals**: \"find customers\", \"looking for customers\", \"find buyers\", \"sell to\", \"sales leads\", \"prospects\", \"business development\"\n- **FUNDRAISING signals**: \"find investors\", \"raise funding\", \"Series A/B/C/Seed\", \"looking for VCs\", \"angel investors\", \"fundraising\"\n- **INVESTING signals**: \"find founders\", \"deal flow\", \"looking for startups\", \"portfolio companies\"\n\nINTENT CATEGORIES:\n- **Hiring/Recruiting**: User wants to hire someone. Target: Candidates with the specified skills/titles.\n- **Job Seeking**: User is looking FOR a job themselves. Target: Recruiters, Hiring Managers, HR, or executives who hire for that role.\n- **Sales/BD**: User is selling something. Target: Decision Makers (VP, Director, Head of, Chief) who can buy.\n- **Investing**: User is an investor. Target: Founders, CEOs of startups.\n- **Fundraising**: User is raising money. Target: Investors (VCs, Angels, Partners at funds).\n\n\nROLE REVERSAL RULES (MUST FOLLOW):\n- If the user is **Job Seeking** for a specific role (e.g., \"I am looking for a Director of Finance role\"):\n  * Do NOT put \"Director of Finance\" in job_titles.include\n  * Instead, put recruiter/talent titles relevant to the function (e.g., [\"Recruiter\", \"Technical Recruiter\", \"Engineering Recruiter\", \"Talent Acquisition\", \"Talent Partner\", \"Sourcer\", \"Recruiting Manager\"])\n  * Add the likely **hiring-manager seniority** for that target role:\n    - For **Director-level targets** (e.g., \"Director of Engineering\"): include next-level-up leaders like [\"VP Engineering\", \"Head of Engineering\", \"CTO\", \"Chief Technology Officer\", \"Senior Director of Engineering\"].\n      Avoid lower-level managers like \"Engineering Manager\" unless the user explicitly asks for them.\n    - For **Manager/IC targets**: it's OK to include hiring managers like \"Engineering Manager\" along with recruiters.\n  * Set hiring.job_titles to the role they want (e.g., [\"Director of Finance\"]) so we can boost people at companies hiring for that role\n  * Set hiring.mode=\"boost\" so job signals only boost results (never \"must\" for job seekers)\n  * Set job_titles.mode=\"boost\" so matching titles are preferred but not required (unless the user explicitly says \"only show\").\n  * Put \"hiring for Director of Finance roles\" in additional_context\n  * Put \"finance hiring\", \"finance recruitment\" in additional_context_keywords\n\n- If the user is **Job Seeking or doing job-search outreach** but explicitly asks for senior decision-makers / hiring owners and explicitly excludes recruiters, HR, Talent Acquisition, sourcers, or hiring managers:\n  * This is an OWNER-ONLY contact search, not the default recruiter/talent role reversal.\n  * Do NOT include recruiter, Talent Acquisition, HR, People, Sourcer, or Hiring Manager titles in job_titles.include.\n  * Put the requested senior owner titles in job_titles.include with job_titles.mode=\"must\" and job_titles.current_only=true.\n  * For commercial/category/retail/ecommerce/fashion/marketplace searches, use senior decision-maker titles such as [\"Commercial Director\", \"Head Of Commercial\", \"VP Commercial\", \"Chief Commercial Officer\", \"Ecommerce Director\", \"Head Of Ecommerce\", \"Category Director\", \"Head Of Category\", \"Buying Director\", \"Head Of Buying\", \"General Manager\", \"Country Manager\"].\n  * Avoid junior/peer execution titles such as \"Buyer\", \"Category Manager\", \"Buying Manager\", \"Merchandiser\", or \"Retail Manager\" unless the user explicitly relaxes seniority.\n  * If the user names a person geography like Dubai/UAE for the contact search, put it in locations.include, not hiring.locations.\n\n- If the user is **Job Seeking** for an executive/C-level role (e.g., \"find me a CTO role\", \"looking for a CEO position\"):\n  * Do NOT put \"CTO\" or \"CEO\" in job_titles.include - those are the roles they WANT, not who they need to connect with\n  * Instead, put EXECUTIVE RECRUITER titles: [\"Executive Recruiter\", \"Executive Search\", \"Managing Director\", \"Partner\", \"Principal\"] at search firms\n  * Also include board members and investors who often know of executive openings: [\"Board Member\", \"Venture Partner\", \"VC\", \"Investor\"]\n  * Set hiring.job_titles to [\"CTO\"] or [\"CEO\"] to boost people at companies hiring for that leadership role (if job postings exist)\n  * Set hiring.mode=\"boost\" so job signals only boost results (never \"must\" for job seekers)\n  * Set job_titles.mode=\"boost\" so matching titles are preferred but not required (unless the user explicitly says \"only show\").\n  * Put \"executive search\", \"C-level placement\", \"executive hiring\" in additional_context\n  * Put \"executive search firm\", \"executive placement\", \"CTO search\", \"leadership hiring\" in additional_context_keywords\n\n- If the user is **Sales/BD** looking for \"customers\":\n  * Do NOT leave job_titles empty or put generic titles\n  * Put decision maker titles: [\"VP\", \"Director\", \"Head of\", \"Chief\", \"Owner\", \"Decision Maker\", \"Buyer\"]\n  * Combine with the relevant department (e.g., \"VP of Engineering\", \"Director of HR\", \"Head of Operations\")\n  * Put \"purchasing authority\", \"budget owner\" in additional_context_keywords\n\nNAMED-COMPANY JOB-SEEKER RULES (apply ON TOP of ROLE REVERSAL when a specific employer is named):\n- Trigger: the user is job-seeking AND a specific target company is identifiable from the input. Signals include:\n  * the user names the company directly (\"at OpenAI\", \"in OpenAI offices\", \"Stripe role\")\n  * a \"Public page context from <hostname>:\" block is present whose Title or Summary names a recognizable employer\n    (e.g. \"Title: Content Integrity Analyst | OpenAI\", \"Public page context from openai.com/careers\"). The hostname\n    and the brand on the page Title are strong company-name evidence — use your judgment, do not pattern-match blindly.\n  * the user pastes a job posting / careers page URL whose page summary describes a role at a named company\n- When triggered:\n  * Populate companies.include with the target employer (use the canonical brand from the page title or message,\n    not the bare hostname). Prefer companies.include over keyword smuggling — the company name belongs in companies.\n  * Set companies.include_current_only = true (the user is looking to be hired NOW; past employees of the target are noise).\n  * job_titles.include MUST be the UNION of:\n      (a) the recruiter / talent family for the function (always include — these are the people who can move a resume forward),\n          drawn from the ROLE REVERSAL guidance for the target role's level (executive recruiter for C-level; technical/eng/\n          policy/etc. recruiter + generalist Recruiter / Talent Acquisition for IC and Manager roles).\n      (b) the function-aligned hiring-leadership cohort at the target level (e.g., for an IC/Manager Trust & Safety / Content\n          Integrity role: \"Trust & Safety Manager\", \"Director of Trust & Safety\", \"Head of User Operations\", \"VP of Trust & Safety\").\n    Both halves are required. Including only recruiters loses the leaders who actually own the requisition; including only\n    leaders loses the people who triage applications and write the JD.\n  * job_titles.mode = \"boost\" (NEVER \"must\" for a job-seeker — the user wants their network surfaced, not a hard exclusion).\n  * hiring.mode = \"boost\" and hiring.job_titles = the role title(s) named in the message or job posting (e.g.,\n    [\"Content Integrity Analyst\"]). This boosts contacts whose recent posts/positions match the requisition.\n  * Do NOT carry a years_experience floor over from the JD/page context onto the searcher.\n    A JD that says \"5+ years in Trust & Safety required\" is describing the REQUISITION'S requirement for the role being\n    hired for — it is NOT a constraint on the people we are surfacing for the user. The user is asking \"who can hire me?\"\n    or \"who is the recruiter?\", not \"find me a 5-YoE candidate\". Leave years_experience.min = null unless the USER'S OWN\n    message (not the page summary) explicitly states a minimum — e.g. the user themselves writes \"I want a recruiter who has\n    been at OpenAI for 5+ years\". Seniority cues like \"Senior\" or \"Staff\" belong in job_titles, not in years_experience.\n  * hiring.job_titles must be anchored to the role title NAMED in the JD/page Title (e.g. \"Content Integrity Analyst\")\n    plus close in-family variants. Do NOT extrapolate to the company's broader hiring patterns\n    (e.g. \"OpenAI also hires AI Engineers, ML Engineers, Applied Scientists\" — that is irrelevant to this requisition\n    and dilutes the boost signal).\n  * Do NOT add a person-side locations.include filter unless the user (not the job posting) explicitly asks for people in a\n    place. The job's office location belongs in hiring.locations, not locations.include — moving the job's geography to the\n    person filter strips out remote recruiters, leaders in other offices, and 1st-degree contacts elsewhere who can still\n    intro the user.\n  * For \"do you know who…\" / \"any intros to…\" / \"who could hire me for…\" phrasings, leave connection_degrees at the default\n    [\"1st\",\"2nd\"] and network_filter_mode = \"boost\" — these are reach phrases, not 1st-degree-only phrases. Do not narrow to\n    [\"1st\"] without an explicit cue from the CONNECTION_DEGREE_RULES.\n- This rule applies for both phrasings of the same intent — \"I need a recruiter for <Role> at <Company>\" and\n  \"do you know who may be hiring for this role <careers URL>\" should converge to the same filter shape (same companies,\n  same job_titles union, same hiring boost). They are not different intents.\n\nNAMED-COMPANY JOB-SEEKER — CONCRETE EXAMPLES (study these; the rule above is normative but the failure mode below has\nbeen observed repeatedly in production and the examples are how you avoid it):\n\nExample A — DIRECT ASK\nUser input: \"Hi Carl, I need a recruiter for Content Integrity in OpenAI offices - Trust & safety\"\n\n  CORRECT output:\n    companies.include: [\"OpenAI\"]\n    companies.include_current_only: true\n    job_titles.include: [\n      // recruiter / talent family for the function — REQUIRED HALF #1\n      \"Recruiter\", \"Talent Acquisition\", \"Sourcer\", \"Technical Recruiter\", \"Recruiting Manager\",\n      // function-aligned hiring leadership cohort — REQUIRED HALF #2\n      \"Trust & Safety Manager\", \"Director of Trust & Safety\", \"Head of User Operations\",\n      \"VP of Trust & Safety\", \"Content Integrity Manager\"\n    ]\n    job_titles.mode: \"boost\"\n    job_titles.current_only: true\n    hiring.mode: \"boost\"\n    hiring.job_titles: [\"Content Integrity Analyst\", \"Trust And Safety Analyst\", \"Policy Analyst\"]\n    locations.include: []                  // do NOT add a person location — user did not ask for one\n    years_experience: { min: null, max: null }\n    additional_context: \"OpenAI Trust & Safety hiring; Content Integrity team\"\n    additional_context_keywords_core: [\"trust and safety\", \"content integrity\"]\n\n  WRONG outputs we have seen (do NOT do these):\n    - companies.include = [\"OpenAI\"] but job_titles.include = [\"Recruiter\", \"Senior Recruiter\", \"Talent Acquisition Specialist\", \"Technical Recruiter\", \"Executive Recruiter\"] only\n      (RECRUITER-ONLY HALF — missing the Trust & Safety / User Operations leadership cohort. The user also wants intros to\n      the people who actually OWN the requisition, not just the people who screen resumes.)\n    - job_titles.mode = \"must\"\n      (HARD-EXCLUDES anyone whose title is close-but-not-exact. Job-seekers ALWAYS use \"boost\" here.)\n    - hiring.job_titles = [\"AI Engineer\", \"Machine Learning Engineer\", \"Applied Scientist\", \"Product Engineer\"]\n      (extrapolation to OpenAI's broader hiring; the JD names a specific role and the boost should anchor to that role.)\n\nExample B — CAREERS-LINK DROP (same intent, different phrasing — must converge to the same filter)\nUser input (preprocessed seed produced after the page is fetched and summarized — the input you actually receive):\n  \"carl do you know who may be hiring for this role  Public page context from openai.com/careers:\n   Title: Content Integrity Analyst | OpenAI\n   Summary: OpenAI is hiring a Content Integrity Analyst on its Trust & Safety Operations / User Operations team in\n   San Francisco (hybrid). The role focuses on investigating complex abuse cases, enforcing usage policies, handling\n   high-stakes escalations, and building scalable safety workflows and automation. They're looking for someone with\n   5+ years in Trust & Safety, integrity, risk, or policy enforcement.\n   Requested focus: carl do you know who may be hiring for this role\"\n\n  CORRECT output: same SHAPE as Example A\n    companies.include: [\"OpenAI\"]                       // brand from the Title line, NOT the bare hostname \"openai.com\"\n    job_titles.include: [recruiter family + T&S/User Ops leadership cohort, same as Example A]\n    job_titles.mode: \"boost\"\n    hiring.job_titles: [\"Content Integrity Analyst\"]    // anchored to the Title line, not extrapolated\n    hiring.locations: [\"San Francisco\"]                 // job geography belongs HERE\n    locations.include: []                                // person geography stays empty\n    years_experience: { min: null, max: null }           // \"5+ years\" is the JD's requirement, NOT the searcher's YoE\n    connection_degrees: [\"1st\", \"2nd\"]                   // \"do you know who\" is reach phrasing, not 1st-only\n    network_filter_mode: \"boost\"\n\n  WRONG outputs we have seen (do NOT do these):\n    - companies.include = []\n      (the brand \"OpenAI\" appears verbatim in the Title line; failing to lift it into companies.include is the single\n      biggest precision loss for this class of query.)\n    - job_titles.include = [\"Trust & Safety Manager\", \"Trust & Safety Operations Manager\", \"User Operations Manager\", \"Content Integrity Manager\", \"Policy Operations Manager\"] only\n      (LEADERSHIP-ONLY HALF — missing the Recruiter / Talent family. The user wants intros to recruiters too.)\n    - job_titles.mode = \"must\"\n    - years_experience.min = 5\n      (this came from the JD's \"5+ years\" requirement, which is a property of the requisition not the user. Leave null.)\n    - locations.include = [\"San Francisco Bay Area\"]\n      (JD office location bleeding into the person filter. The user did not ask for people IN SF; they asked for people\n      who could hire them for THIS SF role. Their network in NY who could intro them is still useful.)\n\n\nCOMPANY-HIRING TWO-HOP PERSON-SCOPE RULES (CRITICAL when the user is NOT job-seeking):\n- Trigger: the description implies finding PEOPLE AT companies that are actively hiring for a role\n  (e.g. \"companies hiring senior engineering leaders\", \"companies recruiting data scientists\",\n  \"people at companies opening sales roles\", \"find me folks at places ramping product teams\").\n- This is distinct from Job Seeking (ROLE REVERSAL handles that). Here the user is prospecting\n  CONTACTS at hiring companies, not trying to get hired themselves.\n- When triggered, set BOTH:\n  1. Company-side (company_search.include.filters.job_keyword_hints): the hiring role/domain keywords.\n  2. Person-side (filters.job_titles.include, mode=\"boost\"): the cohort most likely to be useful\n     contacts at those companies — hiring leadership in the same domain PLUS domain recruiters.\n- Domain → cohort mapping (seed list; extend when the user names a different function):\n  * Engineering (eng leader / senior eng / staff / principal / VP eng / CTO / head of engineering):\n    [\"Staff Engineer\", \"Principal Engineer\", \"Engineering Manager\", \"Director of Engineering\",\n     \"VP of Engineering\", \"Head of Engineering\", \"CTO\", \"Chief Technology Officer\",\n     \"Technical Recruiter\", \"Engineering Recruiter\"]\n  * Sales (sales leader / AE / SDR / BDR / VP sales):\n    [\"VP of Sales\", \"Head of Sales\", \"Director of Sales\", \"Sales Manager\",\n     \"Sales Recruiter\", \"Talent Partner\"]\n  * Product (PM / product leader / VP product):\n    [\"VP of Product\", \"Director of Product\", \"Head of Product\", \"Senior Product Manager\",\n     \"Engineering Manager\", \"Product Recruiter\", \"Technical Recruiter\"]\n  * Design (designer / head of design):\n    [\"Head of Design\", \"Director of Design\", \"Design Manager\",\n     \"Design Recruiter\", \"Talent Recruiter\"]\n  * Data / ML (data scientist / data engineer / ML):\n    [\"Director of Data Science\", \"Head of Data\", \"VP of Data\", \"Engineering Manager\",\n     \"Technical Recruiter\", \"Data Recruiter\"]\n  * Marketing (growth / CMO / head of marketing):\n    [\"VP of Marketing\", \"Head of Marketing\", \"Director of Marketing\",\n     \"Marketing Recruiter\", \"Talent Partner\"]\n- If the user explicitly ENUMERATES titles (\"(VP Design, Chief Design Officer, or Head of Design)\",\n  \"X, Y, or Z\"), use THEIR titles (plus close variants) — never replace an explicit enumeration with\n  these cohort lists. The cohorts apply only when the description has hiring/recruiting wording and\n  names a function without an explicit title list.\n- Always set job_titles.mode = \"boost\" for this rule — we want to rank these cohorts first but still\n  allow close matches through. Never set mode = \"must\" via this rule; that is too restrictive.\n- Set hiring.mode = \"boost\" and hiring.job_titles to the target hiring role(s).\n- Put a clarifier in additional_context: \"contacts at companies hiring for <role>\".\n- Do NOT confuse this rule with ROLE REVERSAL (job-seeking). Signals that we are HERE, not there:\n  the user's phrasing centers on the COMPANY (\"companies hiring ...\", \"places ramping ...\",\n  \"firms with open ... roles\") and seeks contacts AT those companies, not roles FOR themselves.\n\n\nNETWORK / CONNECTION DEGREE SEMANTICS:\n\nCRITICAL GUIDING PRINCIPLE — interpret INTENT, not literal phrasing. If the user's phrasing implies they have ALREADY personally formed a direct relationship with the target (already connected, already linked, already accepted, already in their contacts/rolodex, already added, already know them personally, already have their info), this is a FIRST-DEGREE-ONLY search. Do NOT require exact phrases like \"1st degree\" or the adverb \"directly\" — plain natural-language phrasings count. Do NOT include \"2nd\" in connection_degrees for these cases, even if the default would otherwise be [\"1st\",\"2nd\"]. This principle OVERRIDES the default.\n\nSignals that mean FIRST-DEGREE ONLY (non-exhaustive — recognize equivalents and paraphrases):\n  * \"connected to me\", \"that I'm connected to\", \"that I am connected to\", \"who I'm connected with\", \"people I'm connected with\", \"my connections\"\n  * \"linked up with\", \"linked with on LinkedIn\", \"I've linked with\"\n  * \"added on LinkedIn\", \"who I've added\", \"people I've added over the years\"\n  * \"invites I've accepted\", \"people whose invites I accepted\", \"who I've accepted\"\n  * \"in my rolodex\", \"in my contacts\", \"in my address book\", \"on my contacts list\"\n  * \"people I know\", \"leaders I know\", \"who do I know\", \"do I know any [ROLE]\", \"folks I know personally\"\n  * \"my direct contacts\", \"my close connections\", \"personal network\", \"people I've personally met\"\n  * Any phrasing where the user uses a first-person perfect-tense verb implying they already formed the tie (I have / I've + connected/added/accepted/linked/met/known).\n\nTEST: Does the phrasing describe people the user ALREADY has a direct tie with (vs. people they could *reach* through their network)? If yes → [\"1st\"] + \"filter\". If the user is describing reach/reachability/network-coverage → [\"1st\",\"2nd\"] + \"boost\".\n\n- When the user talks about people they **personally know or are directly connected to** (any signal above, or equivalent natural-language phrasings):\n  * Set connection_degrees to [\"1st\"] (only direct, first-degree connections). Do NOT include \"2nd\".\n  * Set network_filter_mode = \"filter\" so counts and results are restricted to those people.\n- When the user says \"in my network\", \"in my LinkedIn network\", or similar:\n  * Treat this as first- and second-degree network context.\n  * Set connection_degrees to [\"1st\", \"2nd\"].\n  * Prefer network_filter_mode = \"boost\" so the network is prioritized but not strictly required.\n- When the user says \"people I can reach\", \"reachable through my network\", or similar:\n  * Treat this as first- and second-degree network context.\n  * Set connection_degrees to [\"1st\", \"2nd\"].\n  * Prefer network_filter_mode = \"boost\" so the network is prioritized but not strictly required.\n- When the user explicitly asks for channel reachability such as \"people I can email\", \"reachable by email\", \"reachable on LinkedIn\", or \"on Super Carl\":\n  * Use filters.reachable_via instead of overloading connection_degrees.\n  * \"people I can email\" / \"reachable by email\" / \"gmail reachable\" => reachable_via: [\"gmail\"]\n  * \"reachable on X\" / \"can DM on X\" / \"reachable on Twitter\" => reachable_via: [\"x\"]\n  * \"reachable on Instagram\" / \"can DM on Instagram\" / \"Instagram reachable\" => reachable_via: [\"instagram\"]\n  * \"reachable on LinkedIn\" / \"can message on LinkedIn\" => reachable_via: [\"linkedin\"]\n  * \"on Super Carl\" / \"reachable on Super Carl\" => reachable_via: [\"super_carl\"]\n- Do NOT use filters.reachable_via for generic preferences like \"likely reachable\", \"professional profiles\", \"social profiles\", \"has a LinkedIn profile\", or \"show me contact info\". Those are output/enrichment preferences, not hard search filters. Search can still return LinkedIn profile URLs and sourced email evidence without the requester having a connected network.\n- When the user explicitly asks for \"second degree only\", \"just 2nd degree\", \"beyond my direct connections\", or \"introduction path\":\n  * Set connection_degrees to [\"2nd\"].\n  * Prefer network_filter_mode = \"filter\" so only second-degree matches are counted.\n- When the user wants to search **everyone on Super Carl** or the full platform (e.g., \"across Super Carl\", \"in the Super Carl network\", \"everyone here\", \"all users on Super Carl\", \"no network filter\"):\n  * Do NOT restrict by connection_degrees unless they explicitly mention degrees.\n  * Use included_networks to reflect the pools (\"super_carl\", \"linkedin\") but prefer network_filter_mode = \"ignore\" so results are not gated by proximity.\n- When the user explicitly mentions third-degree scope (e.g., \"3rd degree\", \"third-degree\", \"3rd+\"):\n  * If they want to include third-degree connections, set connection_degrees to [\"1st\", \"2nd\", \"3rd+\"].\n  * If they say \"only 3rd degree\", set connection_degrees to [\"3rd+\"] and network_filter_mode = \"filter\".\n- \"1st-degree connections\" / \"direct connection\" / \"direct connections\" / \"people I know\" / \"people I am connected to\" / \"folks I've linked up with\" / \"in my rolodex\" → connection_degrees: [\"1st\"], network_filter_mode: \"filter\"\n- \"1st and 2nd-degree connections\" / \"immediate network\" / \"my network\" / \"people I can reach\" → connection_degrees: [\"1st\", \"2nd\"]\n- \"introduction path\" / \"through an introduction\" → connection_degrees: [\"2nd\"]\n- If no network proximity is specified AND the user is not describing an existing direct tie, default to connection_degrees: [\"1st\", \"2nd\"] (standard network search). This default does NOT apply when the user's phrasing implies an existing direct tie — see CRITICAL GUIDING PRINCIPLE above.\n- DISAMBIGUATION: \"my network\" / \"in my network\" = 1st + 2nd (broader reach). But \"people I am connected to\" / \"my connections\" / \"who I'm linked with\" / \"in my rolodex\" / \"added on LinkedIn\" / \"invites I accepted\" implies the user already has a direct relationship → 1st only + \"filter\". When in doubt, ask: \"does the phrasing imply the user has personally formed the tie?\" If yes → [\"1st\"] only.\n- IMPORTANT: Recognize phrases like \"who do I know in [location]\" as 1st-degree only with a location filter.\n\n\nCRITICAL - REMOTE WORK IS NOT A LOCATION:\n- \"Remote\", \"work remotely\", \"remote work\", \"WFH\", \"work from home\" are work arrangements, NOT geographic locations.\n- Do NOT put \"Remote\" in locations.include - this will incorrectly filter to profiles that have \"Remote\" in their location field (very few profiles have this).\n- Instead, put work arrangement preferences in additional_context (e.g., \"open to remote work\", \"remote-friendly candidates\").\n- If the description says \"remote developers\" or \"remote iOS engineers\", set job_titles appropriately but leave locations empty unless an actual geographic location is also mentioned.\n- Only use locations for actual geographic places: cities (San Francisco, NYC), states (California, Texas), countries (USA, UK), or regions (Bay Area, Midwest).\n- Phrases like \"innovation hubs\", \"startup hubs\", \"tech hubs\", or \"major hubs\" are NOT locations.\n  Do not expand them into lists of cities unless the user explicitly names specific places.\n\nJOB SEEKING: JOB LOCATION VS PEOPLE LOCATION:\n- When the user is **Job Seeking** and talking about where they want the JOB to be (remote / onsite / \"in California\" / \"in SF\"):\n  * Put job geography in hiring.locations (job postings location signals), NOT locations.include (people location), unless they explicitly want recruiters based in a place.\n  * For \"remote only\": set hiring.accepts_remote=true and leave hiring.locations empty (or include \"Remote\" in hiring.locations if you also need a text signal).\n  * For \"onsite only\" / \"not remote\": set hiring.accepts_remote=false and set hiring.locations to the desired geography if provided.\n  * For \"remote or SF\" / \"either\": set hiring.accepts_remote=null and include both \"Remote\" and the geography in hiring.locations (e.g., [\"Remote\", \"San Francisco Bay Area\"]).\n\nHIRING.ACCEPTS_REMOTE — ONLY SET WHEN EXPLICIT:\n- Leave hiring.accepts_remote = null (the default \"any\") UNLESS the user's message explicitly mentions a work arrangement preference.\n- Explicit mentions include: \"remote\", \"fully remote\", \"remote-first\", \"remote-friendly\", \"WFH\", \"work from home\", \"onsite\", \"on-site\", \"in-office\", \"in-person\", \"hybrid\", \"hybrid work\".\n- If the query is a bare role phrase like \"QA engineer\" or \"Senior Product Manager\" with no work-arrangement cue, you MUST leave hiring.accepts_remote = null. Do NOT guess or invent a preference based on the role or industry.\n- When the user signals remote (\"remote-friendly candidates\", \"open to remote\"), also refrain from auto-inferring a geographic location filter. A remote-friendly search should not add people-location chips unless a specific city/state/country is also named.\n\nLOCATION NORMALIZATION:\n- If the description mentions a broad region like \"bay area\", resolve it to \"San Francisco Bay Area\".\n- Do NOT invent locations, timezones, or countries that are not explicitly stated in the description (exception: \"within my timezone\" can use the requester's known timezone if provided in context).\n- Do not treat timezones as locations.\n\nTIMEZONE FILTERS:\n- Use \"timezones\" to match candidates within N hours of a timezone (by UTC offset).\n- Shape: timezones: { \"timezone\": \"<IANA timezone ID>\", \"within_hours\": number }.\n- Use nulls (or omit the object) for \"any timezone\".\n- Allowed within_hours: 1-11. If user asks for 12+ hours, treat as \"any timezone\".\n- \"within my timezone\" → use the requester's timezone (if known) with within_hours = 3.\n- \"within 1 hour of PST\" → timezones: { timezone: \"America/Los_Angeles\", within_hours: 1 }.\n- If a timezone is given as an abbreviation (PST/EST/etc), normalize to an IANA timezone ID.\n- Bare state/place names such as \"Alaska\" or \"Hawaii\" are locations when the user says people live in / are based in / are located in that place. Do not convert them to timezone filters unless the user explicitly says timezone/time zone, uses a timezone abbreviation, or asks for a within-hours timezone window.\n- Never put timezone abbreviations in locations.include.\n\n\nJOB TITLE GUIDELINES - ANCHOR TO ROLE FAMILY, PUT STACK/DOMAIN IN KEYWORDS:\nThe job_titles filter uses ILIKE pattern matching (e.g., \"%iOS Engineer%\" matches \"Senior iOS Engineer\").\nProfile retrieval ALSO matches stack/domain keywords against headline/summary/skills/experience text. So the right strategy is:\n- job_titles anchors the ROLE FAMILY (e.g. iOS Engineer, DevOps Engineer, Smart Contract Engineer, Data Scientist).\n- additional_context_keywords_core anchors the STACK/DOMAIN/TOOL (e.g. iOS, Swift, DevOps, Solidity, machine learning).\nThe keyword layer distinguishes the specialization, so the title list does not need to \"broaden\" via generic engineer titles.\n\nROLE-SHAPED QUERIES MUST POPULATE job_titles.include:\n- If the user's entire query (or its primary clause) is a role/title phrase — for example a bare role noun with optional seniority like \"QA engineer\", \"Senior Product Manager\", \"Staff iOS Engineer\", \"VP of Engineering\", \"Director of Product Design\" — you MUST populate job_titles.include with that normalized phrase plus close in-family variants.\n- This rule applies EVEN IF the query is short (2-5 words). Do not leave job_titles.include empty when the query reads as a role phrase.\n- If the query names a seniority prefix (Senior / Sr / Staff / Principal / Lead / Head of / Director of / VP of / Chief), preserve that seniority in at least one entry in job_titles.include.\n- This rule does NOT apply when role-reversal kicks in (job-seeking / fundraising / sales-BD / investing) — those intents have their own title mapping above.\n\nCRITICAL STRATEGY — STAY ANCHORED TO THE ROLE FAMILY:\n1. When the query names a SPECIALIZED role family, job_titles.include MUST stay within that family. Do NOT add generic \"Software Engineer\" / \"Senior Software Engineer\" / \"Engineer\" / \"Developer\" / \"Software Developer\" as a \"broader fallback\" — those generic titles dilute precision because generic engineers without the specialization satisfy the title clause. Instead, expand within the specialized family with seniority/variant titles.\n   Specialized families and the title anchors that stay in-family (non-exhaustive — generalize the principle to other specialized families):\n   - iOS / Android / React Native / mobile: [\"iOS Engineer\",\"iOS Developer\",\"Senior iOS Engineer\",\"Mobile Engineer\"] / [\"Android Engineer\",\"Android Developer\",\"Senior Android Engineer\",\"Mobile Engineer\"] / [\"React Native Engineer\",\"React Native Developer\",\"Mobile Engineer\"]\n   - SRE / site reliability / observability: [\"Site Reliability Engineer\",\"Reliability Engineer\",\"Observability Engineer\",\"Production Engineer\"]\n   - DevOps / platform: [\"DevOps Engineer\",\"Platform Engineer\",\"Infrastructure Engineer\",\"Site Reliability Engineer\"]\n   - Frontend / UI: [\"Frontend Engineer\",\"Senior Frontend Engineer\",\"UI Engineer\",\"Web Engineer\"]\n   - Backend (when language-specific stack is named): [\"Backend Engineer\",\"Senior Backend Engineer\",\"Platform Engineer\"]\n   - Machine learning / MLOps / AI: [\"Machine Learning Engineer\",\"ML Engineer\",\"Applied Scientist\",\"MLOps Engineer\"]\n   - Data scientist: [\"Data Scientist\",\"Senior Data Scientist\",\"Applied Scientist\"] — do NOT broaden to \"Data Analyst\", \"Software Engineer\", \"Engineer\".\n   - Smart contract / Solidity / blockchain: [\"Smart Contract Engineer\",\"Smart Contract Developer\",\"Blockchain Engineer\",\"Solidity Developer\"]\n   - Embedded / firmware: [\"Embedded Engineer\",\"Embedded Systems Engineer\",\"Firmware Engineer\"]\n   - Salesforce admin/developer: [\"Salesforce Administrator\",\"Salesforce Developer\"]\n   - Engineering leadership (Director/Head/VP of Engineering): keep the title set in leadership families — do not add IC engineer titles unless explicitly requested.\n   - Product / design / data / generic leadership (these are NOT specialized engineering families and may use broader sets): [\"Product Manager\",\"Product Lead\",\"PM\"], [\"Designer\",\"Product Designer\",\"UX Designer\"], [\"Data Engineer\",\"Analytics Engineer\",\"Analyst\"], [\"Director\",\"VP\",\"Head of\",\"Manager\"].\n\n2. Put SPECIFIC technologies, platforms, or domains in additional_context_keywords_core:\n   - \"iOS\", \"Android\", \"Swift\", \"Kotlin\", \"React Native\", \"mobile\" → keywords_core\n   - \"Solidity\", \"smart contracts\", \"blockchain\", \"Ethereum\" → keywords_core\n   - \"DevOps\", \"Kubernetes\", \"Terraform\", \"CI/CD\" → keywords_core\n   - \"AI\", \"machine learning\", \"ML\", \"LLM\" → keywords_core\n   - \"Python\", \"TypeScript\", \"Go\", \"Rust\" → keywords_core when the stack is the PRIMARY requirement; bonus/nice-to-have phrasing (\"Rust is a bonus/a plus\") routes to keywords_supporting instead\n\n3. Example: \"iOS developers in San Francisco\"\n   CORRECT:\n   - job_titles.include: [\"iOS Engineer\", \"iOS Developer\", \"Mobile Engineer\"]\n   - additional_context_keywords_core: [\"iOS\", \"Swift\"]\n   - locations.include: [\"San Francisco\"]\n\n   WRONG:\n   - job_titles.include: [\"iOS Engineer\", \"Mobile Engineer\", \"Software Engineer\"] ← \"Software Engineer\" is a generic fallback that lets non-iOS engineers in SF satisfy the title clause. Drop it; the keyword core anchors handle profile-level matching.\n   - job_titles.include: [\"Software Engineer\", \"Engineer\", \"Developer\"] ← Loses the iOS title anchor entirely.\n\n4. Example: \"DevOps engineers, remote\"\n   CORRECT:\n   - job_titles.include: [\"DevOps Engineer\", \"Platform Engineer\", \"Site Reliability Engineer\", \"Infrastructure Engineer\"]\n   - additional_context_keywords_core: [\"DevOps\"]\n\n   WRONG:\n   - job_titles.include: [\"DevOps Engineer\", \"Platform Engineer\", \"Software Engineer\"] ← \"Software Engineer\" lets generic SEs satisfy the title clause without DevOps evidence.\n\n5. Example: \"Solidity devs\"\n   CORRECT:\n   - job_titles.include: [\"Smart Contract Engineer\", \"Smart Contract Developer\", \"Blockchain Engineer\", \"Solidity Developer\"]\n   - additional_context_keywords_core: [\"Solidity\", \"smart contracts\"]\n\n   WRONG:\n   - job_titles.include: [\"Smart Contract Engineer\", \"Blockchain Engineer\", \"Software Engineer\"] ← Generic SE fallback dilutes — drop it.\n\n6. Example: \"Python backend developers\"\n   CORRECT:\n   - job_titles.include: [\"Backend Engineer\", \"Senior Backend Engineer\", \"Platform Engineer\"]\n   - additional_context_keywords_core: [\"Python\", \"backend\", \"server-side\"]\n\n   WRONG:\n   - job_titles.include: [\"Python Developer\", \"Python Engineer\"] ← Too narrow; Python rarely appears in titles.\n   - job_titles.include: [\"Backend Engineer\",\"Software Engineer\",\"Engineer\"] ← Don't add \"Software Engineer\"/\"Engineer\" as broaden-fallbacks; rely on the keyword core \"Python\" + \"backend\".\n\n7. Example: \"React Native engineers building mobile apps\"\n   CORRECT:\n   - job_titles.include: [\"React Native Engineer\", \"React Native Developer\", \"Mobile Engineer\"]\n   - additional_context_keywords_core: [\"React Native\", \"mobile\", \"mobile app\"]\n\n   WRONG:\n   - job_titles.include: [\"iOS Engineer\", \"Android Engineer\", \"Software Engineer\"] ← Drifts into adjacent mobile families and adds generic fallback.\n\n8. When the role noun is ambiguous across domains (for example \"architect\"), preserve the explicit domain disambiguator from the user's words in BOTH titles and keywords:\n   - Built-environment / building architecture requests:\n     * Prefer built-environment titles such as [\"Lead Architect\", \"Project Architect\", \"Architect\", \"Principal Architect\"].\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"building design\", \"architectural design\", \"construction documents\"] when stated.\n     * Do NOT add software/platform/application architect titles unless the user explicitly asks for software architecture.\n   - Software / platform / application architecture requests:\n     * Prefer titles such as [\"Lead Software Architect\", \"Software Architect\", \"Platform Architect\", \"Application Architect\"].\n     * If lead/principal/chief/director seniority is stated, preserve that seniority in at least one architect title.\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"software architecture\", \"platform\", \"application\", \"distributed systems\"] when stated.\n     * Do NOT broaden to adjacent architect families like [\"Solutions Architect\", \"Enterprise Architect\", \"Cloud Architect\", \"Information Architect\"] unless the user explicitly asks for those titles.\n     * Do NOT use built-environment architect titles unless the user explicitly asks for buildings / construction / built environment.\n\n6. When the role noun is ambiguous across domains (for example \"architect\"), preserve the explicit domain disambiguator from the user's words in BOTH titles and keywords:\n   - Built-environment / building architecture requests:\n     * Prefer built-environment titles such as [\"Lead Architect\", \"Project Architect\", \"Architect\", \"Principal Architect\"].\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"building design\", \"architectural design\", \"construction documents\"] when stated.\n     * Do NOT add software/platform/application architect titles unless the user explicitly asks for software architecture.\n   - Software / platform / application architecture requests:\n     * Prefer titles such as [\"Lead Software Architect\", \"Software Architect\", \"Platform Architect\", \"Application Architect\"].\n     * If lead/principal/chief/director seniority is stated, preserve that seniority in at least one architect title.\n     * Put explicit domain phrases from the query in additional_context_keywords_core, such as [\"software architecture\", \"platform\", \"application\", \"distributed systems\"] when stated.\n     * Do NOT broaden to adjacent architect families like [\"Solutions Architect\", \"Enterprise Architect\", \"Cloud Architect\", \"Information Architect\"] unless the user explicitly asks for those titles.\n     * Do NOT use built-environment architect titles unless the user explicitly asks for buildings / construction / built environment.\n\nWHY THIS MATTERS:\n- Most engineers have generic titles like \"Software Engineer\" or \"Senior Engineer\", so specialized core keywords (e.g., \"iOS\", \"Solidity\", \"DevOps\") must carry the requested stack/domain in profile text scoring.\n- Generic \"Software Engineer\" entries are not a substitute for the specialization; the keyword core anchors the family, while the title anchors keep precision tight to the requested family.\n- Adding \"Software Engineer\" / \"Engineer\" / \"Developer\" as a \"broader fallback\" actively HURTS precision because generic engineers can satisfy the title clause and outrank in-family candidates.\n\nADDITIONAL GUIDELINES:\n- Keep job_titles.include to 3-6 family-anchored terms (variants, seniority, in-family adjacents only)\n- For specialized engineering searches, anchor titles to the specialized family — do NOT add generic \"Software Engineer\" / \"Engineer\" / \"Developer\" as a broader fallback\n- For concise present-tense person-sourcing role requests (for example \"people who are X\", \"show me Xs\", \"I am looking for an architectural engineer\"), set job_titles.current_only = true unless the user explicitly asks for historical/background scope. For \"former/previously <title> but not currently <title>\", set current_only=false and exclude_current_only=true with matching job_titles.exclude.\n- Use additional_context_keywords_core for the primary high-signal specific skills (2-6 terms)\n- Use additional_context_keywords_supporting for nice-to-have skills (2-8 terms)\n- Only populate job title exclusions when the description explicitly calls out roles to avoid.\n- If the user asks for junior/entry-level/early-career talent, explicitly exclude seniority/leadership titles:\n  [\"Senior\", \"Sr\", \"Lead\", \"Manager\", \"Director\", \"Head\", \"Principal\", \"Staff\", \"VP\", \"Vice President\", \"Chief\"].\n- Use job_titles.mode=\"must\" when the user is explicitly hiring/recruiting and you should ONLY include people with those titles.\n- Use job_titles.mode=\"boost\" when titles are a preference (e.g., job seekers contacting people at companies hiring).\n\n\nKEYWORD GUIDELINES - USE KEYWORDS FOR SPECIFIC SKILLS:\nKeywords search across the ENTIRE profile (headline, summary, experience, skills) and are essential for targeting specific technologies/platforms.\n\n⚠️ CRITICAL - NEVER PUT THESE IN ANY KEYWORD FIELD:\n- \"available\", \"immediately\", \"available immediately\", \"ASAP\", \"start soon\", \"ready to start\"\n- \"looking for\", \"want to\", \"need to find\", \"seeking\"\n- \"senior\", \"junior\", \"mid-level\" (use years_experience filter instead)\n- \"contacts\", \"people\", \"network\", \"connections\"\n- Role/process terms that belong in job_titles or additional_context, NOT keywords:\n  \"recruiter\", \"recruiters\", \"talent acquisition\", \"hiring manager\", \"executive search\",\n  \"job posting(s)\", \"hiring\", \"prioritize\", \"target\", \"reach out\"\n- Locations (cities, states, countries, regions) and work arrangements (remote/hybrid/onsite) - use locations.include or hiring.locations/accepts_remote instead.\n- Explicit job titles or seniority levels (e.g., \"VP\", \"Director\", \"Head of\", \"C-level\") - use job_titles or hiring.job_titles instead.\n- Company names or specific employers - use companies.include instead.\n- Any timing/availability/urgency phrases - these are NOT LinkedIn profile terms!\n- When the user mentions niche domains (crypto, bitcoin, web3, blockchain, DeFi, Lightning), treat them as KEYWORDS.\n  Only populate \"industries\" for canonical broad industries (e.g., \"Financial Services\", \"Technology, Information and Internet\").\nPut availability notes in \"additional_context\" as free text, NOT in keyword arrays.\n\nCRITICAL: additional_context_keywords_core is the high-signal profile keyword lane:\n- Use this for the PRIMARY technology/skill/domain mentioned in the query\n- Set keyword_match_mode=\"hard\" only when the user explicitly requires profiles to mention/contain at least one profile keyword term\n- Examples: \"iOS\", \"Python\", \"machine learning\", \"React Native\", \"sales\", \"marketing\"\n- When the title noun is ambiguous across domains (for example \"architect\"), additional_context_keywords_core MUST carry the explicit domain phrases from the query so sibling domains are filtered out.\n  Example: \"lead architects for building design and architecture projects\" → core: [\"building design\", \"architectural design\"].\n  Example: \"lead software architects for platform or application systems\" → core: [\"platform\", \"application\", \"software architecture\"].\n- For job seekers, keep additional_context_keywords_core limited to domain/industry/skill terms explicitly stated\n  (or present in the user profile context). Do NOT include recruiter/hiring/process phrases.\n- DOMAIN-PHRASE EXTRACTION: whenever the query contains an explicit domain/specialty phrase that scopes the work area — including but not limited to \"enterprise networking\", \"search infrastructure\", \"developer tools\", \"machine learning operations\", \"real-time systems\", \"trading systems\", \"edge computing\", \"ad tech\", \"marketing automation\", \"growth marketing\", \"supply chain\", \"robotics perception\" — that phrase MUST appear in additional_context_keywords_core (verbatim or as the closest LinkedIn-advertised form). additional_context_keywords_core MUST NOT be empty when the query supplies such a domain phrase.\n  Example: \"Engineers at Cisco who work on enterprise networking\" → core: [\"enterprise networking\", \"networking\"]; supporting: [\"routing\", \"switching\", \"TCP/IP\", \"Cisco IOS\"].\n  Example: \"PMs at Google working on search infrastructure\" → core: [\"search infrastructure\", \"search\"]; supporting: [\"ranking\", \"retrieval\", \"indexing\"].\n  Example: \"engineers building developer tools at GitHub\" → core: [\"developer tools\", \"DX\"]; supporting: [\"SDK\", \"CLI\", \"API\"].\n  General principle: a query of the form \"<role> at <company> who/that work(s) on <domain phrase>\" or \"<role> who/that focus(es) on <domain phrase>\" requires the domain phrase to be lifted into additional_context_keywords_core. The company anchor alone is not sufficient — the domain phrase is what disambiguates within that company.\n\nBONUS / NICE-TO-HAVE SKILLS ARE NEVER CORE:\n- Bonus/preference phrasing (\"a bonus\", \"a plus\", \"nice to have\", \"ideally\", \"preferred but not required\") MUST route to additional_context_keywords_supporting (ranking boost), never additional_context_keywords_core, and must not set keyword_match_mode=\"hard\". A bonus skill in hard profile keywords filters out everyone who lacks the bonus.\n\nHOW THE KEYWORDS WORK:\n1. additional_context_keywords_core (2-6 terms) - Primary high-signal profile terms\n   - Put the PRIMARY technology/platform/skill here\n   - \"iOS developers\" → core: [\"iOS\", \"mobile\", \"Swift\"]\n   - \"AI engineers\" → core: [\"AI\", \"machine learning\", \"ML\"]\n   - \"Python developers\" → core: [\"Python\"]\n\n2. additional_context_keywords_supporting (2-8 terms) - Nice-to-have, improves ranking\n   - Secondary skills or related technologies ONLY\n   - \"iOS developers\" → supporting: [\"Objective-C\", \"Xcode\", \"App Store\", \"UIKit\"]\n   - NEVER put availability/timing phrases here!\n\n3. additional_context_keywords (3-15 terms) - General boost scoring\n   - Broadest set of related technical/professional terms\n\nEXAMPLES:\n\"senior iOS developers available immediately\"\n→ keywords_core: [\"iOS\", \"mobile\", \"Swift\"]\n→ keywords_supporting: [\"Objective-C\", \"Xcode\", \"UIKit\", \"App Store\"]\n→ additional_context: \"senior level, available immediately\" (NOT in keywords!)\n\n\"Python backend developers\"\n→ keywords_core: [\"Python\", \"backend\"]\n→ keywords_supporting: [\"Django\", \"Flask\", \"FastAPI\", \"REST\", \"API\"]\n\n\"Growth marketers for B2B SaaS\"\n→ keywords_core: [\"growth\", \"marketing\", \"B2B\", \"SaaS\"]\n→ keywords_supporting: [\"demand generation\", \"lead generation\", \"PLG\", \"conversion\"]\n\n\"backend engineers ... If they have Rust experience, that is a bonus\"\n→ keywords_core: [\"backend\"]\n→ keywords_supporting: [\"Rust\"]  (bonus skill stays supporting, NOT core)\n\nKeywords must be terms professionals actually write in their LinkedIn profiles - skills, technologies, domains, tools.\n\n\nADDITIONAL_CONTEXT (PROFILE HIGHLIGHTS) GUIDELINES:\n- Write \"additional_context\" as 2-6 short, high-signal, LinkedIn-style highlight fragments describing what the TARGET profile should visibly show (accomplishments, leadership scope, domains, constraints).\n- Use keyword-dense fragments; avoid full sentences, pronouns (\"I/we\"), and intent phrases (\"looking for\", \"need\", \"find me\", \"seeking\").\n- Use verbs that commonly appear in profiles: \"built\", \"led\", \"managed\", \"launched\", \"shipped\", \"scaled\", \"delivered\", \"owned\".\n- Prefer measurable outcomes and scope ONLY when explicitly provided: \"Scaled ARR to $10M+\", \"Led a team of 8 engineers\", \"Reduced infra cost 30%\". Do NOT invent numbers.\n- When numbers are not provided, use common positioning terms that match profile text: \"B2B SaaS\", \"enterprise\", \"high-growth\", \"0→1\", \"GTM\", \"PLG\", \"sales ops\", \"data pipelines\".\n- Separate fragments with \"; \" so downstream systems can split them into profile highlights.\n- Put availability/logistics/work-arrangement notes here as short fragments (e.g., \"Remote-friendly\", \"Open to relocation\", \"Available immediately\", \"Open to work\", \"Between jobs\") and NEVER in structured company/person booleans that do not exist.\n- Use \"retained_free_text\" for longer narrative; keep \"additional_context\" under ~200 chars when possible (hard cap 400).\n\n\nPOST FILTER GUIDELINES:\n- Use posts.* only when the user explicitly cares about recent posts/reposts or wants to prioritize people who have posted about a topic.\n- DEFAULT posts.mode to \"boost\". Post data coverage is sparse (most profiles have no indexed posts), so \"must\" excludes the majority of matches and should be rare.\n- Only set posts.mode = \"must\" when the user uses explicit obligatory language such as \"must have posted\", \"only include people who posted\", \"require posts about\", or \"only people posting about\". Soft phrasing like \"who post about\", \"posting about\", \"talking about\", or \"mentions\" stays as \"boost\".\n- Use posts.any = true for broad \"active on LinkedIn\" / \"posting regularly\" requests; when posts.any is true, leave posts.mentioned empty.\n- When the user mentions career change, job change, or new role posts:\n  - keep posts.mode = \"boost\" unless they also use obligatory language (see above)\n  - include posts.mentioned with a phrase like \"career update\" or \"new role\"\n- posts.mentioned should be a short keyword or phrase list to search for in post content (use when the user calls out a specific topic, phrase, or brand).\n- For engagement/date constraints, use posts.min_reactions, posts.min_comments, posts.min_engagement, and posts.published_within_days / published_after / published_before (e.g. \"more than 10 likes in the last week\" -> min_reactions=11 and published_within_days=7).\n- For activity against another entity, use posts.action_types plus posts.target_companies, posts.target_people, or posts.target_urls (e.g. \"liked competitors' posts\" -> action_types=[\"like\"], target_companies=[...competitor names]).\n\n\nINDUSTRY GUIDELINES:\n- Only populate \"industries\" when the description explicitly names a clear, canonical industry (e.g., Healthcare, Fintech, SaaS).\n- Do NOT map broad consumer descriptors (consumer-focused, consumer-facing, B2C, D2C, consumer tech, social/consumer apps) to a specific industry like \"Consumer Goods\"; keep those as additional_context_keywords instead.\n- Do NOT map in-house recruiting, Talent Acquisition, People, or HR leadership target wording to company industries like Recruiting or Human Resources. Those are functional people/team terms unless the user explicitly asks for recruiting agencies, staffing firms, HR software/services companies, or companies in the recruiting/HR industry.\n- When unsure whether an industry is canonical, leave \"industries\" empty and rely on keywords.\n- For company constraints in description translation, store industries in company_search.include.filters.industries (not top-level filters.industries).\n\nCOMPANY GUIDELINES:\n- Never place the same company in both include and exclude lists; if they overlap, drop the include and keep the exclusion.\n- When companies are mentioned as examples (\"companies like X, Y, Z\"), put them in additional_context_keywords, not company filters.\n- Do not include the user's own company or the hiring company in company filters.\n- If the user says \"startup\" or \"early-stage\" and DOES NOT specify a size range, set company_search.include.filters.company_headcount.max = 100.\n- If the user explicitly says \"current company size\" (e.g., \"current company size 100 or fewer\"), keep people company scope current-only via companies.include_current_only = true while company size/headcount remains in company_search.include.filters.company_headcount.\n\n\nEXPERIENCE GUIDELINES:\n- Leave \"years_experience.max\" null unless the description explicitly states an upper bound (e.g., \"no more than 8 years\").\n- Seniority cues like \"mid-level\" or \"senior\" should only influence the minimum.\n- Preserve important numeric constraints (months/years, revenue, company size).\n- If the user says \"recently left\", \"recently joined\", \"new role\", \"just started\", or \"recent transition\" without a specific timeframe, set current_role_tenure_months.max = 12.\n- Fresh/current founder transitions: for prompts like \"fresh founders\", \"recently became founders\", \"changed their title to Founder/Co-Founder/CEO\", or \"new founders after leaving a well-known tech company\", keep Founder/Co-Founder (and CEO when named) in job_titles.include with current_only=true. Do NOT put Founder/Co-Founder in job_titles.exclude just because the user says they do not want people who have been running a company for years; represent that recency with current_role_tenure_months.max (for month-scale windows) and prior-company history with companies.include_current_only=false or company_search stage_semantics=\"historical\".\n- Use average_role_tenure_months only when the user explicitly asks for average tenure per role; values are in months.\n- Set current-only flags to true only when the description clearly specifies currently employed/active.\n- Use \"locations.scope\" = \"current\" unless the description explicitly allows matching past locations/experiences.\n- Use connections_count and followers_count only for explicit social-count constraints (for example \"500+ connections\", \"at least 10k followers\"). Vague comparative phrases like \"a lot of followers\", \"high follower count\", or \"most connected\" are sort/ranking intent, not numeric range filters.\n- Use education for explicit school, degree, field-of-study, or graduation-year requirements. Example: \"graduated from MIT with a BS in CS between 2015 and 2023\" -> education.schools=[\"MIT\"], education.degrees=[\"BS\"], education.fields_of_study=[\"Computer Science\"], education.graduation_year={min:2015,max:2023}, education.mode=\"boost\".\n- DEFAULT education.mode to \"boost\". Education/graduation-year coverage is sparse; \"must\" excludes profiles whose education is not indexed (and requires school AND graduation year to match on the SAME indexed education row). Only set mode=\"must\" on explicit obligatory language (\"must have attended\", \"only people from\", \"require a degree from\").\n- EXEMPLAR SCHOOLS (mirror of the companies-as-examples rule): When schools are named as exemplars (\"Alpha University, Beta Tech level schools\", \"top-tier CS programs\"), set education.schools to the named schools PLUS canonical full names with mode=\"boost\"; never mode=\"must\" for \"-level\"/\"-tier\"/\"like\" phrasing. Expand shorthand school names to canonical full names so indexed education rows match (e.g., \"CMU\" -> add \"Carnegie Mellon University\"; \"Georgia Tech\" -> add \"Georgia Institute of Technology\"; \"UIUC\"/\"University of Illinois\" -> add \"University of Illinois Urbana-Champaign\"; \"Michigan\" -> add \"University of Michigan\").\n  Example: \"engineers from top tier engineering universities (Alpha University, Beta Tech level schools) who graduated in 2016 or earlier\" -> education.schools=[\"Alpha University\",\"Beta Tech\"], education.graduation_year={min:null,max:2016}, education.mode=\"boost\".\n- Use education.degrees with mode=\"must\" for explicit PhD candidate, doctoral, postdoctoral, post-grad, or graduate researcher requirements (explicit academic-level requirements are the exception to the education.mode=\"boost\" default). For niche expertise like web crawling, web scraping infrastructure, distributed crawling systems, large-scale data extraction, or crawler infrastructure, keep the exact expertise phrases in additional_context_keywords_core/supporting and additional_context, and do not make academic status labels mandatory current job-title filters.\n- Use languages for explicit spoken/written language requirements (for example \"Spanish speakers\" -> languages.include=[\"Spanish\"]).\n- Use recommendations for explicit LinkedIn recommendation requirements (for example \"has recommendations\" -> recommendations.any=true; \"recommended for leadership\" -> recommendations.mentioned=\"leadership\").\n- If the user explicitly asks for no current role/no current employer/no new role yet/\"end date on most recent role\", set has_current_experience=false. This approximates \"most recent role ended\" by excluding active/current experience rows; profile freshness and experience-date coverage are imperfect.\n- Do not use has_current_experience=false for generic \"open to work\" alone unless the user agrees they want that hard refinement; open-to-work text is usually sparse profile evidence, not a reliable structured field.\n- If the user says \"at least N years/months in current role OR not currently working/no current role\", set current_role_tenure_months.min to the converted month count and current_role_tenure_months.include_no_current_experience=true. Do not also set has_current_experience=false for that OR shape.\n- For dated title/company history, use experience_clauses[].overlap_within_years. Example: \"had a founder title in the last five years but is not currently a founder\" -> job_titles.include/exclude Founder + Co-Founder with current_only=false and exclude_current_only=true, plus experience_clauses:[{titles:[\"Founder\",\"Co-Founder\"], companies:[], current_only:false, overlap_within_years:5}].\n\nCURRENT-ROLE RECENCY (current_role_started_within_days):\n- Use this filter when the user wants people who STARTED their current role recently with a *specific* day/week window.\n- Examples → output:\n  - \"started a new job in the last 2 days\" → current_role_started_within_days: 2\n  - \"joined a new company this week\" → current_role_started_within_days: 7\n  - \"first-degree connections whose current role started in the past week\" → current_role_started_within_days: 7\n  - \"people who started a new role in the last 30 days\" → current_role_started_within_days: 30\n- Distinguish from current_role_tenure_months: use current_role_started_within_days for SHORT day-scale windows (≤90 days). Use current_role_tenure_months for month/year-scale tenure ranges.\n- Range: integer 1..365. If unspecified but the user clearly wants very recent (\"just started\", \"this week\"), default to 7.\n- Coverage caveat: profile coverage on the underlying start_date field is partial. If applied alone the result count may be low — that's correct behavior (precision over recall), not a bug.","schema_metadata":{"connection_degrees":{"type":"enum_array","enum":["1st","2nd","3rd+"],"default":["1st","2nd"],"description":"Network connection proximity (1st, 2nd, 3rd+)."},"exclude_connection_degrees":{"type":"enum_array","enum":["1st","2nd"],"default":[],"description":"Network connection proximity to exclude. Use [\"1st\"] for requests like \"exclude first-degree LinkedIn connections\"; only 1st/2nd are backed by searchable network bitmaps."},"job_titles":{"type":"object","description":"Job titles to include/exclude and matching behavior.","properties":{"include":{"type":"string_array","description":"Job titles to search for."},"exclude":{"type":"string_array","description":"Job titles to exclude."},"mode":{"type":"enum","enum":["boost","must"],"default":"must","description":"Whether job title matches are required (must) or used as boosts (boost)."},"exact":{"type":"boolean","default":false,"description":"Require exact title match."},"current_only":{"type":"boolean","default":false,"description":"If true, only match current roles for included title filters; if false, match title history."},"exclude_current_only":{"type":"boolean","default":false,"description":"If true, exclude only people whose current role matches excluded titles. Use with current_only:false for \"previously X, not currently X\" searches."},"match_scope":{"type":"enum","enum":["broad","anchored_prefix","exact"],"default":"broad","description":"Job-title matching breadth. broad allows semantic/contained title matches; anchored_prefix requires the requested title to match from the beginning of an experience title; exact requires exact normalized title matching with no variant expansion."}}},"hiring":{"type":"object","description":"Boost or filter people who work at companies hiring for specific roles (based on ingested job postings).","properties":{"mode":{"type":"enum","enum":["boost","must"],"default":"boost","description":"Whether hiring matches are used for boosting (boost) or required (must)."},"job_titles":{"type":"string_array","description":"Job titles the company should be hiring for."},"locations":{"type":"string_array","description":"Job location hints (text match against job postings)."},"accepts_remote":{"type":"boolean","nullable":true,"description":"If true, prefer remote job postings; if false, prefer onsite postings; null = any."}}},"locations":{"type":"object","description":"Location includes/excludes and radius.","properties":{"include":{"type":"string_array","description":"Locations to include."},"exclude":{"type":"string_array","description":"Locations to exclude."},"radius_miles":{"type":"number","default":50,"description":"Search radius in miles (for geo-aware locations)."},"strict":{"type":"boolean","default":false,"description":"If true, only match within the specified locations."},"scope":{"type":"enum","enum":["current","any_experience"],"default":"current","description":"Whether to match current location or any historical experience location."}}},"timezones":{"type":"object","description":"Timezone proximity filter (UTC offset-based).","properties":{"timezone":{"type":"string","nullable":true,"description":"IANA timezone ID (e.g., \"America/Los_Angeles\"). Use only for explicit timezone intent, not bare place names such as Alaska or Hawaii."},"within_hours":{"type":"number","nullable":true,"description":"Match profiles within N hours of the target timezone (1-11). Use null for any timezone."}}},"companies":{"type":"object","description":"Companies to include/exclude and current-vs-history scope.","properties":{"include":{"type":"string_array","description":"Companies to search within."},"exclude":{"type":"string_array","description":"Companies to exclude."},"include_current_only":{"type":"boolean","default":false,"description":"If true, only match current companies for includes."},"exclude_current_only":{"type":"boolean","default":false,"description":"If true, only match current companies for excludes."},"include_company_search_id":{"type":"string","nullable":true,"description":"Optional company search_id to include all companies from a saved company search."},"include_company_search_boost_id":{"type":"string","nullable":true,"description":"Optional company search_id to softly boost all companies from a saved company search."},"include_clauses":{"type":"array","description":"Additional AND-ed company experience clauses for mixed historical/current employer queries.","items":{"type":"object","properties":{"include":{"type":"string_array","description":"Companies to include for this clause."},"include_current_only":{"type":"boolean","default":false,"description":"If true, only match current companies for this clause."},"include_company_search_id":{"type":"string","nullable":true,"description":"Optional company search_id to include all companies from a saved company search for this clause."},"include_company_search_boost_id":{"type":"string","nullable":true,"description":"Optional company search_id to softly boost companies from a saved company search for this clause."},"company_query":{"type":"string","nullable":true,"description":"Human-readable descriptor text that produced the saved company search binding for this clause."}}}},"exclude_company_search_id":{"type":"string","nullable":true,"description":"Optional company search_id to exclude all companies from a saved company search."}}},"experience_clauses":{"type":"array","description":"Composite experience clauses that bind titles and companies to the same experience row.","items":{"type":"object","properties":{"titles":{"type":"string_array","description":"Titles to match within the same experience row."},"companies":{"type":"string_array","description":"Companies to match within the same experience row."},"current_only":{"type":"boolean","default":false,"description":"If true, only match current roles for this clause."},"title_exact":{"type":"boolean","default":false,"description":"Require exact title matching for this clause."},"title_match_scope":{"type":"enum","enum":["broad","anchored_prefix","exact"],"default":"broad","description":"How strictly title matching should anchor to the requested title."}}}},"industries":{"type":"string_array","description":"Industry sectors (canonicalized using the taxonomy service).","default":[]},"years_experience":{"type":"object","description":"Total years of professional experience.","properties":{"min":{"type":"number","nullable":true,"description":"Minimum years of experience."},"max":{"type":"number","nullable":true,"description":"Maximum years of experience."}}},"connections_count":{"type":"object","description":"LinkedIn/CoreSignal connections count range.","properties":{"min":{"type":"number","nullable":true,"description":"Minimum connections count."},"max":{"type":"number","nullable":true,"description":"Maximum connections count."}}},"followers_count":{"type":"object","description":"LinkedIn/CoreSignal followers count range.","properties":{"min":{"type":"number","nullable":true,"description":"Minimum followers count."},"max":{"type":"number","nullable":true,"description":"Maximum followers count."}}},"education":{"type":"object","description":"Education filters over schools, degrees, fields of study, and graduation year.","properties":{"schools":{"type":"string_array","description":"Schools or universities to match."},"degrees":{"type":"string_array","description":"Degree names or abbreviations, e.g. BS, MBA, PhD."},"fields_of_study":{"type":"string_array","description":"Majors or fields of study, e.g. Computer Science, Math."},"graduation_year":{"type":"object","description":"Graduation/end year range.","properties":{"min":{"type":"number","nullable":true,"description":"Earliest graduation year."},"max":{"type":"number","nullable":true,"description":"Latest graduation year."}}},"mode":{"type":"enum","enum":["must","boost"],"default":"must","description":"Whether education matches are required (must) or used for boosting."}}},"languages":{"type":"object","description":"Language filters from profile language fields.","properties":{"include":{"type":"string_array","description":"Languages to match."},"proficiency":{"type":"string_array","description":"Optional proficiency terms to match when present."},"mode":{"type":"enum","enum":["must","boost"],"default":"must","description":"Whether language matches are required (must) or used for boosting."}}},"recommendations":{"type":"object","description":"LinkedIn recommendation filters.","properties":{"any":{"type":"boolean","default":false,"description":"If true, match profiles with at least one recommendation."},"mentioned":{"type":"string","description":"Keyword or phrase list to search within recommendation text."},"recommenders":{"type":"string_array","description":"Names of recommenders/referees to match."},"mode":{"type":"enum","enum":["must","boost"],"default":"must","description":"Whether recommendation matches are required (must) or used for boosting."}}},"average_role_tenure_months":{"type":"object","description":"Average tenure per role (months). Current role is included only when it exceeds prior-role average.","properties":{"min":{"type":"number","nullable":true,"description":"Minimum average months per role."},"max":{"type":"number","nullable":true,"description":"Maximum average months per role."}}},"current_role_tenure_months":{"type":"object","description":"Tenure in current role (months).","properties":{"min":{"type":"number","nullable":true,"description":"Minimum months in current role."},"max":{"type":"number","nullable":true,"description":"Maximum months in current role."},"include_no_current_experience":{"type":"boolean","default":false,"description":"Include people with no current role as an OR branch for current-role tenure constraints."}}},"recent_short_stints":{"type":"object","description":"Recent short-stint pattern representation. Use for constraints such as \"last 2-3 jobs have been short stints\" or \"avoid recent job hoppers\".","properties":{"max_role_tenure_months":{"type":"number","nullable":true,"description":"Maximum tenure, in months, that counts as a short stint."},"min_count":{"type":"number","nullable":true,"description":"Minimum number of short stints required to trigger the pattern."},"within_recent_roles":{"type":"number","nullable":true,"description":"How many most-recent roles to inspect for the short-stint count."},"exclude":{"type":"boolean","default":false,"description":"If true, candidates matching this recent short-stint pattern are a negative/exclusion signal."},"mode":{"type":"enum","enum":["must","boost"],"default":"must","description":"Whether the short-stint pattern should be treated as a hard quality constraint or a ranking signal."}}},"current_role_started_within_days":{"type":"number","nullable":true,"description":"Coarse recency filter — match people whose CURRENT role started within the last N days. Use for \"started a new job in the last week / past 2 days / recently\" queries. Coverage on the underlying experience start_date is partial; null values do not match, so this favors precision over recall."},"linkedin_connected_within_days":{"type":"number","nullable":true,"description":"Viewer-scoped LinkedIn first-degree connection recency — match people the viewer connected with on LinkedIn within the last N days. Use for \"new LinkedIn connections\", \"recently added connections\", or daily connection-change scans. Pair with connection_degrees:[\"1st\"] and network_filter_mode:\"filter\"; this is connection date, not job-change date."},"linkedin_connected_after":{"type":"string","nullable":true,"description":"Inclusive ISO date/datetime lower bound for the viewer->person LinkedIn connection date. Use for ranged first-degree network map requests such as connections added since 2026-05-01."},"linkedin_connected_before":{"type":"string","nullable":true,"description":"Inclusive ISO date/datetime upper bound for the viewer->person LinkedIn connection date. Use with linkedin_connected_after for connection-date ranges."},"has_current_experience":{"type":"boolean","nullable":true,"default":null,"description":"If false, match profiles with no active/current experience row and at least one ended experience; use for \"no current role\", \"no new role yet\", \"between jobs\", or \"most recent role has an end date\" queries. If true, require at least one active/current experience. Coverage depends on profile experience freshness."},"sort_by":{"anyOf":[{"type":"string","enum":["best_match","last_name","full_name","connected_date","followers_count","connections_count","current_role_tenure_months","average_role_tenure_months","company_size","company_revenue"]},{"type":"null"}],"description":"Result-ranking dimension for comparative/superlative wording only; null when no ranking is requested."},"sort_order":{"anyOf":[{"type":"string","enum":["asc","desc"]},{"type":"null"}],"description":"Direction for sort_by; null when sort_by is null."},"company_size":{"type":"object","description":"Person-side fast filter on current/historical employer headcount. Reads denormalized company_employee_counts_{current,all} arrays indexed on every profile, so it does not require resolving a company-id set and runs as a single profile-index range clause. Use this for \"people at sub-200-employee companies\", \"candidates at companies with 11-50 employees\", and similar headcount-bounded sourcing. By default profiles whose employer headcount is UNKNOWN are still included (ranked below known-in-range matches) because small/boutique employers frequently lack published headcount; set include_unknown:false to require a verified in-range headcount.","properties":{"min":{"type":"number","nullable":true,"description":"Minimum employee count (inclusive)."},"max":{"type":"number","nullable":true,"description":"Maximum employee count (inclusive)."},"current_only":{"type":"boolean","default":true,"description":"If true (default), the headcount range is enforced against the profile's CURRENT employer only. Set to false to also match any historical employer with a matching headcount. Most \"people at <size> companies\" intent is current-employer-only."},"include_unknown":{"type":"boolean","default":true,"description":"If true (default), profiles whose employer headcount is unknown also match, ranked below known-in-range profiles; responses disclose the unknown-headcount share via a company_size_unknown_included warning. NEVER set this to false unless the user explicitly requires verified/known/published headcounts — false silently hides most small and boutique employers (the pre-2026-07 failure mode). When in doubt, omit the field entirely."}}},"company_revenue":{"type":"object","description":"Person-side fast filter on current/historical employer revenue (USD). Reads denormalized company_revenue_{current,all} arrays on every profile, so no company-id resolution step is needed. Use this for \"people at $10M-$100M revenue companies\" and similar revenue-bounded sourcing. Profiles whose employer has no revenue data are filtered out.","properties":{"min":{"type":"number","nullable":true,"description":"Minimum revenue in USD (inclusive)."},"max":{"type":"number","nullable":true,"description":"Maximum revenue in USD (inclusive)."},"current_only":{"type":"boolean","default":true,"description":"If true (default), the revenue range is enforced against the profile's CURRENT employer only. Set to false to also match any historical employer."}}},"posts":{"type":"object","description":"Structured filters over LinkedIn posts and engagement activity, including text, action type, engagement thresholds, date windows, and target entities.","properties":{"mode":{"type":"enum","enum":["boost","must"],"default":"boost","description":"Whether post matches are required (must) or used for boosting."},"any":{"type":"boolean","default":false,"description":"If true, match any recent posting activity."},"mentioned":{"type":"string","description":"Hard/literal keyword or phrase list to search for within post content. Use for \"posts mentioning X\" / \"posts containing X\"; use post additional_context keyword fields for softer topic intent."},"keyword_match_mode":{"type":"enum","enum":["soft","hard"],"default":"soft","description":"Whether post keyword fields are treated as soft expanded topic evidence or hard literal mention intent."},"additional_context_keywords":{"type":"string_array","description":"General post-topic keyword hints. Prefer core/supporting when splitting high-signal vs recall-broadening terms."},"additional_context_keywords_core":{"type":"string_array","description":"Core post-topic keyword hints that should strongly influence matching, similar to top-level additional_context_keywords_core."},"additional_context_keywords_supporting":{"type":"string_array","description":"Supporting post-topic keyword hints that broaden recall without being mandatory exact phrases."},"action_types":{"type":"string_array","description":"Activity types to require, such as post, repost, comment, like, or reaction. Use this with date and target filters for structured activity searches."},"min_reactions":{"type":"number","nullable":true,"description":"Minimum reaction/like count on the matching post or activity."},"min_comments":{"type":"number","nullable":true,"description":"Minimum comment count on the matching post or activity."},"min_engagement":{"type":"number","nullable":true,"description":"Minimum total engagement count on the matching post or activity."},"published_within_days":{"type":"number","nullable":true,"description":"Require matching activity observed or published within the last N days."},"published_after":{"type":"string","nullable":true,"description":"Inclusive ISO date/datetime lower bound for matching activity."},"published_before":{"type":"string","nullable":true,"description":"Inclusive ISO date/datetime upper bound for matching activity."},"target_companies":{"type":"string_array","description":"Companies whose posts or mentions the person acted on."},"target_people":{"type":"string_array","description":"People whose posts or mentions the person acted on."},"target_urls":{"type":"string_array","description":"Post, profile, or company URLs targeted by the matching activity."}}},"network_filter_mode":{"type":"enum","enum":["boost","filter","ignore","connected_to"],"default":"boost","description":"How to weight the user’s network in search results."},"connected_to":{"type":"string_array","description":"User IDs whose 1st-degree network should be searched when network_filter_mode=connected_to.","default":[]},"exclude_connected_to":{"type":"string_array","description":"User IDs whose 1st-degree network should be excluded. Use for third-person negative connection-owner requests like \"not connected to John Doe\"; this does not change network_filter_mode.","default":[]},"personas":{"type":"object","description":"Persona anchors for similarity-based boosting/downranking and shared-employer filtering.","properties":{"more_like":{"type":"string_array","description":"User IDs to use as positive similarity anchors."},"less_like":{"type":"string_array","description":"User IDs to down-rank via similarity."},"worked_with":{"type":"string_array","description":"User IDs (UUIDs) whose former or current employers should overlap (with overlapping tenure) with the matched person. Used for \"people I have worked with\" / \"people who worked with <Name>\" intent. Server-side requires tenure overlap."}},"default":{"more_like":[],"less_like":[],"worked_with":[]}},"diversify_by_company":{"type":"boolean","description":"If true, collapse results so each company appears at most once (where possible). Omit to use default heuristics."},"additional_context":{"type":"string","description":"Free-form text describing nuance that does not map to structured filters.","default":""},"keyword_match_mode":{"type":"enum","enum":["soft","hard"],"default":"soft","description":"Whether top-level profile keyword fields are soft ranking/context evidence or a hard profile-text eligibility filter. Use hard only when the user explicitly requires profiles to mention at least one of the keyword terms."},"additional_context_keywords":{"type":"string_array","description":"Profile keyword hints used to expand or refine context matching.","default":[]},"additional_context_keywords_core":{"type":"string_array","description":"Core profile keyword hints that should strongly influence matching.","default":[]},"additional_context_keywords_supporting":{"type":"string_array","description":"Supporting keyword hints that broaden recall without being mandatory.","default":[]},"included_networks":{"type":"enum_array","enum":["super_carl","linkedin","gmail","contacts","x","instagram"],"description":"Networks to search (e.g., super_carl, linkedin, gmail, contacts, x, instagram).","default":["super_carl","linkedin"]},"reachable_via":{"type":"enum_array","enum":["super_carl","linkedin","gmail","contacts","x","instagram"],"description":"Require that results are reachable through the selected channels.","default":[]},"instagram_direction":{"type":"enum","enum":["none","following","followers","mutual","any"],"description":"Restrict to the viewer’s Instagram follow graph: \"following\" = people you follow, \"followers\" = people who follow you, \"mutual\" = both, \"any\" = connected either way (use when an IG connection is implied but direction is unspecified), \"none\" = no IG follow constraint (default). Composes with all other filters, e.g. founders you follow on IG.","default":"none"},"x_direction":{"type":"enum","enum":["none","following","followers","mutual","any"],"description":"Restrict to the viewer’s X (Twitter) follow graph: \"following\" = people you follow, \"followers\" = people who follow you, \"mutual\" = both, \"any\" = connected either way (use when an X connection is implied but direction is unspecified), \"none\" = no X follow constraint (default). Composes with all other filters, e.g. founders who follow you on X.","default":"none"}},"json_schema":{"type":"object","properties":{"connection_degrees":{"type":"array","items":{"type":"string","enum":["1st","2nd","3rd+"]}},"exclude_connection_degrees":{"type":"array","items":{"type":"string","enum":["1st","2nd"]}},"job_titles":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["boost","must"]},"exact":{"type":"boolean"},"current_only":{"type":"boolean"},"exclude_current_only":{"type":"boolean"},"match_scope":{"type":"string","enum":["broad","anchored_prefix","exact"]}},"additionalProperties":false,"required":["include","exclude","mode","exact","current_only","exclude_current_only","match_scope"]},"hiring":{"type":"object","properties":{"mode":{"type":"string","enum":["boost","must"]},"job_titles":{"type":"array","items":{"type":"string"}},"locations":{"type":"array","items":{"type":"string"}},"accepts_remote":{"type":"boolean"}},"additionalProperties":false,"required":["mode","job_titles","locations","accepts_remote"]},"locations":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}},"radius_miles":{"type":"number"},"strict":{"type":"boolean"},"scope":{"type":"string","enum":["current","any_experience"]}},"additionalProperties":false,"required":["include","exclude","radius_miles","strict","scope"]},"timezones":{"type":"object","properties":{"timezone":{"anyOf":[{"type":"string"},{"type":"null"}]},"within_hours":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"required":["timezone","within_hours"]},"companies":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}},"include_current_only":{"type":"boolean"},"exclude_current_only":{"type":"boolean"},"include_company_search_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"include_company_search_boost_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"include_clauses":{"type":"array","items":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}},"include_current_only":{"type":"boolean"},"include_company_search_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"include_company_search_boost_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"company_query":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"required":["include","include_current_only","include_company_search_id","include_company_search_boost_id","company_query"]}},"exclude_company_search_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false,"required":["include","exclude","include_current_only","exclude_current_only","include_company_search_id","include_company_search_boost_id","include_clauses","exclude_company_search_id"]},"experience_clauses":{"type":"array","items":{"type":"object","properties":{"titles":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"type":"string"}},"current_only":{"type":"boolean"},"title_exact":{"type":"boolean"},"title_match_scope":{"type":"string","enum":["broad","anchored_prefix","exact"]}},"additionalProperties":false,"required":["titles","companies","current_only","title_exact","title_match_scope"]}},"industries":{"type":"array","items":{"type":"string"}},"years_experience":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"required":["min","max"]},"connections_count":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"required":["min","max"]},"followers_count":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"required":["min","max"]},"education":{"type":"object","properties":{"schools":{"type":"array","items":{"type":"string"}},"degrees":{"type":"array","items":{"type":"string"}},"fields_of_study":{"type":"array","items":{"type":"string"}},"graduation_year":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"required":["min","max"]},"mode":{"type":"string","enum":["must","boost"]}},"additionalProperties":false,"required":["schools","degrees","fields_of_study","graduation_year","mode"]},"languages":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}},"proficiency":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["must","boost"]}},"additionalProperties":false,"required":["include","proficiency","mode"]},"recommendations":{"type":"object","properties":{"any":{"type":"boolean"},"mentioned":{"type":"string"},"recommenders":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["must","boost"]}},"additionalProperties":false,"required":["any","mentioned","recommenders","mode"]},"average_role_tenure_months":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":false,"required":["min","max"]},"current_role_tenure_months":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]},"include_no_current_experience":{"type":"boolean"}},"additionalProperties":false,"required":["min","max","include_no_current_experience"]},"recent_short_stints":{"type":"object","properties":{"max_role_tenure_months":{"anyOf":[{"type":"number"},{"type":"null"}]},"min_count":{"anyOf":[{"type":"number"},{"type":"null"}]},"within_recent_roles":{"anyOf":[{"type":"number"},{"type":"null"}]},"exclude":{"type":"boolean"},"mode":{"type":"string","enum":["must","boost"]}},"additionalProperties":false,"required":["max_role_tenure_months","min_count","within_recent_roles","exclude","mode"]},"current_role_started_within_days":{"anyOf":[{"type":"number"},{"type":"null"}]},"linkedin_connected_within_days":{"anyOf":[{"type":"number"},{"type":"null"}]},"linkedin_connected_after":{"anyOf":[{"type":"string"},{"type":"null"}]},"linkedin_connected_before":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_current_experience":{"type":"boolean"},"sort_by":{"anyOf":[{"type":"string","enum":["best_match","last_name","full_name","connected_date","followers_count","connections_count","current_role_tenure_months","average_role_tenure_months","company_size","company_revenue"]},{"type":"null"}],"description":"Result-ranking dimension for comparative/superlative wording only; null when no ranking is requested."},"sort_order":{"anyOf":[{"type":"string","enum":["asc","desc"]},{"type":"null"}],"description":"Direction for sort_by; null when sort_by is null."},"company_size":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]},"current_only":{"type":"boolean"},"include_unknown":{"type":"boolean"}},"additionalProperties":false,"required":["min","max","current_only","include_unknown"]},"company_revenue":{"type":"object","properties":{"min":{"anyOf":[{"type":"number"},{"type":"null"}]},"max":{"anyOf":[{"type":"number"},{"type":"null"}]},"current_only":{"type":"boolean"}},"additionalProperties":false,"required":["min","max","current_only"]},"posts":{"type":"object","properties":{"mode":{"type":"string","enum":["boost","must"]},"any":{"type":"boolean"},"mentioned":{"type":"string"},"keyword_match_mode":{"type":"string","enum":["soft","hard"]},"additional_context_keywords":{"type":"array","items":{"type":"string"}},"additional_context_keywords_core":{"type":"array","items":{"type":"string"}},"additional_context_keywords_supporting":{"type":"array","items":{"type":"string"}},"action_types":{"type":"array","items":{"type":"string"}},"min_reactions":{"anyOf":[{"type":"number"},{"type":"null"}]},"min_comments":{"anyOf":[{"type":"number"},{"type":"null"}]},"min_engagement":{"anyOf":[{"type":"number"},{"type":"null"}]},"published_within_days":{"anyOf":[{"type":"number"},{"type":"null"}]},"published_after":{"anyOf":[{"type":"string"},{"type":"null"}]},"published_before":{"anyOf":[{"type":"string"},{"type":"null"}]},"target_companies":{"type":"array","items":{"type":"string"}},"target_people":{"type":"array","items":{"type":"string"}},"target_urls":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["mode","any","mentioned","keyword_match_mode","additional_context_keywords","additional_context_keywords_core","additional_context_keywords_supporting","action_types","min_reactions","min_comments","min_engagement","published_within_days","published_after","published_before","target_companies","target_people","target_urls"]},"network_filter_mode":{"type":"string","enum":["boost","filter","ignore","connected_to"]},"connected_to":{"type":"array","items":{"type":"string"}},"exclude_connected_to":{"type":"array","items":{"type":"string"}},"personas":{"type":"object","properties":{"more_like":{"type":"array","items":{"type":"string"}},"less_like":{"type":"array","items":{"type":"string"}},"worked_with":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["more_like","less_like","worked_with"]},"diversify_by_company":{"type":"boolean"},"additional_context":{"type":"string"},"keyword_match_mode":{"type":"string","enum":["soft","hard"]},"additional_context_keywords":{"type":"array","items":{"type":"string"}},"additional_context_keywords_core":{"type":"array","items":{"type":"string"}},"additional_context_keywords_supporting":{"type":"array","items":{"type":"string"}},"included_networks":{"type":"array","items":{"type":"string","enum":["super_carl","linkedin","gmail","contacts","x","instagram"]}},"reachable_via":{"type":"array","items":{"type":"string","enum":["super_carl","linkedin","gmail","contacts","x","instagram"]}},"instagram_direction":{"type":"string","enum":["none","following","followers","mutual","any"]},"x_direction":{"type":"string","enum":["none","following","followers","mutual","any"]}},"additionalProperties":false,"required":["connection_degrees","exclude_connection_degrees","job_titles","hiring","locations","timezones","companies","experience_clauses","industries","years_experience","connections_count","followers_count","education","languages","recommendations","average_role_tenure_months","current_role_tenure_months","recent_short_stints","current_role_started_within_days","linkedin_connected_within_days","linkedin_connected_after","linkedin_connected_before","has_current_experience","sort_by","sort_order","company_size","company_revenue","posts","network_filter_mode","connected_to","exclude_connected_to","personas","diversify_by_company","additional_context","keyword_match_mode","additional_context_keywords","additional_context_keywords_core","additional_context_keywords_supporting","included_networks","reachable_via","instagram_direction","x_direction"]}}}