{"openapi":"3.1.0","info":{"title":"Superlink API","version":"1.0.0","description":"One agentic endpoint — *find the best people for X*. State a goal; get back a ranked, scored shortlist plus a supply report. Search, evaluation, and enrichment are internal steps of the loop, not separately exposed."},"servers":[{"url":"https://api.superlink.ai"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/sourcing-runs":{"post":{"summary":"Start a sourcing run","description":"State a goal; a bounded agentic loop searches, evaluates against a synthesized scorecard, and converges on a ranked shortlist. Asynchronous — returns a run id to poll.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcingRunRequest"}}}},"responses":{"202":{"description":"Run queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRunResponse"}}}}}}},"/v1/sourcing-runs/{id}":{"get":{"summary":"Poll a sourcing run","description":"Poll until a terminal state. `progress` exposes the live loop trace; `result` carries the ranked shortlist and the supply report.","parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Current run status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcingRunStatus"}}}}}}}},"components":{"schemas":{"SourcingRunRequest":{"type":"object","properties":{"goal":{"description":"Natural-language objective, e.g. 'the 5 best infra engineers who've scaled distributed training'.","type":"string","minLength":1,"maxLength":4000},"jobDescription":{"description":"Pasted job description.","type":"string","maxLength":20000},"jobDescriptionUrl":{"description":"A URL to a job description — fetched and parsed server-side.","type":"string","format":"uri"},"hiringManagerNotes":{"type":"string","maxLength":8000},"exemplarLinkedinUrls":{"description":"Reference profiles — 'more like these'. LinkedIn URLs in goal/JD/notes are auto-extracted too.","maxItems":25,"type":"array","items":{"type":"string"}},"criteria":{"description":"Optional explicit scorecard dimensions; otherwise synthesized from the goal/JD/notes.","type":"object","properties":{"dimensions":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},"required":["dimensions"]},"excludeCompany":{"description":"Exclude this company's current employees (URL/slug/id/name). Workspace keys auto-use their own hiring company.","type":"string","maxLength":500},"targetCount":{"default":5,"description":"Maximum candidates to return (a ceiling).","type":"integer","minimum":1,"maximum":50},"minScore":{"default":7,"description":"Quality floor 0–10. Candidates below this are never returned.","type":"number","minimum":0,"maximum":10},"fetchNewSupply":{"default":true,"description":"Allow the loop to ingest net-new people. (Phase 2 — currently inert; the loop searches the indexed pool.)","type":"boolean"},"budget":{"default":{"maxRounds":8,"maxFetched":200,"maxDurationMs":1800000,"maxCostUsd":25},"$ref":"#/components/schemas/Budget"}}},"Budget":{"type":"object","properties":{"maxRounds":{"default":8,"description":"Max search rounds.","type":"integer","minimum":1,"maximum":20},"maxFetched":{"default":200,"description":"Cap on net-new profiles ingested per run (applies to fetch-new, Phase 2).","type":"integer","minimum":0,"maximum":2000},"maxDurationMs":{"default":1800000,"description":"Wall-clock ceiling for the run.","type":"integer","minimum":10000,"maximum":3600000},"maxCostUsd":{"default":25,"description":"Cumulative LLM spend ceiling across rounds.","type":"number","minimum":0,"maximum":500}}},"CreateRunResponse":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string","const":"queued"},"poll":{"type":"string"}},"required":["runId","status","poll"],"additionalProperties":false},"SourcingRunStatus":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"progress":{"anyOf":[{"$ref":"#/components/schemas/SourcingRunProgress"},{"type":"null"}]},"result":{"anyOf":[{"$ref":"#/components/schemas/SourcingRunResult"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","status","progress","result","error"],"additionalProperties":false},"SourcingRunProgress":{"type":"object","properties":{"round":{"type":"number"},"phase":{"type":"string"},"strongFound":{"type":"number"},"evaluated":{"type":"number"},"fetched":{"type":"number"}},"required":["round","phase","strongFound","evaluated","fetched"],"additionalProperties":false},"SourcingRunResult":{"type":"object","properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"supplyReport":{"$ref":"#/components/schemas/SupplyReport"}},"required":["candidates","supplyReport"],"additionalProperties":false},"Candidate":{"type":"object","properties":{"score":{"type":"number","description":"Weighted scorecard score, 0–10."},"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/Dimension"}},"analysis":{"anyOf":[{"type":"string"},{"type":"null"}]},"enrichment":{"$ref":"#/components/schemas/Enrichment"},"profile":{"type":"object","properties":{"name":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"linkedinUrl":{"type":"string"},"linkedinSlug":{"type":"string"},"headline":{"type":"string"},"location":{"type":"string"},"photoUrl":{"type":"string"},"summary":{"type":"string"},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"company":{"type":"string"},"location":{"type":"string"},"startDate":{"type":"string"},"startDateDisplay":{"type":"string"},"endDate":{"type":"string"},"endDateDisplay":{"type":"string"},"isCurrent":{"type":"boolean"},"description":{"type":"string"},"aiSummary":{"type":"string"},"companyLinkedinId":{"type":"string"},"companyDescription":{"type":"string"},"logoUrl":{"type":"string"}},"required":["title","company","isCurrent"],"additionalProperties":false}},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":"string"},"degree":{"type":"string"},"field":{"type":"string"},"startYear":{"type":"number"},"endYear":{"type":"number"},"isCurrent":{"type":"boolean"},"schoolLinkedinId":{"type":"string"},"schoolLinkedinUrl":{"type":"string"},"logoUrl":{"type":"string"},"activitiesAndSocieties":{"type":"string"}},"required":["school"],"additionalProperties":false}},"skills":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"proficiency":{"type":"string"}},"required":["name"],"additionalProperties":false}},"certifications":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"issuer":{"type":"string"},"issuedDate":{"type":"string"},"issuedDateDisplay":{"type":"string"},"expirationDate":{"type":"string"},"expirationDateDisplay":{"type":"string"},"url":{"type":"string"}},"required":["name"],"additionalProperties":false}},"honors":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"issuer":{"type":"string"},"issuedDate":{"type":"string"},"issuedDateDisplay":{"type":"string"},"description":{"type":"string"}},"required":["title"],"additionalProperties":false}},"yearsOfExperience":{"type":"number"},"twitterSlug":{"type":"string"},"numConnections":{"type":"number"},"github":{"type":"object","properties":{"username":{"type":"string"},"id":{"type":"number"},"bio":{"type":"string"},"company":{"type":"string"},"location":{"type":"string"},"email":{"type":"string"},"blog":{"type":"string"},"twitterUsername":{"type":"string"},"publicRepos":{"type":"number"},"followers":{"type":"number"},"createdAt":{"type":"string"},"topLanguages":{"type":"array","items":{"type":"string"}},"topTopics":{"type":"array","items":{"type":"string"}},"languageStats":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"repos":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"ownerLogin":{"type":"string"},"description":{"type":"string"},"stars":{"type":"number"},"forks":{"type":"number"},"language":{"type":"string"},"url":{"type":"string"},"isFork":{"type":"boolean"},"isArchived":{"type":"boolean"},"pushedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["name","stars","url"],"additionalProperties":false}},"contributedToRepos":{"type":"array","items":{"type":"object","properties":{"repoFullName":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"stars":{"type":"number"},"language":{"type":"string"},"commitCount":{"type":"number"},"prCount":{"type":"number"},"firstContributionAt":{"type":"string"},"lastContributionAt":{"type":"string"},"source":{"type":"string","enum":["repo_import","events_api","commit_search"]}},"required":["repoFullName","url","source"],"additionalProperties":false}},"profileReadme":{"type":"string"},"orgs":{"type":"array","items":{"type":"object","properties":{"login":{"type":"string"},"description":{"type":"string"}},"required":["login"],"additionalProperties":false}},"activitySummary":{"type":"object","properties":{"firstRepoCreatedAt":{"type":"string"},"lastPushAt":{"type":"string"},"activeYears":{"type":"string"},"isCurrentlyActive":{"type":"boolean"}},"additionalProperties":false},"builderSignals":{"type":"object","properties":{"recentActivityScore":{"type":"number"},"reposCreatedLast12Months":{"type":"number"},"reposActiveLast90Days":{"type":"number"},"externalContributionRecency":{"type":"string"},"totalExternalCommits":{"type":"number"},"accountAgeYears":{"type":"number"},"followerRatio":{"type":"number"},"eventWindowPrCount":{"type":"number"},"eventWindowIssueCount":{"type":"number"},"eventWindowReposActive":{"type":"number"}},"required":["recentActivityScore","reposCreatedLast12Months","reposActiveLast90Days","totalExternalCommits","accountAgeYears","followerRatio"],"additionalProperties":false},"repoDetails":{"type":"array","items":{"type":"object","properties":{"repoFullName":{"type":"string"},"dependencies":{"type":"array","items":{"type":"string"}},"packageEcosystem":{"type":"string"},"summary":{"type":"string"}},"required":["repoFullName"],"additionalProperties":false}}},"required":["username"],"additionalProperties":false},"huggingface":{"type":"object","properties":{"username":{"type":"string"},"fullname":{"type":"string"},"bio":{"type":"string"},"isPro":{"type":"boolean"},"createdAt":{"type":"string"},"numModels":{"type":"number"},"numDatasets":{"type":"number"},"numSpaces":{"type":"number"},"numPapers":{"type":"number"},"numFollowers":{"type":"number"},"orgs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"fullname":{"type":"string"}},"required":["name","fullname"],"additionalProperties":false}},"topModels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"downloads":{"type":"number"},"likes":{"type":"number"},"pipeline_tag":{"type":"string"},"cardSummary":{"type":"string"}},"required":["id","downloads","likes"],"additionalProperties":false}},"topDatasets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"downloads":{"type":"number"},"likes":{"type":"number"}},"required":["id","downloads","likes"],"additionalProperties":false}},"topSpaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"likes":{"type":"number"},"sdk":{"type":"string"}},"required":["id","likes"],"additionalProperties":false}},"topPapers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"publishedAt":{"type":"string"},"upvotes":{"type":"number"},"summary":{"type":"string"}},"required":["id","title","publishedAt","upvotes"],"additionalProperties":false}},"aiDomains":{"type":"array","items":{"type":"string"}},"lastActivityAt":{"type":"string"},"naturalLanguages":{"type":"array","items":{"type":"string"}}},"required":["username","isPro","createdAt","numModels","numDatasets","numSpaces","numPapers","numFollowers","orgs"],"additionalProperties":false},"linkedinActivity":{"type":"object","properties":{"activitySummary":{"type":"string"},"posts":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"url":{"type":"string"},"date":{"type":"string"},"reactions":{"type":"number"},"comments":{"type":"number"},"shares":{"type":"number"},"isRepost":{"type":"boolean"}},"required":["text"],"additionalProperties":false}},"topicalStances":{"type":"array","items":{"type":"string"}},"contentThemes":{"type":"array","items":{"type":"object","properties":{"theme":{"type":"string"},"description":{"type":"string"}},"required":["theme","description"],"additionalProperties":false}},"aiBuilderSignal":{"type":"object","properties":{"score":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}}},"required":["score","evidence"],"additionalProperties":false},"aiAvailabilitySignal":{"type":"object","properties":{"score":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}}},"required":["score","evidence"],"additionalProperties":false}},"required":["posts"],"additionalProperties":false},"sources":{"type":"array","items":{"type":"string","enum":["MANUAL_OVERRIDE","BIO_SIGNALS","FULLENRICH","CRUSTDATA_CONTACT","CRUSTDATA","CRUSTDATA_POSTS","GITHUB","HUGGINGFACE","PERSONAL_WEBSITE","WEB_SEARCH","SOCIAL_SEARCH","SCHOLAR","PATENT","CRM","CONTEXT_SEED"]}},"contacts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"channel":{"type":"string","enum":["email","phone"]},"type":{"type":"string","enum":["work","personal","unknown"]},"status":{"anyOf":[{"type":"string","enum":["active","undeliverable","outdated","unsubscribed","invalid"]},{"type":"null"}]},"source":{"type":"string"},"discoveredOn":{"type":"string"}},"required":["value","channel","source","discoveredOn"],"additionalProperties":false}},"papers":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"authors":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"year":{"type":"number"},"citations":{"type":"number"},"source":{"type":"string"},"venue":{"type":"string"},"arxivId":{"type":"string"},"doi":{"type":"string"}},"required":["title","authors"],"additionalProperties":false}},"patents":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"patentNumber":{"type":"string"},"inventors":{"type":"array","items":{"type":"string"}},"assignee":{"type":"string"},"filingDate":{"type":"string"},"url":{"type":"string"},"source":{"type":"string"}},"required":["title","patentNumber","inventors"],"additionalProperties":false}},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"type":{"type":"string","enum":["social","article","news","talk","event","project","patent","company","other"]},"platform":{"type":"string","enum":["twitter","github","linkedin","youtube","medium","stackoverflow","dribbble","behance","substack","mastodon","bluesky","threads","producthunt","devto","huggingface","kaggle","google_scholar","other"]},"title":{"type":"string"},"date":{"type":"string"},"source":{"type":"string"}},"required":["url","type"],"additionalProperties":false}},"personalWebsite":{"type":"string"},"interests":{"type":"array","items":{"type":"string"}},"vendorInsights":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["MANUAL_OVERRIDE","BIO_SIGNALS","FULLENRICH","CRUSTDATA_CONTACT","CRUSTDATA","CRUSTDATA_POSTS","GITHUB","HUGGINGFACE","PERSONAL_WEBSITE","WEB_SEARCH","SOCIAL_SEARCH","SCHOLAR","PATENT","CRM","CONTEXT_SEED"]},"summary":{"type":"string"}},"required":["source","summary"],"additionalProperties":false}},"masterSummary":{"type":"string"},"generatedHeadline":{"type":"string"},"headlineAction":{"type":"string","enum":["replace","keep_original"]},"linkedinOpenToCards":{"type":"array","items":{"type":"string"}},"linkedinJoinedDate":{"type":"string"},"linkedinVerifications":{"type":"array","items":{"type":"string"}},"compensationEstimate":{"type":"object","properties":{"total_comp_median":{"type":"number"},"total_comp_p25":{"type":"number"},"total_comp_p75":{"type":"number"},"rationale":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"debug":{"anyOf":[{"type":"object","properties":{"reference_company":{"type":"string"},"reference_title":{"type":"string"},"base_salary":{"type":"object","properties":{"median":{"type":"number"},"p25":{"type":"number"},"p75":{"type":"number"}},"required":["median","p25","p75"],"additionalProperties":false},"target_bonus":{"type":"object","properties":{"median":{"type":"number"},"p25":{"type":"number"},"p75":{"type":"number"}},"required":["median","p25","p75"],"additionalProperties":false},"equity_annualized":{"type":"object","properties":{"median":{"type":"number"},"p25":{"type":"number"},"p75":{"type":"number"}},"required":["median","p25","p75"],"additionalProperties":false},"sign_on_amortized":{"anyOf":[{"type":"object","properties":{"median":{"type":"number"},"p25":{"type":"number"},"p75":{"type":"number"}},"required":["median","p25","p75"],"additionalProperties":false},{"type":"null"}]},"citations":{"type":"array","items":{"type":"string"}}},"required":["reference_company","reference_title","base_salary","target_bonus","equity_annualized","sign_on_amortized","citations"],"additionalProperties":false},{"type":"null"}]}},"required":["total_comp_median","total_comp_p25","total_comp_p75","rationale","confidence","debug"],"additionalProperties":false},"siteQuality":{"type":"object","properties":{"isCustomBuilt":{"type":"boolean"},"hasActiveBlog":{"type":"boolean"},"hasTechnicalDepth":{"type":"boolean"},"hasInteractiveElements":{"type":"boolean"},"lastContentUpdate":{"type":"string"},"overallCraftScore":{"type":"number"}},"required":["isCustomBuilt","hasActiveBlog","hasTechnicalDepth","hasInteractiveElements","overallCraftScore"],"additionalProperties":false},"builderSignal":{"type":"object","properties":{"score":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}},"computedAt":{"type":"string"}},"required":["score","evidence"],"additionalProperties":false},"availabilitySignal":{"type":"object","properties":{"score":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}},"computedAt":{"type":"string"}},"required":["score","evidence"],"additionalProperties":false},"linkedinPhotoHash":{"type":"string"}},"required":["name","experience","education","skills","sources"],"additionalProperties":false,"description":"Canonical profile. Image URLs are proxied through api.superlink.ai."}},"required":["score","dimensions","analysis","enrichment","profile"],"additionalProperties":false},"Dimension":{"type":"object","properties":{"name":{"type":"string"},"score":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"type":"number"},"explanation":{"type":"string"}},"required":["name","score","weight","explanation"],"additionalProperties":false},"Enrichment":{"type":"object","properties":{"depth":{"type":"string","enum":["shallow","indexed","deep"]},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"version":{"anyOf":[{"type":"number"},{"type":"null"}]},"outdated":{"type":"boolean"},"sources":{"type":"array","items":{"type":"string"}},"signals":{"type":"object","properties":{"builder":{"type":"boolean"},"availability":{"type":"boolean"}},"required":["builder","availability"],"additionalProperties":false}},"required":["depth","step","version","outdated","sources","signals"],"additionalProperties":false},"SupplyReport":{"type":"object","properties":{"rounds":{"type":"number"},"totalEvaluated":{"type":"number"},"newProfilesFetched":{"type":"number"},"stoppedReason":{"type":"string","enum":["converged","budget_exhausted","supply_exhausted"]},"confidence":{"type":"string","enum":["low","medium","high"]},"gaps":{"type":"array","items":{"type":"string"}}},"required":["rounds","totalEvaluated","newProfilesFetched","stoppedReason","confidence","gaps"],"additionalProperties":false}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key, as `Authorization: Bearer sl_live_...`."}}}}