YubHub API

openapi: 3.1.0
info:
  title: YubHub API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 57 operation(s) read from 4 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; YubHub has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 56
    pages-with-code: 2
    pages-read: 4
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://yubhub.co/api
  - https://yubhub.co/developers/api-reference
  - https://yubhub.co/developers
  - https://yubhub.co/.well-known/openapi.yaml
servers:
- url: https://api.yubhub.co
paths:
  /api/account:
    delete:
      operationId: delete_api_account
      tags:
      - Api
      summary: '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'
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_api_account
      tags:
      - Api
      summary: Account profile + usage
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/account/api-key:
    delete:
      operationId: delete_api_account_api_key
      tags:
      - Api
      summary: Revoke current API key
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_account_api_key
      tags:
      - Api
      summary: Generate a new yh_ API key
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/account/checkout:
    post:
      operationId: post_api_account_checkout
      tags:
      - Api
      summary: Create a Stripe Checkout session to subscribe or upgrade (an existing subscriber gets a Billing Portal session instead)
      description: Creates a Stripe Checkout session for subscription or upgrade.
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/account/portal:
    post:
      operationId: post_api_account_portal
      tags:
      - Api
      summary: Create a Stripe Billing Portal session (manage or cancel a subscription)
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/account/usage:
    get:
      operationId: get_api_account_usage
      tags:
      - Api
      summary: Current plan usage and monthly quota
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds:
    get:
      operationId: get_api_feeds
      tags:
      - Api
      summary: List your feeds
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_feeds
      tags:
      - Api
      summary: Create a feed
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds/{id}:
    delete:
      operationId: delete_api_feeds_id
      tags:
      - Api
      summary: Delete feed (its enriched jobs are soft‑expired; unenriched jobs are deleted)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_api_feeds_id
      tags:
      - Api
      summary: Feed detail
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_api_feeds_id
      tags:
      - Api
      summary: Update feed
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds/{id}/jobs:
    delete:
      operationId: delete_api_feeds_id_jobs
      tags:
      - Api
      summary: Delete all jobs for a feed
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds/{id}/jobs/reset-enrichment:
    post:
      operationId: post_api_feeds_id_jobs_reset_enrichment
      tags:
      - Api
      summary: Reset this feed's jobs to re-run enrichment
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds/{id}/jobs/retry-failed:
    post:
      operationId: post_api_feeds_id_jobs_retry_failed
      tags:
      - Api
      summary: Re-queue this feed's stuck jobs (failed / quota_blocked / scraped; re-enrich when content survives)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds/{id}/schedule:
    patch:
      operationId: patch_api_feeds_id_schedule
      tags:
      - Api
      summary: Update the feed auto‑refresh schedule
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/feeds/{id}/xml:
    get:
      operationId: get_api_feeds_id_xml
      tags:
      - Api
      summary: The public XML feed URL for this feed
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/jobs/{jobid}:
    get:
      operationId: get_api_jobs_jobid
      tags:
      - Api
      summary: Authenticated full-data job fetch
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/jobs/{jobid}/reset-enrichment:
    post:
      operationId: post_api_jobs_jobid_reset_enrichment
      tags:
      - Api
      summary: Reset one of your jobs and re-run enrichment (re-scrape if its raw content was cleared)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /feed/{feedid}:
    get:
      operationId: get_feed_feedid
      tags:
      - Feed
      summary: XML feed for one employer feed (the URL shown in the dashboard)
      description: Provides the XML feed for a specific employer feed.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: feedid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /health:
    get:
      operationId: get_health
      tags:
      - Health
      summary: Service health
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /search:
    get:
      operationId: get_search
      tags:
      - Search
      summary: GET /search
      x-source: https://yubhub.co/api
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: q
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl. No key needed. requests # Full-text search for engineering jobs in the UK https://api.yubhub.co/search?q=engineer&country=GB
          # First page of live jobs that ask for Python https://api.yubhub.co/stats/by-facet/skill/python?page=1 # Engineering jobs as jobs.json,
          each a schema.org JobPosting https://feeds.yubhub.co/facet/category/engineering.json # London jobs as XML, ready for job board softwa'
  /stats/by-facet/{type}/{value}:
    get:
      operationId: get_stats_by_facet_type_value
      tags:
      - Stats
      summary: Detailed data for a single facet value (paginated job list + aggregations)
      description: Provides detailed data for a specific facet value.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: value
        in: path
        required: true
        schema:
          type: string
      - name: X-Accept-Stale
        in: header
        required: false
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: string
      - name: perPage
        in: query
        required: false
        schema:
          type: string
      - name: city
        in: query
        required: false
        schema:
          type: string
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: sort
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/by-title/{title}:
    get:
      operationId: get_stats_by_title_title
      tags:
      - Stats
      summary: Deep stats for a single title (companies, locations, work arrangement, experience level, salary)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: title
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/categories:
    get:
      operationId: get_stats_categories
      tags:
      - Stats
      summary: Jobs by category with experience-level breakdown
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/companies:
    get:
      operationId: get_stats_companies
      tags:
      - Stats
      summary: Company directory (list of companies with N+ live roles)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: min
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/companies/leaderboard:
    get:
      operationId: get_stats_companies_leaderboard
      tags:
      - Stats
      summary: Cross-company rankings (accelerating, AI-exposed, hiring-velocity, exec-hires)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: metric
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: min_jobs
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/company/{slug}:
    get:
      operationId: get_stats_company_slug
      tags:
      - Stats
      summary: Full company intelligence profile + hiring aggregates + 11 benchmarking sections
      description: Returns comprehensive intelligence for a company.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/company/{slug}/peers:
    get:
      operationId: get_stats_company_slug_peers
      tags:
      - Stats
      summary: Same-industry peer ranking with momentum classification
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: n
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/company/{slug}/profile:
    get:
      operationId: get_stats_company_slug_profile
      tags:
      - Stats
      summary: Company profile only (the `data.company` block of /stats/company/{slug})
      description: Returns only the company profile block.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/company/{slug}/timeseries:
    get:
      operationId: get_stats_company_slug_timeseries
      tags:
      - Stats
      summary: Per-company time series (velocity / categories / titles / geo)
      description: Provides time‑series data for a company.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: metric
        in: query
        required: false
        schema:
          type: string
      - name: weeks
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/early-careers/{track}:
    get:
      operationId: get_stats_early_careers_track
      tags:
      - Stats
      summary: Live graduate / entry-level jobs or internships, with specialism and country breakdowns
      description: Provides early‑career job listings and breakdowns.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: track
        in: path
        required: true
        schema:
          type: string
      - name: category
        in: query
        required: false
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: string
      - name: perPage
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/employer-showcase:
    get:
      operationId: get_stats_employer_showcase
      tags:
      - Stats
      summary: Rotating employer showcase for the homepage
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/experience-levels:
    get:
      operationId: get_stats_experience_levels
      tags:
      - Stats
      summary: Entry/mid/senior/executive distribution
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/facets/{type}:
    get:
      operationId: get_stats_facets_type
      tags:
      - Stats
      summary: List facet values with counts (for directory index pages)
      description: Returns facet values and their counts.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: min
        in: query
        required: false
        schema:
          type: string
      - name: fields
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/hiring-intensity:
    get:
      operationId: get_stats_hiring_intensity
      tags:
      - Stats
      summary: Open-jobs-per-employee ratio for top employers
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/hiring-velocity:
    get:
      operationId: get_stats_hiring_velocity
      tags:
      - Stats
      summary: 30-day hiring trend timeseries
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/industry-momentum:
    get:
      operationId: get_stats_industry_momentum
      tags:
      - Stats
      summary: Industry hiring momentum with accelerating/stable/decelerating signal
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/job/{id}:
    get:
      operationId: get_stats_job_id
      tags:
      - Stats
      summary: Full data for a single job including linked-data (Wikidata sameAs)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: view
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/market-concentration:
    get:
      operationId: get_stats_market_concentration
      tags:
      - Stats
      summary: Top-company share of total jobs per category
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/market-pulse:
    get:
      operationId: get_stats_market_pulse
      tags:
      - Stats
      summary: Category growth
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/occupation-ai-exposure:
    get:
      operationId: get_stats_occupation_ai_exposure
      tags:
      - Stats
      summary: SOC occupation AI exposure scores (from Anthropic telemetry)
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/overview:
    get:
      operationId: get_stats_overview
      tags:
      - Stats
      summary: Site-wide totals
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/recent-jobs:
    get:
      operationId: get_stats_recent_jobs
      tags:
      - Stats
      summary: Recent enriched job IDs (for sitemap consumers)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: before
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/related/{type}/{value}:
    get:
      operationId: get_stats_related_type_value
      tags:
      - Stats
      summary: Related facets (cross-link suggestions for archive sidebars)
      description: Returns related facets for the given type and value.
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: value
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/salaries:
    get:
      operationId: get_stats_salaries
      tags:
      - Stats
      summary: Pay by job category for live US jobs (in USD) or UK jobs (in GBP)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: country
        in: query
        required: false
        schema:
          type: string
      - name: arrangement
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/salary-by-sector:
    get:
      operationId: get_stats_salary_by_sector
      tags:
      - Stats
      summary: Annual pay distribution by job category, in one currency
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: currency
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/salary-transparency:
    get:
      operationId: get_stats_salary_transparency
      tags:
      - Stats
      summary: Percentage of jobs disclosing salary per category
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/skill-ai-exposure:
    get:
      operationId: get_stats_skill_ai_exposure
      tags:
      - Stats
      summary: Skill-level AI exposure scores
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/skills-matrix:
    get:
      operationId: get_stats_skills_matrix
      tags:
      - Stats
      summary: Top skills with category split
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/skills-split:
    get:
      operationId: get_stats_skills_split
      tags:
      - Stats
      summary: Required vs preferred skill counts
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/title-salaries:
    get:
      operationId: get_stats_title_salaries
      tags:
      - Stats
      summary: Annual pay per job title (top titles by live jobs)
      x-source: https://yubhub.co/developers/api-reference
      parameters:
      - name: currency
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/title-trends:
    get:
      operationId: get_stats_title_trends
      tags:
      - Stats
      summary: Week-over-week title demand changes
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/titles-list:
    get:
      operationId: get_stats_titles_list
      tags:
      - Stats
      summary: All titles with ≥3 jobs (programmatic SEO feed)
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/top-companies:
    get:
      operationId: get_stats_top_companies
      tags:
      - Stats
      summary: Top companies by job count
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/top-titles:
    get:
      operationId: get_stats_top_titles
      tags:
      - Stats
      summary: Most common job titles (top 30)
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /stats/work-arrangements:
    get:
      operationId: get_stats_work_arrangements
      tags:
      - Stats
      summary: Remote/hybrid/on-site distribution
      x-source: https://yubhub.co/developers/api-reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Feed
- name: Health
- name: Search
- name: Stats