REST API reference
Read endpoints need no key and have open CORS, so you can call them from a browser or a server.
Feed and account endpoints need a yh_ key, which comes with the Pro Publisher plan.
The /search endpoint is limited to 30 requests a minute per IP.
Everything below is generated from the OpenAPI 2.12.0 spec.
Authentication
Data endpoints (Health, Search, Stats) are open — no key required. Feed & account endpoints (marked auth) need your key as a Bearer token:
Authorization: Bearer yh_your_api_key Health
1 endpoint/health Service health
Search
1 endpoint/search Full-text search across job titles and companies
q (query)*, page (query), perPage (query), country (query), city (query), arrangement (query), level (query), category (query), sort (query)
Stats
23 endpoints/stats/overview Site-wide totals
/stats/top-companies Top companies by job count
/stats/categories Jobs by category with experience-level breakdown
/stats/top-titles Most common job titles (top 30)
/stats/title-trends Week-over-week title demand changes
/stats/title-salaries Annual pay per job title (top titles by live jobs)
currency (query)
/stats/work-arrangements Remote/hybrid/on-site distribution
/stats/experience-levels Entry/mid/senior/executive distribution
/stats/salary-by-sector Annual pay distribution by job category, in one currency
currency (query)
/stats/salaries Pay by job category for live US jobs (in USD) or UK jobs (in GBP)
country (query), arrangement (query)
/stats/skills-matrix Top skills with category split
/stats/skills-split Required vs preferred skill counts
/stats/hiring-velocity 30-day hiring trend timeseries
/stats/hiring-intensity Open-jobs-per-employee ratio for top employers
/stats/salary-transparency Percentage of jobs disclosing salary per category
/stats/market-pulse Category growth
/stats/market-concentration Top-company share of total jobs per category
/stats/industry-momentum Industry hiring momentum with accelerating/stable/decelerating signal
/stats/titles-list All titles with ≥3 jobs (programmatic SEO feed)
/stats/by-title/{title} Deep stats for a single title (companies, locations, work arrangement, experience level, salary)
title (path)*
/stats/occupation-ai-exposure SOC occupation AI exposure scores (from Anthropic telemetry)
/stats/skill-ai-exposure Skill-level AI exposure scores
/stats/employer-showcase Rotating employer showcase for the homepage
Feeds (authenticated)
13 endpoints · Beareryh_ key /api/feeds List your feeds
include (query)
/api/feeds Create a feed
/api/feeds/{id} Feed detail
id (path)*
/api/feeds/{id} Update feed
id (path)*
/api/feeds/{id} Delete feed (its enriched jobs are soft-expired; unenriched jobs are deleted)
id (path)*
/api/feeds/{id}/run Trigger discovery+scrape+enrich
id (path)*
/api/feeds/{id}/jobs Paginated jobs for a feed
id (path)*, status (query), page (query), per_page (query)
/api/feeds/{id}/jobs Delete all jobs for a feed
id (path)*
/api/feeds/{id}/xml The public XML feed URL for this feed (JSON body
id (path)*
/api/feeds/{id}/schedule Get the feed auto-refresh schedule
id (path)*
/api/feeds/{id}/schedule Update the feed auto-refresh schedule
id (path)*
/api/feeds/{id}/jobs/retry-failed Re-queue this feed's stuck jobs (failed / quota_blocked / scraped; re-enrich when content survives
id (path)*
/api/feeds/{id}/jobs/reset-enrichment Reset this feed's jobs to re-run enrichment
id (path)*
Jobs
4 endpoints/stats/job/{id} Full data for a single job including linked-data (Wikidata sameAs)
id (path)*, view (query)
/stats/recent-jobs Recent enriched job IDs (for sitemap consumers)
limit (query), offset (query)
/api/jobs/{jobId} Authenticated full-data job fetch
jobId (path)*
/api/jobs/{jobId}/reset-enrichment Reset one of your jobs and re-run enrichment (re-scrape if its raw content was cleared)
jobId (path)*
Account (authenticated)
7 endpoints · Beareryh_ key /api/account Account profile + usage
/api/account Delete account permanently: cancels the Stripe subscription, deletes the Clerk user, soft-expires your jobs (rows are kept, never hard-deleted), then deletes your feeds, usage log and user row
/api/account/usage Current plan usage and monthly quota
/api/account/api-key Generate a new yh_ API key
/api/account/api-key Revoke current API key
/api/account/portal Create a Stripe Billing Portal session (manage or cancel a subscription)
/api/account/checkout Create a Stripe Checkout session to subscribe or upgrade (an existing subscriber gets a Billing Portal session instead)
Public feeds (feeds.yubhub.co)
4 endpoints/facet/{type}/{slug}.xml Free XML job feed for a facet (JBoard/SmartJobBoard-compatible) — on feeds.yubhub.co
type (path)*, slug (path)*
/facet/{type}/{slug}.json Free JSON job feed for a facet — on feeds.yubhub.co
type (path)*, slug (path)*
/facet/{type}/{slug}.rss Free RSS 2.0 job feed for a facet, for feed readers and email alerts, on feeds.yubhub.co
type (path)*, slug (path)*
/feed/{feedId} XML feed for one employer feed (the URL shown in the dashboard) — on feeds.yubhub.co
feedId (path)*
Facets
4 endpoints/stats/facets/{type} List facet values with counts (for directory index pages)
type (path)*, min (query), fields (query)
/stats/by-facet/{type}/{value} Detailed data for a single facet value (paginated job list + aggregations)
type (path)*, value (path)*, page (query), perPage (query), city (query), country (query), sort (query)
/stats/related/{type}/{value} Related facets (cross-link suggestions for archive sidebars)
type (path)*, value (path)*
/stats/early-careers/{track} Live graduate / entry-level jobs or internships, with specialism and country breakdowns
track (path)*, category (query), page (query), perPage (query)
Companies
6 endpoints/stats/company/{slug} Full company intelligence profile + hiring aggregates + 11 benchmarking sections
slug (path)*
/stats/company/{slug}/profile Company profile only (the `data.company` block of /stats/company/{slug})
slug (path)*
/stats/company/{slug}/timeseries Per-company time series (velocity / categories / titles / geo)
slug (path)*, metric (query), weeks (query)
/stats/company/{slug}/peers Same-industry peer ranking with momentum classification
slug (path)*, n (query)
/stats/companies/leaderboard Cross-company rankings (accelerating, AI-exposed, hiring-velocity, exec-hires)
metric (query), limit (query), min_jobs (query)
/stats/companies Company directory (list of companies with N+ live roles)
min (query)
* required parameter. Feed & account endpoints require a Pro Publisher plan.