{"openapi":"3.1.0","info":{"title":"Trackly Public API","version":"1.0.0","summary":"Query jobs, companies, and your Trackly profile.","description":"Build on top of Trackly's large job catalog across thousands of companies. Query jobs, companies, and your Trackly profile from any language that can speak HTTPS.\n\n## Authentication\n\nAll endpoints require a bearer API key. Pass it in the `Authorization` header:\n\n```\nAuthorization: Bearer trk_your_key_here\n```\n\nMint keys at [usetrackly.app/developers](https://usetrackly.app/developers).\n\n## Rate limits\n\nAll 5 public endpoints share a uniform **10,000 requests/hour per user**. Exceeding the limit returns HTTP 429.\n\n## Defaults\n\nOmitted query params inherit the authenticated user's saved preferences from their Trackly account. For a new account with no saved preferences, the static fallback is `locationFilter=us`, `jobModality=full_time`, `wantsPM=true`. Because defaults are per-user, the same API key can return different results depending on whose key it is.\n\n## Stability\n\nSpec version `1.0.0`. Additive changes only without a major version bump.\n","contact":{"name":"Trackly API","url":"https://usetrackly.app/developers"},"license":{"name":"Trackly Terms","url":"https://usetrackly.app/terms"}},"servers":[{"url":"https://closeai.mba","description":"Production"}],"security":[{"TracklyAPIKey":[]}],"tags":[{"name":"Jobs","description":"Search and retrieve job postings."},{"name":"Companies","description":"List and search companies with hiring activity."},{"name":"User","description":"Authenticated user's profile and preferences."}],"paths":{"/api/v1/jobs":{"get":{"tags":["Jobs"],"summary":"List jobs","description":"Filter Trackly's job catalog by function, region, modality, and other criteria. Returns the list response shape (no `description`, no structured-JD fields). For full job details including description, fetch `GET /api/v1/jobs/{id}`.\n\n**Defaults:** Omitted params inherit the authenticated user's saved preferences. Static fallback for users with no saved prefs: `locationFilter=us`, `jobModality=full_time`, `wantsPM=true`.\n","operationId":"listJobs","parameters":[{"name":"jobFunction","in":"query","description":"Comma-separated list of job function values. Example: `finance,partnerships`. Accepts any subset of the 14 canonical values in `JobFunction`.\n","required":false,"schema":{"type":"string"},"examples":{"single":{"value":"finance"},"multiple":{"value":"finance,partnerships"}}},{"name":"locationFilter","in":"query","description":"Region tag filter. Two modes:\n\n- **Single-value:** `us`, `non_us`, `all`, or any single `RegionTag` value (e.g. `europe`, `remote`).\n- **Comma-list:** only `RegionTag` values are honored — `us`/`non_us`/`all` are silently dropped from a list. So `locationFilter=us,non_us` is parsed as `us` only.\n\nCity/state granularity is only available via `usStates`/`caProvinces`. Remote filtering: use `region=remote` or `usStates=REMOTE`/`caProvinces=REMOTE`. Hybrid and onsite are not supported as first-class filters.\n","required":false,"schema":{"type":"string"},"examples":{"single":{"value":"us"},"region":{"value":"europe"},"list":{"value":"europe,canada"}}},{"name":"jobModality","in":"query","description":"Employment type. `full_time` (default), `internship`, or `all`. Filters on the `is_internship` column — this is NOT remote/hybrid/onsite.\n","required":false,"schema":{"$ref":"#/components/schemas/JobModality"}},{"name":"search","in":"query","description":"Free-text keyword search across title, company, and description.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by the authenticated user's application-pipeline state for each job — not a job-posting status.\n","required":false,"schema":{"$ref":"#/components/schemas/JobStatus"}},{"name":"sort","in":"query","description":"Sort order.\n- `newest` (default) — most recently posted first.\n- `match` — highest match score first (requires resume on file).\n\nThe deprecated values `oldest` and `company` are rejected with HTTP 400.\n","required":false,"schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"limit","in":"query","description":"Page size, 1 through 100. Default 50.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Result offset for pagination. Default 0.","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"region","in":"query","description":"Comma-separated list of `RegionTag` values. Takes priority over `locationFilter` when both are set.\n","required":false,"schema":{"type":"string"},"example":"europe,canada"},{"name":"usStates","in":"query","description":"Comma-separated 2-letter US state codes (e.g. `NY,CA`). Include `REMOTE` to also match remote jobs. Invalid non-empty codes return HTTP 400. Under canonical hierarchical enforcement, selecting a state also selects the US parent and other selected regions remain active (for example, California plus Europe is an OR). During legacy or shadow rollout, explicit query parameters retain their compatibility behavior; persisted state selections remain inactive until canonical enforcement.\n","required":false,"schema":{"type":"string"},"example":"NY,CA,REMOTE"},{"name":"caProvinces","in":"query","description":"Comma-separated 2-letter Canadian province codes (e.g. `ON,BC`). Include `REMOTE` to also match remote jobs. Parent-scoped OR behavior for persisted provinces activates only with canonical hierarchical enforcement; explicit query parameters retain legacy compatibility behavior before then.\n","required":false,"schema":{"type":"string"},"example":"ON,BC"},{"name":"internshipLevels","in":"query","description":"Comma-separated list of internship levels. Applied to internship jobs when `jobModality=internship` or `jobModality=all`; in combined mode, full-time jobs remain unaffected. Values: `undergraduate`, `graduate`, `mba`, `not_specified`.\n","required":false,"schema":{"type":"string"},"example":"mba,graduate"},{"name":"companyId","in":"query","description":"Restrict results to a single company by its Trackly ID.","required":false,"schema":{"type":"integer"}},{"name":"favoriteCompaniesOnly","in":"query","description":"Limit results to the authenticated user's favorited companies.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of jobs matching the filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"},"examples":{"finance":{"summary":"Two finance jobs in the US","value":{"success":true,"jobs":[{"id":211202955,"externalId":"c019b11f-4fbb-46a2-bbad-338ba8f4bedb","title":"Agentic Finance Engineer","companyName":"Mercor","companyId":1059,"companyDomain":"mercor.com","companyLogoUrl":"https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fwww.mercor.com&size=128","companyLogoUrls":["https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fwww.mercor.com&size=128","https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fmercor.com&size=128","https://icons.duckduckgo.com/ip3/mercor.com.ico","https://ui-avatars.com/api/?name=m%20e&size=128&background=8b5cf6&color=fff&bold=true&format=png&length=2"],"location":"San Francisco","jobUrl":"https://jobs.ashbyhq.com/mercor/c019b11f-4fbb-46a2-bbad-338ba8f4bedb","atsSource":"ashby","autoApplySupported":false,"isPM":false,"isStrategyOps":false,"isPartnership":false,"jobFunction":"finance","postedAt":"2026-04-18T20:39:30.721Z","firstSeenAt":"2026-04-18T21:27:41.348Z","isNew":false,"isActive":true,"sponsorshipStatus":"unknown","sponsorshipEvidence":"No mention of sponsorship, work authorization, or visa status at all.","sponsorshipClassifier":"reused","region":"us","seniorityLevel":"mid","salaryRange":null,"visaSponsorship":null,"userStatus":null,"applyStartedAt":null,"appliedConfirmedAt":null,"statusUpdatedAt":null,"timeToApplyMinutes":null,"matchScore":null,"scoreModel":null,"matchReasons":[],"matchLabel":null,"matchConfidence":null,"matchConfidenceReasons":[],"missingSkills":[],"dimensionScores":[],"matchExplanation":null,"company":{"id":1059,"name":"Mercor","domain":"mercor.com","logoUrl":"https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fwww.mercor.com&size=128","logoUrls":["https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fwww.mercor.com&size=128","https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fmercor.com&size=128","https://icons.duckduckgo.com/ip3/mercor.com.ico","https://ui-avatars.com/api/?name=m%20e&size=128&background=8b5cf6&color=fff&bold=true&format=png&length=2"],"companyStage":"decacorn","fundingStage":"Later Stage VC","fundingSeries":"Series C","valuationMillions":10000,"lastFinancingDate":"2026-02-04T00:00:00.000Z","description":"Developer of an artificial intelligence-powered hiring platform.","ycBatch":null}}],"total":3,"hasMore":true,"autoApplyDevEnabled":false,"servedFromCache":false,"dataFreshnessMs":0,"pagination":{"total":3,"limit":2,"offset":0,"hasMore":true}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/jobs/{id}":{"get":{"tags":["Jobs"],"summary":"Get a job by ID","description":"Returns the full detail response including `description`, `descriptionHtml`, structured-JD fields (when available), and personalized match data for the authenticated user.\n","operationId":"getJob","parameters":[{"name":"id","in":"path","required":true,"description":"Trackly job ID (integer).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Full job detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetailResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/companies":{"get":{"tags":["Companies"],"summary":"List companies","description":"List companies with hiring activity. Responses include per-function job counts (`functionCounts`). Always pass `limit` — full responses can exceed 1MB.\n\nFilters applied: `locationFilter`, `usStates`, `caProvinces`, `jobModality`, `region`, `internshipLevels`. Same semantics as `/api/v1/jobs`.\n","operationId":"listCompanies","parameters":[{"name":"allowUnavailableCounts","in":"query","required":false,"description":"Exact opt-in value `1` permits HTTP 200 with all per-company job counts null when the bounded live aggregation times out. The response declares `countsState=unavailable` and `retryAfterSeconds=60`. Without this opt-in, the same failure remains HTTP 500; successful counts remain numeric. The retry hint is advisory and does not guarantee recovery.","schema":{"type":"string","enum":["1"]}},{"name":"locationFilter","in":"query","description":"See `/api/v1/jobs` for semantics.","required":false,"schema":{"type":"string"}},{"name":"jobModality","in":"query","description":"Employment type filter. See `/api/v1/jobs`.","required":false,"schema":{"$ref":"#/components/schemas/JobModality"}},{"name":"region","in":"query","description":"Comma-separated `RegionTag` values. See `/api/v1/jobs`.","required":false,"schema":{"type":"string"}},{"name":"usStates","in":"query","description":"Comma-separated 2-letter US state codes. Same hierarchy and validation semantics as `/api/v1/jobs`.","required":false,"schema":{"type":"string"}},{"name":"caProvinces","in":"query","description":"Comma-separated 2-letter Canadian province codes. Same hierarchy and validation semantics as `/api/v1/jobs`.","required":false,"schema":{"type":"string"}},{"name":"internshipLevels","in":"query","description":"See `/api/v1/jobs`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of companies to return. Capped at 500 server-side. When omitted, returns all companies (response can exceed 1 MB — pass `limit` unless you specifically need the full list).","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"offset","in":"query","description":"Offset for pagination. Default 0.","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"List of companies.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CompanyList"},{"$ref":"#/components/schemas/CompanyListCountsUnavailable"}]},"examples":{"list":{"summary":"First company (alphabetical)","value":{"success":true,"companies":[{"id":658,"name":"100ms","domain":"100ms.live","logoUrl":"https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fwww.100ms.live&size=128","atsType":"lever","industry":"devtools","isFavorite":false,"pmJobCount":0,"totalJobCount":0,"mbaJobCount":0,"functionCounts":{},"companyStage":null,"fundingStage":null,"fundingSeries":null,"valuationMillions":null,"lastFinancingDate":null,"description":null,"ycBatch":null}],"count":1965,"servedFromCache":false,"dataFreshnessMs":0}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/companies/search":{"get":{"tags":["Companies"],"summary":"Search companies","description":"Deterministic SQL company resolution. Exact name, domain, and approved-alias\nmatches are terminal. A high-confidence correction may resolve one company;\notherwise the response is explicitly missing and may include optional similar\ncompanies plus a prefilled request action. Azure semantic search is not used.\n","operationId":"searchCompanies","parameters":[{"name":"q","in":"query","required":true,"description":"Search query (2 to 160 characters after Unicode NFKC normalization).","schema":{"type":"string","minLength":2,"maxLength":160}},{"name":"locationFilter","in":"query","description":"Parent-region filter. Same semantics as `/api/v1/jobs`.","required":false,"schema":{"type":"string"}},{"name":"region","in":"query","description":"Comma-separated parent regions; overrides `locationFilter`.","required":false,"schema":{"type":"string"}},{"name":"usStates","in":"query","description":"Comma-separated US state codes. Invalid non-empty codes return HTTP 400.","required":false,"schema":{"type":"string"}},{"name":"caProvinces","in":"query","description":"Comma-separated Canadian province codes. Invalid non-empty codes return HTTP 400.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum results, 1 through 200. Default 80.","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":80}},{"name":"offset","in":"query","description":"Result offset. Default 0.","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Matching companies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearch"},"examples":{"stripe":{"summary":"Search for stripe","value":{"success":true,"companies":[{"id":1,"name":"Stripe","domain":"stripe.com","logoUrl":"https://t1.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=http%3A%2F%2Fwww.stripe.com&size=128","atsType":"greenhouse","industry":"fintech","isFavorite":false,"pmJobCount":13,"totalJobCount":227,"mbaJobCount":4,"functionCounts":{"data":7,"legal":3,"other":26,"sales":32,"design":7,"people":9,"finance":11,"product":13,"support":3,"strategy":10,"marketing":16,"operations":22,"engineering":64,"partnerships":4},"companyStage":"enterprise","fundingStage":null,"fundingSeries":null,"valuationMillions":null,"lastFinancingDate":null,"description":null,"ycBatch":"S09"}],"count":1,"total":1,"similarTotal":0,"similarCompanies":[],"searchSource":"sql_fallback","resolution":{"kind":"exact","engine":"deterministic_sql","strategy":"name","confidence":1},"servedFromCache":false,"dataFreshnessMs":0}}}}}},"400":{"description":"Missing or too-short query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Search query must be at least 2 characters"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/me":{"get":{"tags":["User"],"summary":"Get authenticated user profile","description":"Returns the authenticated user's profile and preferences. This is **not** aggregate tracker metrics — it is per-user data (email, name, saved preferences, subscription state, feature flags).\n\nUse this endpoint to inspect which defaults the API applies to omitted query params on `/jobs` and `/companies`.\n","operationId":"getMe","responses":{"200":{"description":"Authenticated user profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"},"example":{"success":true,"user":{"id":1,"email":"user@example.com","name":"Example User","picture":"https://example.com/avatar.png","autoApplyDevEnabled":false,"candidateExperienceFilterAvailable":false,"experienceFilterV2Available":false,"preferences":{"wantsPM":true,"wantsStrategyOps":false,"wantsPartnerships":false,"wantedJobFunctions":["product"],"locationFilter":"us","needsSponsorship":false,"jobModality":"full_time","experienceRange":null,"experienceRanges":null,"candidateExperienceYears":null,"experienceLimitsByJobFunction":{"product":2,"strategy":5},"experienceFilterVersion":2,"experienceFilterActive":false,"experienceFilterV2Active":true,"internshipLevels":null,"favoritesDailyDigest":true,"notificationsFavoritesOnly":false,"notificationFrequency":"realtime","discoveryPreferenceRevision":0},"subscription":{"status":"none","expiresAt":null},"onboardingCompleted":true,"featureFlags":{"networkingV1":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/v1/stats":{"get":{"tags":["User"],"summary":"Get authenticated user profile (legacy alias)","description":"Legacy alias — prefer `GET /api/v1/me`. Returns the same response shape. The name `/stats` is historical and misleading: this endpoint returns the authenticated user's profile and preferences, not aggregate tracker metrics.\n","operationId":"getStats","deprecated":false,"responses":{"200":{"description":"Authenticated user profile (same as `/api/v1/me`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"TracklyAPIKey":{"type":"http","scheme":"bearer","bearerFormat":"trk_","description":"Trackly API key, issued at [usetrackly.app/developers](https://usetrackly.app/developers). Keys start with the `trk_` prefix. Pass as `Authorization: Bearer trk_...`.\n"}},"responses":{"BadRequest":{"description":"Invalid request (bad parameter value).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Invalid status filter."}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"value":{"error":"API key required. Use Authorization: Bearer trk_..."}},"invalid":{"value":{"error":"Invalid or revoked API key"}}}}}},"RateLimited":{"description":"Too many requests — limit is 10,000/hour per user across all public endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Rate limit exceeded (10,000 requests/hour)"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":"Failed to fetch jobs"}}}}},"schemas":{"JobFunction":{"type":"string","description":"Canonical job function. Matches the `job_function` column in the database.","enum":["product","engineering","design","data","marketing","sales","partnerships","finance","strategy","operations","people","legal","support","other"]},"JobModality":{"type":"string","description":"Employment type — full-time, internship, or both. Not remote/hybrid/onsite.","enum":["full_time","internship","all"]},"JobStatus":{"type":"string","description":"The authenticated user's application-pipeline state for a job.","enum":["new","applied_confirmed","check_later","not_interested","all"]},"SortOrder":{"type":"string","description":"Sort order for job lists.\n- `newest` — most recently posted first (default).\n- `match` — highest match score first (requires resume on file).\n\nThe deprecated values `oldest` and `company` are rejected with HTTP 400.\n","enum":["newest","match"]},"RegionTag":{"type":"string","description":"Region tag used for location filtering.","enum":["us","europe","latam","middle_east","asia","africa","canada","oceania","remote","unknown"]},"MatchConfidence":{"type":"string","description":"Confidence level for a per-user match score.","enum":["high","medium","low"]},"Company":{"type":"object","description":"Nested company object embedded in job responses.","required":["id","name","domain"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":"string"},"logoUrl":{"type":["string","null"],"format":"uri"},"logoUrls":{"type":"array","items":{"type":"string","format":"uri"}},"companyStage":{"type":["string","null"],"description":"e.g. seed, enterprise, decacorn"},"fundingStage":{"type":["string","null"]},"fundingSeries":{"type":["string","null"]},"valuationMillions":{"type":["number","null"]},"lastFinancingDate":{"type":["string","null"],"format":"date-time"},"description":{"type":["string","null"]},"ycBatch":{"type":["string","null"],"description":"Y Combinator batch (e.g. S09, W21) if applicable."},"sponsorshipHistory":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RoleSponsorshipHistory"}],"description":"US-only company sponsorship history for this job's function plus a cross-function counter-signal. null for non-US roles or companies that have never explicitly stated a policy. Clients render `signal` directly."}}},"SponsorshipExample":{"type":"object","description":"A past posting that explicitly stated a visa-sponsorship policy.","required":["jobId","jobFunction"],"properties":{"jobId":{"type":"integer","description":"Trackly job id — deep-link via /jobs/{jobId} (resolves even if the posting was later removed)."},"anchorAt":{"type":["string","null"],"format":"date-time","description":"Visible recency timestamp — valid vendor posted_at, otherwise Trackly first_seen_at."},"postedAt":{"type":["string","null"],"format":"date-time"},"evidence":{"type":["string","null"],"description":"Exact quote from the posting."},"jobFunction":{"type":"string"}}},"SponsorshipFacet":{"type":"object","description":"One side of the sponsorship signal (the primary stance or its counter).","required":["polarity","scope","jobFunction","example","message"],"properties":{"polarity":{"type":"string","enum":["no","yes"]},"scope":{"type":"string","enum":["same_function","other_function"]},"jobFunction":{"type":"string"},"example":{"$ref":"#/components/schemas/SponsorshipExample"},"message":{"type":"string","description":"Backend-rendered copy — clients display directly."}}},"RoleSponsorshipHistory":{"type":"object","description":"Company sponsorship history for a single US job (see Company.sponsorshipHistory).","properties":{"function":{"oneOf":[{"type":"null"},{"type":"object","description":"Counts + latest-of-each for the viewed job's own function.","required":["jobFunction","noCount","yesCount"],"properties":{"jobFunction":{"type":"string"},"noCount":{"type":"integer"},"yesCount":{"type":"integer"},"latestNo":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SponsorshipExample"}]},"latestYes":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SponsorshipExample"}]}}}]},"signal":{"oneOf":[{"type":"null"},{"type":"object","required":["primary","counter","tone","applicableRegion"],"properties":{"primary":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SponsorshipFacet"}]},"counter":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SponsorshipFacet"}]},"tone":{"type":"string","enum":["caution","positive","mixed"]},"applicableRegion":{"type":"string","enum":["us"]}}}]}}},"CompanyDetailed":{"type":"object","description":"Full company record returned by `/api/v1/companies` and `/api/v1/companies/search`.","required":["id","name","domain","isFavorite","pmJobCount","totalJobCount","mbaJobCount","functionCounts"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":"string"},"logoUrl":{"type":["string","null"],"format":"uri"},"atsType":{"type":["string","null"],"description":"ATS vendor slug (e.g. greenhouse, lever, ashby, eightfold)."},"industry":{"type":["string","null"]},"isFavorite":{"type":"boolean"},"pmJobCount":{"type":"integer","description":"Number of PM-classified roles currently active at this company."},"totalJobCount":{"type":"integer","description":"Total active roles at this company (post-filter)."},"mbaJobCount":{"type":"integer","description":"Active MBA-level roles at this company."},"functionCounts":{"type":"object","description":"Map of `JobFunction` value to active role count at this company.","additionalProperties":{"type":"integer"}},"companyStage":{"type":["string","null"]},"fundingStage":{"type":["string","null"]},"fundingSeries":{"type":["string","null"]},"valuationMillions":{"type":["number","null"]},"lastFinancingDate":{"type":["string","null"],"format":"date-time"},"description":{"type":["string","null"]},"ycBatch":{"type":["string","null"]}}},"CompanyCountsUnavailable":{"type":"object","description":"Opt-in Companies list record when live counts are unavailable. All count fields are null; metadata and per-user favorites retain their normal meaning.","required":["id","name","domain","isFavorite","pmJobCount","totalJobCount","mbaJobCount","functionCounts"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":["string","null"]},"logoUrl":{"type":["string","null"],"format":"uri"},"atsType":{"type":["string","null"],"description":"ATS vendor slug (e.g. greenhouse, lever, ashby, eightfold)."},"industry":{"type":["string","null"]},"isFavorite":{"type":"boolean"},"pmJobCount":{"type":"null"},"totalJobCount":{"type":"null"},"mbaJobCount":{"type":"null"},"functionCounts":{"type":"null"},"companyStage":{"type":["string","null"]},"fundingStage":{"type":["string","null"]},"fundingSeries":{"type":["string","null"]},"valuationMillions":{"type":["number","null"]},"lastFinancingDate":{"type":["string","null"],"format":"date-time"},"description":{"type":["string","null"]},"ycBatch":{"type":["string","null"]}}},"DimensionScore":{"type":"object","description":"Per-dimension contribution to the overall match score.","properties":{"dimension":{"type":"string"},"score":{"type":"number"},"weight":{"type":"number"}}},"DimensionRecommendation":{"type":"object","description":"Evidence-safe guidance for improving one match-score dimension.","required":["dimension","score","status","headline","actions","effort"],"properties":{"dimension":{"type":"string"},"score":{"type":"number"},"status":{"type":"string","enum":["strong","good","needs_work","weak"]},"headline":{"type":"string"},"actions":{"type":"array","items":{"type":"string"}},"effort":{"type":"string","enum":["easy","medium","hard"]}}},"JobSourceDateMeta":{"type":"object","additionalProperties":false,"properties":{"precision":{"type":"string","enum":["timestamp","day","unknown"]},"timezone":{"type":["string","null"]},"calendarDay":{"type":["string","null"],"format":"date"}}},"JobSourceReference":{"type":"object","additionalProperties":false,"required":["label","value","disambiguatesTitle"],"properties":{"label":{"type":"string","const":"Req"},"value":{"type":"string"},"disambiguatesTitle":{"type":"boolean"}}},"JobSourceDateBundle":{"type":"object","additionalProperties":false,"properties":{"original":{"oneOf":[{"$ref":"#/components/schemas/JobSourceDateMeta"},{"type":"null"}]},"repost":{"oneOf":[{"$ref":"#/components/schemas/JobSourceDateMeta"},{"type":"null"}]}}},"Job":{"type":"object","description":"Job posting as returned in list responses.","required":["id","externalId","title","companyName","companyId","companyDomain","jobUrl","jobFunction","firstSeenAt"],"properties":{"id":{"type":"integer"},"externalId":{"type":"string","description":"ID assigned by the source ATS."},"title":{"type":"string"},"companyName":{"type":"string"},"companyId":{"type":"integer"},"companyDomain":{"type":"string"},"companyLogoUrl":{"type":["string","null"],"format":"uri"},"companyLogoUrls":{"type":"array","items":{"type":"string","format":"uri"}},"location":{"type":["string","null"]},"jobUrl":{"type":"string","format":"uri"},"atsSource":{"type":["string","null"],"description":"ATS vendor slug (e.g. greenhouse, lever, ashby)."},"autoApplySupported":{"type":"boolean","const":false,"description":"Retired compatibility field. Full auto-apply is not supported; use Assisted Apply."},"isPM":{"type":"boolean"},"isStrategyOps":{"type":"boolean"},"isPartnership":{"type":"boolean"},"jobFunction":{"$ref":"#/components/schemas/JobFunction"},"postedAt":{"type":["string","null"],"format":"date-time"},"firstSeenAt":{"type":"string","format":"date-time"},"originalPostedAt":{"type":["string","null"],"format":"date-time","description":"Verified original source posting time. Omitted when provenance is unavailable so live payloads stay unchanged."},"repostedAt":{"type":["string","null"],"format":"date-time","description":"Latest verified source repost time. Never copied into postedAt."},"displayDate":{"type":["string","null"],"format":"date-time","description":"Verified original posted date when available, otherwise the trustworthy legacy posted date, then firstSeenAt. Repost evidence is timeline-only in repostedAt."},"displayDateKind":{"type":"string","enum":["posted","reposted","found"]},"sourceDateObservedAt":{"type":["string","null"],"format":"date-time"},"sourceDateMeta":{"$ref":"#/components/schemas/JobSourceDateBundle"},"sourceReference":{"oneOf":[{"$ref":"#/components/schemas/JobSourceReference"},{"type":"null"}]},"isNew":{"type":"boolean"},"isActive":{"type":"boolean"},"sponsorshipStatus":{"type":["string","null"],"description":"yes, no, or unknown."},"sponsorshipEvidence":{"type":["string","null"]},"sponsorshipClassifier":{"type":["string","null"],"description":"Which classifier produced the sponsorship tag (regex, llm, reused)."},"region":{"oneOf":[{"$ref":"#/components/schemas/RegionTag"},{"type":"null"}]},"seniorityLevel":{"type":["string","null"],"description":"e.g. junior, mid, senior, staff, director."},"salaryMin":{"type":["number","null"]},"salaryMax":{"type":["number","null"]},"salaryCurrency":{"type":["string","null"]},"salaryPeriod":{"type":["string","null"],"description":"e.g. annual, hourly, monthly."},"salaryRange":{"oneOf":[{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":["string","null"]}}},{"type":"null"}]},"salaryText":{"type":"string"},"compensation":{"type":"string"},"compensationText":{"type":"string"},"visaSponsorship":{"type":["string","null"]},"userStatus":{"oneOf":[{"$ref":"#/components/schemas/JobStatus"},{"type":"null"}]},"applyStartedAt":{"type":["string","null"],"format":"date-time"},"appliedConfirmedAt":{"type":["string","null"],"format":"date-time"},"statusUpdatedAt":{"type":["string","null"],"format":"date-time"},"timeToApplyMinutes":{"type":["number","null"]},"matchScore":{"type":["number","null"],"description":"Personalized match score 0 to 100 on the display scale named by scoreModel. Ranking uses the underlying stored score, so the display scale never reorders jobs; matchLabel is derived from this displayed number with the same 75/55/40/25 cut-offs clients color it with. Null when resume not uploaded or not yet scored."},"matchScoreStatus":{"type":"string","enum":["scored","not_scored"],"description":"Scored means a saved real score exists; not_scored means no score is available now."},"matchScoreReason":{"type":["string","null"],"enum":["not_scored",null],"description":"Not_scored accompanies an absent score; null accompanies a saved score."},"scoreModel":{"type":["string","null"],"description":"Display model that produced matchScore (scoring_model_2026_09_22 for the display curve, raw when the curve is switched off). Null when matchScore is null."},"matchReasons":{"type":"array","items":{"type":"string"}},"matchLabel":{"type":["string","null"]},"matchConfidence":{"oneOf":[{"$ref":"#/components/schemas/MatchConfidence"},{"type":"null"}]},"matchConfidenceReasons":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"missingSkills":{"type":"array","items":{"type":"string"}},"dimensionScores":{"type":"array","items":{"$ref":"#/components/schemas/DimensionScore"}},"matchExplanation":{"type":["string","null"]},"company":{"$ref":"#/components/schemas/Company"}}},"JobDetail":{"type":"object","description":"Full job detail. Extends `Job` with description, recommendations, structured-JD fields (when the `structured_jd` column is populated), and the user's match diagnostics. The structured-JD fields (`seniorityLevel`, `salaryMin`, etc.) are **flat siblings** of `title` and `description` — there is no `structuredJd` parent object.\n","required":["id","externalId","title","jobUrl","jobFunction"],"properties":{"id":{"type":"integer"},"externalId":{"type":"string"},"title":{"type":"string"},"location":{"type":["string","null"]},"jobUrl":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"descriptionHtml":{"type":["string","null"]},"isPM":{"type":"boolean"},"isStrategyOps":{"type":"boolean"},"isPartnership":{"type":"boolean"},"jobFunction":{"$ref":"#/components/schemas/JobFunction"},"postedAt":{"type":["string","null"],"format":"date-time"},"firstSeenAt":{"type":"string","format":"date-time"},"originalPostedAt":{"type":["string","null"],"format":"date-time","description":"Verified original source posting time. Omitted when provenance is unavailable so live payloads stay unchanged."},"repostedAt":{"type":["string","null"],"format":"date-time","description":"Latest verified source repost time. Never copied into postedAt."},"displayDate":{"type":["string","null"],"format":"date-time","description":"Verified original posted date when available, otherwise the trustworthy legacy posted date, then firstSeenAt. Repost evidence is timeline-only in repostedAt."},"displayDateKind":{"type":"string","enum":["posted","reposted","found"]},"sourceDateObservedAt":{"type":["string","null"],"format":"date-time"},"sourceDateMeta":{"$ref":"#/components/schemas/JobSourceDateBundle"},"sourceReference":{"oneOf":[{"$ref":"#/components/schemas/JobSourceReference"},{"type":"null"}]},"minutesAgo":{"type":"number"},"sponsorshipStatus":{"type":["string","null"]},"sponsorshipEvidence":{"type":["string","null"]},"sponsorshipClassifier":{"type":["string","null"]},"region":{"oneOf":[{"$ref":"#/components/schemas/RegionTag"},{"type":"null"}]},"userStatus":{"oneOf":[{"$ref":"#/components/schemas/JobStatus"},{"type":"null"}]},"applyStartedAt":{"type":["string","null"],"format":"date-time"},"appliedConfirmedAt":{"type":["string","null"],"format":"date-time"},"statusUpdatedAt":{"type":["string","null"],"format":"date-time"},"timeToApplyMinutes":{"type":["number","null"]},"matchScore":{"type":["number","null"],"description":"Personalized match score 0 to 100 on the display scale named by scoreModel. Ranking uses the underlying stored score, so the display scale never reorders jobs. Null when resume not uploaded or not yet scored."},"matchScoreStatus":{"type":"string","enum":["scored","not_scored"],"description":"Scored means a saved real score exists; not_scored means no score is available now."},"matchScoreReason":{"type":["string","null"],"enum":["not_scored",null],"description":"Not_scored accompanies an absent score; null accompanies a saved score."},"scoreModel":{"type":["string","null"],"description":"Display model that produced matchScore (scoring_model_2026_09_22 for the display curve, raw when the curve is switched off). Null when matchScore is null."},"matchReasons":{"type":"array","items":{"type":"string"}},"matchLabel":{"type":["string","null"]},"matchConfidence":{"oneOf":[{"$ref":"#/components/schemas/MatchConfidence"},{"type":"null"}]},"matchConfidenceReasons":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"dimensionScores":{"type":"array","items":{"$ref":"#/components/schemas/DimensionScore"}},"missingSkills":{"type":"array","items":{"type":"string"}},"matchExplanation":{"type":["string","null"]},"recommendations":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/DimensionRecommendation"}},{"type":"null"}]},"quickWins":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"candidateFit":{"oneOf":[{"type":"object"},{"type":"null"}]},"skillsOverlap":{"oneOf":[{"type":"object"},{"type":"null"}]},"seniorityLevel":{"type":["string","null"],"description":"Optional — present when `structured_jd` column is populated."},"salaryMin":{"type":["number","null"]},"salaryMax":{"type":["number","null"]},"salaryCurrency":{"type":["string","null"]},"salaryPeriod":{"type":["string","null"],"description":"e.g. annual, hourly, monthly."},"salaryRange":{"oneOf":[{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":["string","null"]}}},{"type":"null"}]},"salaryTiers":{"description":"Education-specific hourly pay read from the job description when no stored salary exists (e.g. \"$25/hour for undergrad; $40/hour for graduate\"). When present, salaryMin/salaryMax/salaryRange are null because no single amount applies to every applicant; salaryText holds the tier summary. Null when the posting has no education tiers.","oneOf":[{"type":"array","items":{"type":"object","required":["educationLevel","label","min","max","currency","period"],"properties":{"educationLevel":{"type":"string","enum":["undergraduate","graduate","masters","mba","phd"]},"label":{"type":"string","description":"The education word as the posting wrote it."},"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"},"period":{"type":"string","enum":["hourly"]}}}},{"type":"null"}]},"salaryText":{"type":"string"},"compensation":{"type":"string"},"compensationText":{"type":"string"},"structuredSkills":{"type":"array","items":{"type":"string"},"description":"Required skills extracted from the JD."},"structuredPreferredSkills":{"type":"array","items":{"type":"string"}},"structuredBenefits":{"type":"array","items":{"type":"string"}},"structuredTools":{"type":"array","items":{"type":"string"}},"structuredSponsorshipInfo":{"type":["string","null"]},"company":{"$ref":"#/components/schemas/Company"}}},"Pagination":{"type":"object","required":["total","limit","offset","hasMore"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}}},"JobList":{"type":"object","description":"Response envelope for `/api/v1/jobs`.","required":["success","jobs","total","hasMore","pagination"],"properties":{"success":{"type":"boolean","const":true},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"total":{"type":"integer"},"hasMore":{"type":"boolean"},"autoApplyDevEnabled":{"type":"boolean","const":false,"description":"Retired compatibility field that is always false."},"servedFromCache":{"type":"boolean"},"dataFreshnessMs":{"type":"integer","description":"Age of the served payload in milliseconds. 0 when freshly computed."},"postedRecencyMode":{"type":"string","enum":["legacy_discovery","unified_posted","display_date"],"description":"Active feed-ordering contract; display_date orders by the verified original posted date, then the truthful legacy posted date, then firstSeenAt. Repost evidence remains timeline-only."},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"JobDetailResponse":{"type":"object","required":["success","job"],"properties":{"success":{"type":"boolean","const":true},"job":{"$ref":"#/components/schemas/JobDetail"}}},"CompanyList":{"type":"object","description":"Response envelope for `/api/v1/companies`.","not":{"required":["countsState"]},"required":["success","companies","count"],"properties":{"success":{"type":"boolean","const":true},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyDetailed"}},"count":{"type":"integer","description":"Number of companies returned in this page (respects `limit`/`offset`)."},"total":{"type":"integer","description":"Total number of companies matching the filter across all pages."},"servedFromCache":{"type":"boolean"},"dataFreshnessMs":{"type":"integer"}}},"CompanyListCountsUnavailable":{"type":"object","description":"Available only with `allowUnavailableCounts=1` after a live aggregation deadline. List count and total remain company counts, not job counts.","required":["success","companies","count","countsState","retryAfterSeconds"],"properties":{"countsState":{"type":"string","const":"unavailable"},"retryAfterSeconds":{"type":"integer","const":60},"success":{"type":"boolean","const":true},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyCountsUnavailable"}},"count":{"type":"integer","description":"Number of companies returned in this page (respects `limit`/`offset`)."},"total":{"type":"integer","description":"Total number of companies matching the filter across all pages."},"servedFromCache":{"type":"boolean"},"dataFreshnessMs":{"type":"integer"}}},"CompanySearch":{"type":"object","description":"Response envelope for `/api/v1/companies/search`.","required":["success","companies","similarCompanies","count","total","searchSource","resolution","servedFromCache","dataFreshnessMs"],"properties":{"success":{"type":"boolean","const":true},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyDetailed"}},"similarCompanies":{"type":"array","description":"Optional partial-name candidates, kept separate from resolved matches.","items":{"$ref":"#/components/schemas/CompanyDetailed"}},"count":{"type":"integer"},"total":{"type":"integer"},"similarTotal":{"type":"integer","description":"Total optional similar companies before pagination."},"searchSource":{"type":"string","enum":["sql_fallback","azure_semantic"],"description":"Backward-compatible retrieval label. Use resolution.engine for deterministic search metadata."},"resolution":{"type":"object","required":["kind","engine","strategy","confidence"],"properties":{"kind":{"type":"string","enum":["exact","corrected","missing"]},"engine":{"type":"string","enum":["deterministic_sql"]},"strategy":{"type":"string","enum":["name","domain","alias","correction","none"]},"confidence":{"type":["number","null"],"minimum":0,"maximum":1}}},"request":{"type":"object","description":"Present only when `resolution.kind` is `missing`.","required":["available","companyName","endpoint"],"properties":{"available":{"type":"boolean","const":true},"companyName":{"type":"string","maxLength":160},"endpoint":{"type":"string","const":"/api/jobscout/companies/request"}}},"servedFromCache":{"type":"boolean"},"dataFreshnessMs":{"type":"integer"}}},"UserPreferences":{"type":"object","required":["wantsPM","wantsStrategyOps","wantsPartnerships","wantedJobFunctions","locationFilter","discoveryPreferenceRevision","needsSponsorship","jobModality"],"properties":{"wantsPM":{"type":"boolean"},"wantsStrategyOps":{"type":"boolean"},"wantsPartnerships":{"type":"boolean"},"wantedJobFunctions":{"type":"array","items":{"$ref":"#/components/schemas/JobFunction"}},"locationFilter":{"type":"string","description":"Comma-separated parent regions. Multiple parents are OR branches."},"usStates":{"type":"array","items":{"type":"string","pattern":"^(?:[A-Z]{2}|REMOTE)$"},"description":"Saved US state children. An empty array means the whole selected US parent. `REMOTE` is a saved Remote selection, not a state."},"caProvinces":{"type":"array","items":{"type":"string","pattern":"^(?:[A-Z]{2}|REMOTE)$"},"description":"Saved Canadian province children. An empty array means the whole selected Canada parent. `REMOTE` is a saved Remote selection, not a province."},"discoveryPreferenceRevision":{"type":"integer","format":"int64","minimum":0,"readOnly":true,"description":"Monotonic account-level discovery-preference revision. First-party editors send this value as expectedPreferenceRevision when saving; stale saves receive HTTP 409 plus the complete authoritative snapshot."},"needsSponsorship":{"type":"boolean","description":"Disclosure and voice-personalization context only. This preference never removes jobs from feeds, counts, saved searches, or alerts; clients should show the job's sponsorship status when available."},"jobModality":{"$ref":"#/components/schemas/JobModality"},"experienceRange":{"type":["string","null"],"deprecated":true,"description":"Legacy ambiguous bucket retained for old clients; never enforced."},"experienceRanges":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"deprecated":true,"description":"Legacy ambiguous buckets retained for old clients; never enforced."},"candidateExperienceYears":{"type":["integer","null"],"minimum":0,"maximum":60,"deprecated":true,"description":"Legacy version-1 total-tenure value retained for old clients; never enforced by the version-2 matcher."},"experienceLimitsByJobFunction":{"type":["object","null"],"additionalProperties":{"type":"integer","minimum":0,"maximum":60},"description":"Sparse version-2 map from canonical job-function slug to the maximum stated minimum years the user accepts. For example, product: 2 keeps jobs requiring 2 years or less; jobs with no stated minimum remain visible. Missing keys do not filter that role. An explicit null or empty object clears all role limits."},"experienceFilterVersion":{"type":"integer","minimum":0,"description":"Version 2 activates the per-job-function contract. Versions 0 and 1 remain readable but are not enforced."},"experienceFilterActive":{"type":"boolean","readOnly":true,"deprecated":true,"description":"Legacy version-1 active state retained unchanged for installed clients."},"experienceFilterV2Active":{"type":"boolean","readOnly":true,"description":"True only when version 2 has at least one saved per-job-function limit."},"internshipLevels":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"favoritesDailyDigest":{"type":"boolean"},"notificationsFavoritesOnly":{"type":"boolean"},"notificationFrequency":{"type":"string","description":"e.g. realtime, daily, weekly."}}},"Subscription":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"none, active, expired."},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"FeatureFlags":{"type":"object","properties":{"networkingV1":{"type":"boolean"}}},"User":{"type":"object","required":["id","email","preferences","subscription","featureFlags"],"properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"name":{"type":["string","null"]},"picture":{"type":["string","null"],"format":"uri"},"autoApplyDevEnabled":{"type":"boolean","const":false,"description":"Retired compatibility field that is always false."},"candidateExperienceFilterAvailable":{"type":"boolean","deprecated":true,"description":"Legacy version-1 total-tenure prompt capability retained unchanged for installed clients."},"experienceFilterV2Available":{"type":"boolean","description":"True when V2-capable clients may show role-specific maximum-required- experience controls. This prompt gate does not imply feed or alert enforcement is active."},"preferences":{"$ref":"#/components/schemas/UserPreferences"},"subscription":{"$ref":"#/components/schemas/Subscription"},"onboardingCompleted":{"type":"boolean"},"featureFlags":{"$ref":"#/components/schemas/FeatureFlags"}}},"Me":{"type":"object","description":"Response envelope for `/api/v1/me` and `/api/v1/stats`.","required":["success","user"],"properties":{"success":{"type":"boolean","const":true},"user":{"$ref":"#/components/schemas/User"}}},"ErrorResponse":{"type":"object","description":"Standard error envelope.","properties":{"success":{"type":"boolean","const":false},"error":{"type":"string"}},"required":["error"]}}}}