{"openapi":"3.1.0","info":{"title":"LeadCognition Public API","version":"v1","description":"REST mirrors for the LeadCognition MCP developer-intent workflow."},"servers":[{"url":"https://app.leadcognition.io","description":"Production"}],"paths":{"/api/v1/health":{"get":{"summary":"Check public API readiness","responses":{"200":{"description":"API is reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/discovery-sessions":{"post":{"summary":"List recent Discover sessions","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Optional domain used to filter recent Discover sessions."},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10}}},"example":{"domain":"vercel.com","limit":5}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverySessionsResponse"},"example":{"sessions":[{"id":"ds_review_123","name":"Vercel developer intent","domain":"vercel.com","status":"ready","totalLeads":18,"createdAt":"2026-05-01T09:00:00Z","recommendedNextAction":"Use this session to prepare a Clay export."}],"nextStep":"Call /api/v1/developer-intent with the selected session id."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/lead-workflows/propose":{"post":{"summary":"Propose safe lead workflows","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":3,"maxLength":4000,"description":"Natural-language lead request."},"surface":{"type":"string","enum":["dashboard","mcp_chatgpt_codex","claude_app","clay_provider","code_execution","gemini_enterprise"],"default":"mcp_chatgpt_codex"},"domain":{"type":"string","description":"Optional product/customer domain from the user's request."},"knownCompetitors":{"type":"array","items":{"type":"string"}}}},"example":{"prompt":"Find ready leads for observability vendors and prepare the best rows for Clay","surface":"mcp_chatgpt_codex","domain":"example.com"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadWorkflowsProposeResponse"},"example":{"interpretedIntent":"Choose a bounded lead workflow before running scans, exports, or unlock-sensitive actions.","recommendedWorkflowId":"find_ready_leads","options":[{"id":"find_ready_leads","title":"Find ready leads now","description":"Rank developers and companies from an existing LeadCognition Discover session.","bestFor":"Teams with tracked repos or a ready Discover preview who want immediate lead review.","expectedOutput":"Ranked developers, company rollups, evidence, and a next step toward Clay rows.","availability":"available_now","surfaces":["mcp_chatgpt_codex","claude_app"],"dataSources":["discover_sessions","mcp_tools","postgres_operational"],"costGuardrail":{"queryMode":"cached","dataScan":"existing_session","creditSpend":"none","note":"Uses existing session results; it does not unlock identity fields or run a new scan."},"questions":[{"id":"icp","label":"Ideal customer profile","type":"textarea","required":true,"placeholder":"Developer tools companies selling to platform teams"}],"primaryAction":{"type":"call_mcp_tool","label":"Run ready-leads workflow","toolName":"run_lead_workflow","requiresConfirmation":false}}],"globalGuardrails":["Workflow planning does not spend credits, unlock identities, send webhooks, or run fresh BigQuery scans.","Executable MCP paths work over existing Discover sessions first."]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/lead-workflows/plan":{"post":{"summary":"Plan a selected lead workflow","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt","workflowId"],"properties":{"prompt":{"type":"string","minLength":3,"maxLength":4000},"workflowId":{"type":"string","enum":["discover_market","find_ready_leads","rank_high_intent_companies","watch_competitors","build_clay_outbound"]},"surface":{"type":"string","enum":["dashboard","mcp_chatgpt_codex","claude_app","clay_provider","code_execution","gemini_enterprise"],"default":"mcp_chatgpt_codex"},"answers":{"type":"object","additionalProperties":true,"description":"User answers keyed by question id."}}},"example":{"prompt":"Find ready leads for observability vendors","workflowId":"find_ready_leads","surface":"claude_app","answers":{"icp":"B2B observability vendors selling to platform teams"}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadWorkflowPlanResponse"},"example":{"workflowId":"find_ready_leads","title":"Find ready leads now","status":"ready_to_run","summary":"Find ready leads now can run through backend-controlled MCP actions over an existing Discover session.","missingQuestionIds":[],"backendExecution":["Resolve the authenticated organization and required MCP scope.","Call run_lead_workflow with the selected session/domain and explicit confirmation when required."],"recommendedActions":[{"type":"call_mcp_tool","label":"Run ready-leads workflow","toolName":"run_lead_workflow","requiresConfirmation":false}],"surfaceAdaptation":{"chatgptCodex":"Show workflow cards first, then call run_lead_workflow only for executable paths.","claude":"Ask concise follow-ups before invoking export or scan-like actions.","clay":"Prefer build_clay_outbound after a reviewed Discover session; keep external webhook delivery separate.","dashboard":"Route fresh discovery to /discover and existing-session work to leads or export review."},"guardrails":["No raw ad-hoc BigQuery scans from model text.","No identity unlock, credit spend, or external delivery without an explicit backend confirmation path."]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/lead-workflows/run":{"post":{"summary":"Run a guided lead workflow","description":"Requires an org API key with mcp:export.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["workflowId"],"properties":{"sessionId":{"type":"string","description":"Optional Discover session id. If omitted, LeadCognition resolves a recent matching session from domain or org history."},"domain":{"type":"string","description":"Optional company/product domain used to resolve a recent Discover session."},"workflowId":{"type":"string","enum":["find_ready_leads","build_clay_outbound"]},"prompt":{"type":"string","minLength":1,"maxLength":2000,"description":"Original user request for auditability and future planner context."},"surface":{"type":"string","enum":["dashboard","mcp_chatgpt_codex","claude_app","clay_provider","code_execution","gemini_enterprise"],"default":"mcp_chatgpt_codex"},"confirmed":{"type":"boolean","default":false,"description":"Required true for workflows that prepare exportable Clay rows."},"batchId":{"type":"string","description":"Optional Discover batch id used when preparing Clay rows."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"example":{"domain":"vercel.com","workflowId":"find_ready_leads","surface":"mcp_chatgpt_codex","limit":10}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadWorkflowRunResponse"},"example":{"status":"completed","workflowId":"find_ready_leads","surface":"mcp_chatgpt_codex","session":{"id":"ds_review_123","name":"Vercel developer intent","status":"ready","domain":"vercel.com"},"developers":[{"githubUser":"vercel-engineer","githubUrl":"https://github.com/vercel-engineer","displayName":null,"company":"Vercel","signalScore":72,"topSignal":"Starred and forked PostHog/posthog-js","qualityBucket":"evaluator","whyIncluded":"Recent GitHub activity in a relevant analytics repo with company match."}],"companies":[{"companyName":"Vercel","developerCount":1,"signalScore":72,"topDevelopers":["vercel-engineer"],"topRepos":["PostHog/posthog-js"],"evidence":["https://github.com/PostHog/posthog-js"],"recommendedAction":"Enrich in Clay and personalize outreach with GitHub evidence."}],"guardrails":["Uses existing LeadCognition Discover sessions and service-layer results only.","Does not run ad-hoc raw BigQuery scans.","Does not unlock identity fields or spend credits."],"nextStep":"Review the ranked developers and companies, then run build_clay_outbound with confirmed=true when ready to prepare Clay rows."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:export","requestId":"req_example_123"}}}}}}}},"/api/v1/developer-intent":{"post":{"summary":"Find developers showing GitHub intent","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"LeadCognition Discover session id."},"domain":{"type":"string","description":"Domain used to locate a recent Discover session."},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10}}},"example":{"domain":"vercel.com","limit":10}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperIntentResponse"},"example":{"session":{"id":"ds_review_123","name":"Vercel developer intent","status":"ready","domain":"vercel.com"},"developers":[{"githubUser":"vercel-engineer","githubUrl":"https://github.com/vercel-engineer","displayName":null,"company":"Vercel","signalScore":72,"topSignal":"Starred and forked PostHog/posthog-js","qualityBucket":"evaluator","whyIncluded":"Recent GitHub activity in a relevant analytics repo with company match."}],"nextStep":"Prepare a Clay export when these developers are relevant to outreach."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/company-intent":{"post":{"summary":"Rank companies showing GitHub intent","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","description":"LeadCognition Discover session id."},"domain":{"type":"string","description":"Domain used to locate a recent Discover session."},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10}}},"example":{"domain":"vercel.com","limit":10}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyIntentResponse"},"example":{"session":{"id":"ds_review_123","name":"Vercel developer intent","status":"ready","domain":"vercel.com"},"companies":[{"companyName":"Vercel","developerCount":2,"signalScore":72,"topDevelopers":["vercel-engineer"],"topRepos":["PostHog/posthog-js"],"evidence":["https://github.com/PostHog/posthog-js"],"recommendedAction":"Enrich in Clay and personalize outreach with GitHub evidence."}],"nextStep":"Use /api/v1/clay/export for flat rows."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/clay/export":{"post":{"summary":"Prepare Clay-ready export rows","description":"Requires an org API key with mcp:export.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"domain":{"type":"string"},"batchId":{"type":"string","description":"Optional Discover batch id for enriched batch rows."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100}}},"example":{"domain":"vercel.com","limit":25}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClayExportResponse"},"example":{"session":{"id":"ds_review_123","name":"Vercel developer intent","status":"ready","domain":"vercel.com"},"rows":[{"company_name":"Vercel","company_domain":"vercel.com","company_domain_status":"matched","github_signal_summary":"vercel-engineer starred and forked posthog/posthog-js in the last 30 days.","signal_evidence_url":"https://github.com/PostHog/posthog-js","signal_evidence_repos":"PostHog/posthog-js | vercel/next.js","signal_score":72,"signal_count":3,"quality_bucket":"evaluator","last_signal_at":"2026-05-01T09:15:22Z","top_repo":"PostHog/posthog-js","top_signal_type":"WatchEvent","lead_name":"","github_username":"vercel-engineer","github_url":"https://github.com/vercel-engineer","linkedin_url":"","work_email":"","recommended_action":"Medium intent. Enrich company and contact in Clay, then personalize outreach using the GitHub evidence."}],"csv":{"fileName":"leadcognition-vercel-export.csv","contentType":"text/csv","content":"company_name,company_domain,github_username,signal_score\nVercel,vercel.com,vercel-engineer,72\n"},"nextStep":"Import the CSV into Clay or call /api/v1/clay/send with a webhook URL."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:export","requestId":"req_example_123"}}}}}}}},"/api/v1/clay/send":{"post":{"summary":"Send Clay-ready rows to a webhook","description":"Requires an org API key with mcp:export.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"domain":{"type":"string"},"batchId":{"type":"string","description":"Optional Discover batch id for enriched batch rows."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100},"clayWebhookUrl":{"type":"string","format":"uri","description":"Clay or webhook.site URL that receives one JSON POST per row."},"clayWebhookAuthToken":{"type":"string","description":"Optional bearer token sent to the Clay webhook."}},"required":["clayWebhookUrl"]},"example":{"domain":"vercel.com","limit":10,"clayWebhookUrl":"https://webhook.site/00000000-0000-4000-8000-000000000000"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendToClayResponse"},"example":{"session":{"id":"ds_review_123","name":"Vercel developer intent","status":"ready","domain":"vercel.com"},"rowCount":1,"acceptedCount":1,"failedCount":0,"rowsPreview":[{"company_name":"Vercel","company_domain":"vercel.com","company_domain_status":"matched","github_signal_summary":"vercel-engineer starred and forked posthog/posthog-js in the last 30 days.","signal_evidence_url":"https://github.com/PostHog/posthog-js","signal_evidence_repos":"PostHog/posthog-js | vercel/next.js","signal_score":72,"signal_count":3,"quality_bucket":"evaluator","last_signal_at":"2026-05-01T09:15:22Z","top_repo":"PostHog/posthog-js","top_signal_type":"WatchEvent","lead_name":"","github_username":"vercel-engineer","github_url":"https://github.com/vercel-engineer","linkedin_url":"","work_email":"","recommended_action":"Medium intent. Enrich company and contact in Clay, then personalize outreach using the GitHub evidence."}],"nextStep":"Open Clay and confirm the row mapped into the expected columns."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:export","requestId":"req_example_123"}}}}}}}},"/api/v1/clay/source":{"post":{"summary":"Clay Source — domain-driven cold-start of a Clay table","description":"Returns paginated Clay rows for a domain. Auto-resolves the most recent Discover session for that domain. Use this as the data source when adding a new HTTP integration in Clay. If no session exists yet, the response sets status=\"no_session\" with a recommendedAction string Clay can render — no error.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Target company domain (e.g. stripe.com or https://stripe.com — normalized server-side)."},"lookbackDays":{"type":"integer","minimum":1,"maximum":365,"default":90},"cursor":{"type":"string","description":"Pagination cursor returned in a previous response. Pass to continue paging."},"limit":{"type":"integer","minimum":1,"maximum":200,"default":50}}},"example":{"domain":"vercel.com","lookbackDays":90,"limit":50}}}},"responses":{"200":{"description":"Source rows + cursor (or no_session status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaySourceResponse"},"example":{"session":{"id":"ds_review_123","name":"Vercel developer intent","status":"ready","domain":"vercel.com"},"rows":[{"company_name":"Vercel","company_domain":"vercel.com","company_domain_status":"matched","github_signal_summary":"vercel-engineer starred and forked posthog/posthog-js in the last 30 days.","signal_evidence_url":"https://github.com/PostHog/posthog-js","signal_evidence_repos":"PostHog/posthog-js | vercel/next.js","signal_score":72,"signal_count":3,"quality_bucket":"evaluator","last_signal_at":"2026-05-01T09:15:22Z","top_repo":"PostHog/posthog-js","top_signal_type":"WatchEvent","lead_name":"","github_username":"vercel-engineer","github_url":"https://github.com/vercel-engineer","linkedin_url":"","work_email":"","recommended_action":"Medium intent. Enrich company and contact in Clay, then personalize outreach using the GitHub evidence."}],"cursor":null,"rowCount":1,"totalAvailable":1,"status":"ready","recommendedAction":"Map the returned fields into Clay columns and enrich work email.","nextStep":"Use the evidence URL for personalization."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:export","requestId":"req_example_123"}}}}}}}},"/api/v1/deanon":{"post":{"summary":"De-anon a GitHub username → LinkedIn (DataForGTM)","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["githubUser"],"properties":{"githubUser":{"type":"string","description":"GitHub login/username (with or without leading @)."},"githubName":{"type":"string","description":"Optional display-name hint; otherwise fetched from the GitHub profile."},"githubCompany":{"type":"string","description":"Optional company hint; otherwise fetched from the GitHub profile."}}},"example":{"githubUser":"torvalds"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeanonResponse"},"example":{"githubUser":"torvalds","linkedin":"https://www.linkedin.com/in/linustorvalds","confidence":70,"method":"serp","matchedSlug":"linustorvalds"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/deanon/batch":{"post":{"summary":"De-anon up to 50 GitHub usernames → LinkedIn (DataForGTM)","description":"Requires an org API key with mcp:read.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["githubUsers"],"properties":{"githubUsers":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50,"description":"GitHub logins (max 50). Processed sequentially."}}},"example":{"githubUsers":["torvalds","gaearon"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeanonBatchResponse"},"example":{"results":[{"githubUser":"torvalds","linkedin":"https://www.linkedin.com/in/linustorvalds","confidence":70,"method":"serp","matchedSlug":"linustorvalds"}],"count":1}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/signup":{"post":{"summary":"Self-serve trial signup (LC-172)","description":"Public, no auth. Creates a pending trial signup and sends a magic-link email. Rate-limited 5/IP/hour and 3/email-domain/24h. One trial per workspace_domain. Disposable email domains are blocked.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"workspace_domain":{"type":"string","description":"Optional. Defaults to the email's domain. Used for trial-per-domain enforcement."},"signup_source":{"type":"string","description":"Channel attribution. e.g. clay_directory, mcp_claude, mcp_cursor, mcp_chatgpt, mcp_smithery, direct_api."},"intended_use":{"type":"string"}}},"example":{"email":"reviewer@example.com","workspace_domain":"example.com","signup_source":"mcp_chatgpt","intended_use":"clay_source"}}}},"responses":{"200":{"description":"Magic link sent (or trial_already_used status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"},"example":{"status":"magic_link_sent","email":"reviewer@example.com","workspace_domain":"example.com","next_step":"Check your email for the activation link."}}}},"400":{"description":"Invalid request or rate-limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Email is required.","requestId":"req_example_123"}}}}}}}},"/api/v1/signup/activate":{"get":{"summary":"Activate a trial via magic-link token (LC-172)","description":"Magic-link landing. Single-use, 24h TTL. **Requires a logged-in Better Auth session** — without one, returns a 302 redirect to /login?next=<this url>. After Google OAuth, the user lands back here and the activation completes. Verifies session.user.email matches the signup email before issuing the key. Returns an HTML page (not JSON) — this is a browser flow.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"64-char hex token from the magic-link email."}],"responses":{"200":{"description":"HTML page rendering the API key on success, or already-activated / expired / error state."},"302":{"description":"Redirect to /login?next=... when no Better Auth session is present."},"400":{"description":"Invalid or malformed token (only when token query param fails basic validation)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/clay/enrich":{"post":{"summary":"Clay Action — column-level enrichment for a domain","description":"Returns a single Clay row aggregating all GitHub-signal evidence for a given company domain. Backed by the org_lead_data materialized view; instant and cheap. Use this as a Clay column-enrichment action against existing rows.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Target company domain (e.g. stripe.com — normalized server-side)."}}},"example":{"domain":"vercel.com"}}}},"responses":{"200":{"description":"Enriched row (or not_found status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClayEnrichResponse"},"example":{"domain":"vercel.com","row":{"company_name":"Vercel","company_domain":"vercel.com","company_domain_status":"matched","github_signal_summary":"vercel-engineer starred and forked posthog/posthog-js in the last 30 days.","signal_evidence_url":"https://github.com/PostHog/posthog-js","signal_evidence_repos":"PostHog/posthog-js | vercel/next.js","signal_score":72,"signal_count":3,"quality_bucket":"evaluator","last_signal_at":"2026-05-01T09:15:22Z","top_repo":"PostHog/posthog-js","top_signal_type":"WatchEvent","lead_name":"","github_username":"vercel-engineer","github_url":"https://github.com/vercel-engineer","linkedin_url":"","work_email":"","recommended_action":"Medium intent. Enrich company and contact in Clay, then personalize outreach using the GitHub evidence."},"status":"ready","recommendedAction":"Enrich the row in Clay and route high-score accounts to outbound."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"invalid_request","message":"Missing or invalid API key.","requestId":"req_example_123"}}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"insufficient_scope","message":"API key is missing required scope: mcp:read","requestId":"req_example_123"}}}}}}}},"/api/v1/company-signals/{domain}":{"get":{"summary":"List recent company signals — durable, paginated","description":"Returns developers at a company who have shown GitHub intent signals, ordered by most-recent first. Use the `since` cursor to poll continuously in Clay without creating a Discover session.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Company domain (e.g. stripe.com)."},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor returned as nextCursor from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated company signal rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySignalsResponse"},"example":{"rows":[{"lead_id":"lead_example_123","github_user":"vercel-engineer","full_name":null,"job_title":null,"linkedin_url":null,"work_email":null,"company_name":"Vercel","company_domain":"vercel.com","signal_count":3,"unique_repo_count":2,"last_signal_date":"2026-05-01T09:15:22Z","engagement_score":72,"engagement_tier":"medium","top_repos":["PostHog/posthog-js"]}],"nextCursor":null}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/company-intel/{domain}":{"get":{"summary":"Get company-level intent rollup","description":"Returns a single aggregated rollup for a company domain: developer count, total signals, top repos, and engagement summary. Cached for 60s.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"Company domain (e.g. stripe.com)."}],"responses":{"200":{"description":"Company intel rollup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyIntelResponse"},"example":{"domain":"vercel.com","company_name":"Vercel","developer_count":2,"total_signal_count":5,"avg_engagement_score":68,"top_developers":[],"top_repos":["PostHog/posthog-js","open-telemetry/opentelemetry-collector"],"last_signal_date":"2026-05-01T09:15:22Z","next_step":"Prepare Clay rows for the highest-scoring developers."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/contributor-affiliation/{company}":{"get":{"summary":"List developers affiliated with a company or GitHub org","description":"Resolve which tracked developers are affiliated with a company. Pass a company domain (e.g. 'acme.com') or a GitHub org login (e.g. 'vercel'). Returns each affiliated developer with the repos they've signalled on as evidence, plus LinkedIn URL and engagement. Cached for 60s.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"company","in":"path","required":true,"schema":{"type":"string"},"description":"Company domain ('acme.com') or GitHub org login ('vercel')."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Max contributors to return."}],"responses":{"200":{"description":"Contributor affiliation list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorAffiliationResponse"},"example":{"query":"vercel","affiliation_kind":"github_org","company_name":"Vercel","contributor_count":2,"total_signal_count":17,"contributors":[{"github_user":"jsmith-dev","full_name":"Jordan Smith","job_title":"Senior Backend Engineer","linkedin_url":"https://linkedin.com/in/jsmith-dev","company_name":"Vercel","company_domain":"vercel.com","affiliated_repos":["vercel/next.js"],"signal_count":12,"unique_repo_count":3,"engagement_score":0.82,"engagement_tier":"high","last_signal_date":"2026-05-01T09:15:22Z"}],"next_step":"Call discover_developer_intent on a github_user to resolve LinkedIn + intent."}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/subscriptions":{"post":{"summary":"Create a webhook subscription","description":"Creates a new webhook subscription for the authenticated org. The secret is returned ONCE on creation only. Requires mcp:export scope.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","eventTypes"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL that will receive webhook POSTs."},"eventTypes":{"type":"array","items":{"type":"string","enum":["signal.discovered","lead.identified","unlock.completed","subscription.upgraded"]},"minItems":1},"description":{"type":"string"}}},"example":{"url":"https://example.com/leadcognition/webhooks","eventTypes":["signal.discovered"],"description":"Reviewer sandbox webhook"}}}},"responses":{"201":{"description":"Subscription created (includes secret, shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionSecret"},"example":{"id":"whsub_example_123","url":"https://example.com/leadcognition/webhooks","eventTypes":["signal.discovered"],"description":"Reviewer sandbox webhook","isActive":true,"createdAt":"2026-05-01T09:15:22Z","secret":"whsec_example_shown_once"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"summary":"List webhook subscriptions","description":"Returns all webhook subscriptions for the authenticated org. Secrets are never returned in list responses. Requires mcp:export scope.","security":[{"apiKeyBearer":[]}],"responses":{"200":{"description":"List of subscriptions (no secrets)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionsListResponse"},"example":{"total":1,"subscriptions":[{"id":"whsub_example_123","url":"https://example.com/leadcognition/webhooks","eventTypes":["signal.discovered"],"description":"Reviewer sandbox webhook","isActive":true,"createdAt":"2026-05-01T09:15:22Z","updatedAt":"2026-05-01T09:15:22Z"}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/subscriptions/{id}":{"delete":{"summary":"Revoke a webhook subscription","description":"Sets is_active=false on the subscription. In-flight deliveries may still complete. Requires mcp:export scope.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription UUID."}],"responses":{"200":{"description":"Subscription revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRevokeResult"},"example":{"revoked":true,"id":"whsub_example_123"}}}},"400":{"description":"Not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/webhooks/test/{id}":{"post":{"summary":"Send a test event to a webhook subscription","description":"Sends a sample signal.discovered event to the subscription URL. Returns the HTTP status received. Requires mcp:export scope.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Subscription UUID."}],"responses":{"200":{"description":"Delivery result (ok, status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryResult"},"example":{"ok":true,"status":200}}}},"400":{"description":"Not found, revoked, or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/developer-signals":{"get":{"summary":"List developer signals for a repo or org","description":"Returns developers who have signalled activity on a specific GitHub repo (owner/repo) or org (owner). Paginate with `since` to poll for new signals continuously.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"repo_or_org","in":"query","required":true,"schema":{"type":"string"},"description":"GitHub repo ('owner/repo') or org ('owner'). Example: facebook/react or stripe."},{"name":"since","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor returned as nextCursor from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated developer signal rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSignalsResponse"},"example":{"rows":[{"lead_id":"lead_example_123","github_user":"vercel-engineer","full_name":null,"job_title":null,"company_name":"Vercel","company_domain":"vercel.com","last_signal_date":"2026-05-01T09:15:22Z","signal_count":3,"engagement_score":72,"matching_repos":["PostHog/posthog-js"]}],"nextCursor":null}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is missing the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"apiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"LeadCognition API key"}},"schemas":{"DeanonResponse":{"type":"object","required":["githubUser","linkedin","confidence","method","matchedSlug"],"properties":{"githubUser":{"type":"string"},"linkedin":{"type":["string","null"],"description":"Resolved LinkedIn profile URL, or null if not found."},"confidence":{"type":"number","description":"0–100. 100 = self-declared (free signal); SERP matches score by slug/name."},"method":{"type":"string","enum":["free-signal","serp","email-name-serp","miss","bot","thin_profile"],"description":"Path that produced the result."},"matchedSlug":{"type":["string","null"],"description":"LinkedIn /in/<slug> that matched, for SERP results."},"tier":{"type":["string","null"],"enum":["verified","probable",null],"description":"Match confidence tier (v1.1.0): 'verified' = GitHub login matches the LinkedIn slug (high precision); 'probable' = strong name match without login overlap (~90% precision). null on a miss. Filter to 'verified' when precision matters most."}}},"DeanonBatchResponse":{"type":"object","required":["results","count"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/DeanonResponse"}},"count":{"type":"integer"}}},"ErrorResponse":{"type":"object","required":["error"],"example":{"error":{"code":"invalid_request","message":"Request body is invalid.","requestId":"req_example_123"}},"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_request","insufficient_scope"]},"message":{"type":"string"},"requestId":{"type":["string","null"]}}}}},"HealthResponse":{"type":"object","required":["ok","name","version"],"properties":{"ok":{"type":"boolean"},"name":{"type":"string"},"version":{"type":"string"}}},"SessionSummary":{"type":"object","required":["id","name","status","domain"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"domain":{"type":"string"}}},"DiscoverySessionSummary":{"type":"object","required":["id","name","domain","status","createdAt","recommendedNextAction"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string"},"totalLeads":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"},"recommendedNextAction":{"type":"string"}}},"DiscoverySessionsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/DiscoverySessionSummary"}},"nextStep":{"type":"string"}}},"WorkflowQuestion":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","textarea","select","multiselect","number"]},"required":{"type":"boolean"},"placeholder":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}}}},"WorkflowGuardrail":{"type":"object","properties":{"queryMode":{"type":"string","enum":["cached","curated_bigquery","discover_preview","clay_export"]},"dataScan":{"type":"string","enum":["none","existing_session","curated_bounded","discover_preview_required"]},"creditSpend":{"type":"string","enum":["none","confirmation_required","not_supported_yet"]},"note":{"type":"string"}}},"WorkflowAction":{"type":"object","description":"Discriminated action. Type-specific fields may include href, questionIds, toolName, surface, or requiresConfirmation.","required":["type","label"],"properties":{"type":{"type":"string","enum":["navigate","ask_followup","call_mcp_tool","open_existing_surface"]},"label":{"type":"string"},"href":{"type":"string"},"questionIds":{"type":"array","items":{"type":"string"}},"toolName":{"type":"string","enum":["run_lead_workflow","list_discovery_sessions","prepare_clay_export"]},"surface":{"type":"string","enum":["discover","leads","settings_api_keys"]},"requiresConfirmation":{"type":"boolean"}}},"LeadWorkflowOption":{"type":"object","properties":{"id":{"type":"string","enum":["discover_market","find_ready_leads","rank_high_intent_companies","watch_competitors","build_clay_outbound"]},"title":{"type":"string"},"description":{"type":"string"},"bestFor":{"type":"string"},"expectedOutput":{"type":"string"},"availability":{"type":"string","enum":["available_now","planned_handoff","requires_existing_session"]},"surfaces":{"type":"array","items":{"type":"string","enum":["dashboard","mcp_chatgpt_codex","claude_app","clay_provider","code_execution","gemini_enterprise"]}},"dataSources":{"type":"array","items":{"type":"string"}},"costGuardrail":{"$ref":"#/components/schemas/WorkflowGuardrail"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowQuestion"}},"primaryAction":{"$ref":"#/components/schemas/WorkflowAction"}}},"LeadWorkflowsProposeResponse":{"type":"object","properties":{"interpretedIntent":{"type":"string"},"recommendedWorkflowId":{"type":"string","enum":["discover_market","find_ready_leads","rank_high_intent_companies","watch_competitors","build_clay_outbound"]},"options":{"type":"array","items":{"$ref":"#/components/schemas/LeadWorkflowOption"}},"globalGuardrails":{"type":"array","items":{"type":"string"}}}},"LeadWorkflowPlanResponse":{"type":"object","properties":{"workflowId":{"type":"string","enum":["discover_market","find_ready_leads","rank_high_intent_companies","watch_competitors","build_clay_outbound"]},"title":{"type":"string"},"status":{"type":"string","enum":["needs_answers","ready_to_run","planned_handoff"]},"summary":{"type":"string"},"missingQuestionIds":{"type":"array","items":{"type":"string"}},"backendExecution":{"type":"array","items":{"type":"string"}},"recommendedActions":{"type":"array","items":{"$ref":"#/components/schemas/WorkflowAction"}},"surfaceAdaptation":{"type":"object","properties":{"chatgptCodex":{"type":"string"},"claude":{"type":"string"},"clay":{"type":"string"},"dashboard":{"type":"string"}}},"guardrails":{"type":"array","items":{"type":"string"}}}},"LeadWorkflowConfirmation":{"type":"object","properties":{"required":{"type":"boolean","const":true},"reason":{"type":"string"},"field":{"type":"string","const":"confirmed"},"value":{"type":"boolean","const":true}}},"LeadWorkflowRunResponse":{"type":"object","description":"Result from the backend-controlled run_lead_workflow tool. Shape depends on workflowId and whether confirmation is still required.","properties":{"status":{"type":"string","enum":["confirmation_required","completed"]},"workflowId":{"type":"string","enum":["find_ready_leads","build_clay_outbound"]},"surface":{"type":"string","enum":["dashboard","mcp_chatgpt_codex","claude_app","clay_provider","code_execution","gemini_enterprise"]},"confirmation":{"$ref":"#/components/schemas/LeadWorkflowConfirmation"},"session":{"$ref":"#/components/schemas/SessionSummary"},"developers":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperIntent"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyIntent"}},"clay":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionSummary"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ClayExportRow"}},"csv":{"$ref":"#/components/schemas/CsvExport"}}},"guardrails":{"type":"array","items":{"type":"string"}},"nextStep":{"type":"string"}}},"DeveloperIntent":{"type":"object","properties":{"githubUser":{"type":"string"},"githubUrl":{"type":"string","format":"uri"},"displayName":{"type":["string","null"]},"company":{"type":["string","null"]},"signalScore":{"type":"number"},"topSignal":{"type":"string"},"qualityBucket":{"type":"string"},"whyIncluded":{"type":"string"}}},"CompanyIntent":{"type":"object","properties":{"companyName":{"type":"string"},"developerCount":{"type":"integer"},"signalScore":{"type":"number"},"topDevelopers":{"type":"array","items":{"type":"string"}},"topRepos":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"string"}},"recommendedAction":{"type":"string"}}},"ClayExportRow":{"type":"object","description":"One Clay-importable row. Flat scalars; non-null defaults so column mapping is trivial.","properties":{"company_name":{"type":"string"},"company_domain":{"type":"string"},"company_domain_status":{"type":"string","enum":["matched","inferred","missing"],"description":"matched=resolved against LC companies table, inferred=session-context guess, missing=run domain enrichment in Clay."},"github_signal_summary":{"type":"string"},"signal_evidence_url":{"type":"string"},"signal_evidence_repos":{"type":"string","description":"Pipe-delimited list of up to 3 evidence repos (CSV-friendly)."},"signal_score":{"type":"number","description":"Aggregate intent score for the developer."},"signal_count":{"type":"integer","description":"Number of distinct evidence repos for this developer."},"quality_bucket":{"type":"string","description":"builder | evaluator | watcher | discusser."},"last_signal_at":{"type":"string","description":"ISO-8601 timestamp of the most recent GitHub event."},"top_repo":{"type":"string"},"top_signal_type":{"type":"string"},"lead_name":{"type":"string"},"github_username":{"type":"string"},"github_url":{"type":"string"},"linkedin_url":{"type":"string"},"work_email":{"type":"string"},"recommended_action":{"type":"string","description":"Per-row routing recommendation. Use as a Clay routing column."}}},"DeveloperIntentResponse":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionSummary"},"developers":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperIntent"}},"nextStep":{"type":"string"}}},"CompanyIntentResponse":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionSummary"},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyIntent"}},"nextStep":{"type":"string"}}},"ClayExportResponse":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionSummary"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ClayExportRow"}},"csv":{"type":"object","properties":{"fileName":{"type":"string"},"contentType":{"type":"string","const":"text/csv"},"content":{"type":"string"}}},"nextStep":{"type":"string"}}},"SignupResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["magic_link_sent","trial_already_used"]},"email":{"type":"string"},"workspace_domain":{"type":"string"},"next_step":{"type":"string"}}},"SignupActivateResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["activated","already_activated","pending_org_creation"]},"email":{"type":"string"},"workspace_domain":{"type":"string"},"api_key":{"type":"string","description":"Full API key, shown ONCE only at activation."},"scopes":{"type":"array","items":{"type":"string"}},"credits_remaining":{"type":"integer"},"next_step":{"type":"string"}}},"ClaySourceResponse":{"type":"object","required":["rows","status"],"properties":{"session":{"anyOf":[{"$ref":"#/components/schemas/SessionSummary"},{"type":"null"}]},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ClayExportRow"}},"cursor":{"type":["string","null"],"description":"Pagination cursor; null when no further rows."},"rowCount":{"type":"integer"},"totalAvailable":{"type":"integer"},"status":{"type":"string","enum":["ready","empty","no_session"]},"recommendedAction":{"type":"string"},"nextStep":{"type":"string"}}},"ClayEnrichResponse":{"type":"object","required":["domain","status"],"properties":{"domain":{"type":"string"},"row":{"anyOf":[{"$ref":"#/components/schemas/ClayExportRow"},{"type":"null"}]},"status":{"type":"string","enum":["ready","not_found"]},"recommendedAction":{"type":"string"}}},"SendToClayResponse":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/SessionSummary"},"rowCount":{"type":"integer"},"acceptedCount":{"type":"integer"},"failedCount":{"type":"integer"},"rowsPreview":{"type":"array","items":{"$ref":"#/components/schemas/ClayExportRow"}},"nextStep":{"type":"string"}}},"CompanySignalRow":{"type":"object","properties":{"lead_id":{"type":"string"},"github_user":{"type":"string"},"full_name":{"type":["string","null"]},"job_title":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"work_email":{"type":["string","null"]},"company_name":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"signal_count":{"type":"integer"},"unique_repo_count":{"type":"integer"},"last_signal_date":{"type":"string","format":"date-time"},"engagement_score":{"type":["number","null"]},"engagement_tier":{"type":["string","null"]},"top_repos":{"type":"array","items":{"type":"string"}}}},"CompanySignalsResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/CompanySignalRow"}},"nextCursor":{"type":["string","null"],"description":"Pass as `since` in the next request to continue paging."}}},"CompanyIntelResponse":{"type":"object","properties":{"domain":{"type":"string"},"company_name":{"type":["string","null"]},"developer_count":{"type":"integer"},"total_signal_count":{"type":"integer"},"avg_engagement_score":{"type":["number","null"]},"top_developers":{"type":"array","items":{"$ref":"#/components/schemas/CompanySignalRow"}},"top_repos":{"type":"array","items":{"type":"string"}},"last_signal_date":{"type":["string","null"],"format":"date-time"},"next_step":{"type":"string"}}},"DeveloperSignalRow":{"type":"object","properties":{"lead_id":{"type":"string"},"github_user":{"type":"string"},"full_name":{"type":["string","null"]},"job_title":{"type":["string","null"]},"company_name":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"last_signal_date":{"type":"string","format":"date-time"},"signal_count":{"type":"integer"},"engagement_score":{"type":["number","null"]},"matching_repos":{"type":"array","items":{"type":"string"}}}},"ContributorRow":{"type":"object","properties":{"github_user":{"type":"string"},"full_name":{"type":["string","null"]},"job_title":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"company_name":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"affiliated_repos":{"type":"array","items":{"type":"string"}},"signal_count":{"type":"integer"},"unique_repo_count":{"type":"integer"},"engagement_score":{"type":["number","null"]},"engagement_tier":{"type":["string","null"]},"last_signal_date":{"type":"string","format":"date-time"}}},"ContributorAffiliationResponse":{"type":"object","properties":{"query":{"type":"string"},"affiliation_kind":{"type":"string","enum":["company_domain","github_org"]},"company_name":{"type":["string","null"]},"contributor_count":{"type":"integer"},"total_signal_count":{"type":"integer"},"contributors":{"type":"array","items":{"$ref":"#/components/schemas/ContributorRow"}},"next_step":{"type":"string"}}},"DeveloperSignalsResponse":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSignalRow"}},"nextCursor":{"type":["string","null"],"description":"Pass as `since` in the next request to continue paging."}}},"WebhookSubscription":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WebhookSubscriptionSecret":{"type":"object","description":"Returned only on subscription creation. The secret field is shown exactly once.","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"eventTypes":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"HMAC signing secret (whsec_... prefix). Store securely — not returned after this."}}},"WebhookSubscriptionsListResponse":{"type":"object","properties":{"total":{"type":"integer"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"WebhookDeliveryResult":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"integer","description":"HTTP status received from the target URL (0 = network error)."}}},"WebhookRevokeResult":{"type":"object","properties":{"revoked":{"type":"boolean"},"id":{"type":"string"}}}}}}