{
  "version": "v1",
  "generated_at": "2026-09-10T21:16:25.724Z",
  "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 deterministic light 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 structured result.",
      "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": "Handled MCP result returned when the account owner is at or over the credit ceiling. It stays on the normal result path so hosts preserve the structured credit metadata instead of promoting it to an opaque runtime exception.",
        "fields": [
          {
            "name": "isError",
            "type": "boolean",
            "required": true,
            "description": "Always false; this is a structured business outcome, not a protocol-level tool failure."
          },
          {
            "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.success",
            "type": "boolean",
            "required": true,
            "description": "Always false."
          },
          {
            "name": "structuredContent.error",
            "type": "string",
            "required": true,
            "description": "\"credits_exhausted\". Top-level output-schema field for normal result-path branching."
          },
          {
            "name": "structuredContent.error_code",
            "type": "string",
            "required": true,
            "description": "\"credits_exhausted\". Compatibility alias for clients that already branch on this field."
          },
          {
            "name": "structuredContent.message",
            "type": "string",
            "required": true,
            "description": "Human-readable summary with remaining balance and reset date when available."
          },
          {
            "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 match-reason enrichment 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 Connectors, 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 Connectors. 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 Connectors 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 Connectors 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 → Grow route and guidance for inviting key LinkedIn contacts to become Connectors and 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": "Searchable viewer-relative connection degree (1 or 2). Null means outside or unknown to the indexed 1st/2nd overlay."
          },
          {
            "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 types (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|null",
            "required": false,
            "description": "Super Carl post id used for post://<id> inline references and /posts/<id> links. Omitted when no safe public post identity exists."
          },
          {
            "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": "Observed actor LinkedIn profile/company URL when present."
          },
          {
            "name": "actor_company_url",
            "type": "string|null",
            "required": false,
            "description": "Observed company-actor URL when actor_entity_type is company."
          },
          {
            "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": "PostMatchedCompany",
        "description": "Deduped company row derived only from matching official company-authored ActivityPost rows. This is an observed-actor join; exact canonical identity is labeled and unresolved actors remain explicit.",
        "fields": [
          {
            "name": "company_id",
            "type": "uuid|string|null",
            "required": false,
            "description": "Canonical company id only when exact URL/name resolution succeeded. Never derived from the activity actor user_id."
          },
          {
            "name": "company_name",
            "type": "string|null",
            "required": false,
            "description": "Observed company actor display name."
          },
          {
            "name": "canonical_name",
            "type": "string|null",
            "required": false,
            "description": "Canonical registry name when exact resolution succeeded."
          },
          {
            "name": "actor_entity_type",
            "type": "string",
            "required": true,
            "description": "Always company for this projection."
          },
          {
            "name": "actor_company_url",
            "type": "string|null",
            "required": false,
            "description": "Observed company actor URL from the matched activity rows."
          },
          {
            "name": "author_profile_url",
            "type": "string|null",
            "required": false,
            "description": "Observed author/profile URL when actor_company_url was absent or as additional provenance."
          },
          {
            "name": "linkedin_company_url",
            "type": "string|null",
            "required": false,
            "description": "Canonical registry LinkedIn company URL when exact resolution succeeded."
          },
          {
            "name": "identity_status",
            "type": "string",
            "required": true,
            "description": "resolved_exact_company_url, resolved_exact_company_name, observed_company_actor_url, or observed_company_actor_name_only."
          },
          {
            "name": "identity_source",
            "type": "string",
            "required": true,
            "description": "Observed identity field used for dedupe/resolution."
          },
          {
            "name": "matched_post_count",
            "type": "number",
            "required": true,
            "description": "Number of matching official company-authored posts on the returned page."
          },
          {
            "name": "latest_post_at",
            "type": "string|null",
            "required": false,
            "description": "Most recent qualifying matched-post timestamp."
          },
          {
            "name": "matched_posts",
            "type": "ActivityPost[]",
            "required": true,
            "description": "Compact qualifying official-post evidence attached to this company actor."
          }
        ]
      },
      {
        "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. Searchable values are 1st and 2nd only. A non-empty authored list defaults to hard membership when network_filter_mode is omitted. Omit or pass an empty array for the full people pool; use network_filter_mode=\"boost\" explicitly to prefer reachable people without restricting eligibility."
          },
          {
            "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": "group_ids",
            "type": "string[]",
            "required": false,
            "description": "Server-issued network-group UUIDs that define a hard membership lane. The selected group pools are OR-ed with any explicitly selected viewer 1st/2nd-degree hard network lane; group_ids alone is a groups-only search. Leave empty for ordinary/global search, including an unqualified request made inside a group chat. Only choose IDs supplied in trusted group context; never invent, infer, or truncate them."
          },
          {
            "name": "job_titles",
            "type": "object",
            "required": false,
            "description": "Job titles to include/exclude and matching behavior.",
            "shape": {
              "include": "string[]",
              "exclude": "string[]",
              "mode": "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",
              "published_within_days": "number|null",
              "published_after": "string|null",
              "published_before": "string|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",
              "company_query": "string|null"
            }
          },
          {
            "name": "experience_clauses",
            "type": "unknown",
            "required": false,
            "description": "Composite experience clauses that bind titles, companies, and evidence keywords to the same experience row. within_recent_roles adds an exact service-layer check over the person's most recent N roles after Elasticsearch recall filtering. role_position=\"immediate_predecessor\" instead targets the canonical role immediately before the selected current role. For absolute historical employment, keep title, company, and as_of_date in this same row-bound clause. as_of_date is month-resolution reconstruction from the latest profile history, not a historical snapshot."
          },
          {
            "name": "title_company_size_conditions",
            "type": "unknown",
            "required": false,
            "description": "Title-conditional employer-headcount implications. Use when an employer-size restriction applies only to a subset of otherwise accepted titles, for example \"CMOs only at employers with 200 or fewer employees.\" Candidates without a matching title are unaffected; candidates with a matching title must satisfy the headcount condition on that same experience row. Do not turn this into top-level company_size or company_search, which would incorrectly apply the size restriction to every accepted title."
          },
          {
            "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": "Profile-listed languages.",
            "shape": {
              "include": "string[]",
              "match": "any|all",
              "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": "current_role_started_within_days",
            "type": "number|null",
            "required": false,
            "description": "Hard current-role-start eligibility — 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": "Current/historical employer headcount range. Profile-index counts and bands provide candidate hints; include_unknown:false requires final canonical numeric verification. A current range beside hard current job_titles binds to that same matching role, never to a different concurrent job. 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. Preferred size is a company ranking boost, not a hard company_size filter.",
            "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",
              "author_entity_types": "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",
              "authors": "string[]",
              "target_companies": "string[]",
              "target_people": "string[]",
              "target_urls": "string[]"
            }
          },
          {
            "name": "network_filter_mode",
            "type": "boost|filter|ignore|connected_to",
            "required": false,
            "description": "Whether the viewer’s relationships rank or restrict the search. Omission defaults to \"filter\" beside a non-empty authored connection_degrees list, and otherwise to \"boost\". \"boost\" ranks relationship-relevant rows higher without removing anyone. \"filter\": the request makes the network an explicit requirement (\"only in my network\", \"must be first-degree\") — eligibility. \"ignore\": explicit opt-out. \"connected_to\": scope to a named third party’s network."
          },
          {
            "name": "connected_to",
            "type": "(string | {name, company?, location?, linkedin_url?})[] (user id, LinkedIn profile URL, vanity, name, or name-plus-context object)",
            "required": false,
            "description": "People whose 1st-degree network should be searched when network_filter_mode=connected_to. Each entry may be a Super Carl profile id (UUID), a LinkedIn profile URL (\"https://www.linkedin.com/in/<vanity>\", any locale/subdomain variant, or a bare \"/in/<vanity>\" path), a LinkedIn vanity slug, a literal person name, or an object {name, company?, location?, linkedin_url?} — give the company/location you know when several people share the name, and never embed a qualifier in the name string itself (\"Jaime Bott (Peak XV)\" is rejected; {\"name\": \"Jaime Bott\", \"company\": \"Peak XV\"} binds). No client-side URL-to-id lookup is required. The server resolves non-id references and returns entity_resolution_required when a name matches several people; a LinkedIn URL that matches no indexed profile is reported as unresolved rather than silently ignored."
          },
          {
            "name": "exclude_connected_to",
            "type": "(string | {name, company?, location?, linkedin_url?})[] (user id, LinkedIn profile URL, vanity, name, or name-plus-context object)",
            "required": false,
            "description": "People 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. Accepts the same person references as connected_to: profile id (UUID), LinkedIn profile URL or \"/in/<vanity>\" path, vanity slug, literal name, or {name, company?, location?, linkedin_url?} object — the server resolves non-id references, using the object's company/location to pick between namesakes."
          },
          {
            "name": "personas",
            "type": "object",
            "required": false,
            "description": "Persona anchors for similarity-based boosting/downranking and shared-employer filtering. Each entry may be a Super Carl profile id (UUID), a LinkedIn profile URL (\"https://www.linkedin.com/in/<vanity>\", any locale/subdomain variant, or a bare \"/in/<vanity>\" path), a LinkedIn vanity slug, a literal person name, or an object {name, company?, location?, linkedin_url?} — give the company/location you know when several people share the name, and never embed a qualifier in the name string itself (\"Jaime Bott (Peak XV)\" is rejected; {\"name\": \"Jaime Bott\", \"company\": \"Peak XV\"} binds). No client-side URL-to-id lookup is required. The server resolves non-id references and returns entity_resolution_required when a name matches several people; a LinkedIn URL that matches no indexed profile is reported as unresolved rather than silently ignored.",
            "shape": {
              "more_like": "(string | {name, company?, location?, linkedin_url?})[] (user id, LinkedIn profile URL, vanity, name, or name-plus-context object)",
              "less_like": "(string | {name, company?, location?, linkedin_url?})[] (user id, LinkedIn profile URL, vanity, name, or name-plus-context object)",
              "worked_with": "(string | {name, company?, location?, linkedin_url?})[] (user id, LinkedIn profile URL, vanity, name, or name-plus-context object)"
            }
          },
          {
            "name": "worked_with_overlap_mode",
            "type": "graded|date_verified",
            "required": false,
            "description": "Worked-with membership before pagination: graded (default) or date_verified (dated overlap only)."
          },
          {
            "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 ALREADY reachable through the selected channels — gmail means an email address is already stored for the person, true of ~0.009% of profiles. Needing contact details is not the same as having them: a request to find or supply an email address is an enrichment need against the returned rows, not an eligibility filter, and must leave this empty."
          },
          {
            "name": "gmail_correspondence_direction",
            "type": "none|sent|received|reciprocal|any",
            "required": false,
            "description": "Owner-scoped Gmail history: sent = the viewer sent at least one message, received = the viewer received at least one, reciprocal = both, any = either direction, none = no history constraint. This is correspondence history, not email reachability and not Gmail contact-graph membership."
          },
          {
            "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"
            }
          }
        ]
      }
    ]
  }
}