Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

Hirebase exposes several endpoints that overlap in what they return — jobs, companies, search results — but they’re tuned for very different use cases. This guide walks through the most common things people build on top of Hirebase and which API to reach for.

​
Quick Decision Guide

Add job search to your app

Use POST /v2/jobs/search

Build your own product on Hirebase data

Use POST /v2/jobs/export — sync to your own database

Show 'similar jobs' under a listing

Use POST /v2/jobs/vsearch with search_type: "job"

Match jobs to a candidate's resume

Use POST /v2/resumes/embed → vsearch with search_type: "resume"

Build company profile pages

Use POST /v2/hirebase/companies/search + GET /v2/hirebase/companies/{slug}

Keep your local data fresh

Use GET /v2/jobs/expired-jobs on a schedule

​
1. Adding Job Search to an Existing App

Use: POST /v2/jobs/search This is the right starting point for most integrations: a job board, a careers page, a search bar in a community app, an internal tool — anywhere you want users to type a query and see a paginated list of matching jobs back. It’s the simplest endpoint to integrate, the response shape is predictable, and every job comes back with a unique job_slug and company_slug you can use to build clean URLs in your own app: 
yoursite.com/jobs/{company_slug}/{job_slug}
You don’t need to store anything on your side — Hirebase is the source of truth. Just call the search endpoint when the user submits a query, render the results, and link the slugs to a detail page that calls GET /v2/jobs/{job_id} for the full record.
Page 1 is free without an API key, so you can prototype the search box before you sign up. Paginating past page 1 requires a key.

​
When this stops being the right choice

The /jobs/search endpoint is paginated. As long as your users are searching — narrowing a filter, looking at the first few pages of relevant jobs — pagination is fine and you’ll never feel a slowdown. Where it breaks down is when you try to use the search endpoint to iterate over the entire dataset. Past roughly 200,000 results, deep pagination gets noticeably slow. If you find yourself writing a loop that keeps incrementing page to walk every job in the database, you’ve outgrown this endpoint — see the next section.

​
2. Building Your Own Product on Hirebase Data

Use: POST /v2/jobs/export If you’re building a real product on top of Hirebase data — your own search engine, an analytics dashboard, an ATS feature, an LLM agent that needs offline access to job listings — don’t paginate the search endpoint. Use the export API instead. POST /v2/jobs/export takes the same filter shape as /jobs/search but kicks off an async task that produces a single CSV or JSON file containing every matching job. You then poll GET /v2/tasks/{task_id} until state is "completed", download the file from result.download_url, and load it into your own database (Postgres, ElasticSearch, MongoDB — whatever fits your stack). 
# Kick off an export of every Software Engineer role posted in the last 30 days
curl -X POST https://api.hirebase.org/v2/jobs/export \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "search": {
      "job_titles": ["Software Engineer"],
      "days_ago": 30
    },
    "format": "json"
  }'
# → returns a task object; poll /v2/tasks/{id} until state="completed"
After your initial backfill, run smaller incremental exports on a schedule (e.g., daily with days_ago: 1) to pick up new listings, and use Expired Jobs to remove stale ones (see section 6).
Pagination fields (page, limit) are accepted in the search block but ignored — the export processes the entire matching result set. If you want a smaller export, narrow the filters instead.

​
3. Similar Jobs / Recommendations

Use: POST /v2/jobs/vsearch with search_type: "job" If you have a job detail page and want a “Similar jobs” rail at the bottom, vector search is built for this. Pass the _id of the job the user is looking at, and Hirebase returns the most semantically similar listings: 
curl -X POST https://api.hirebase.org/v2/jobs/vsearch \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "search_type": "job",
    "job_id": "67d550e407a47816d9b14f42",
    "top_k": 10
  }'
Each returned job comes with a score between 0 and 1 — use it to sort or to threshold low-quality matches. This works much better than re-running a keyword search with the original job’s title, because vector similarity captures things like “ML engineer” being close to “AI engineer” without the strings matching. The same endpoint with search_type: "summary" powers a natural-language search bar — useful if you want users to type “remote backend role at a Series B fintech with equity” instead of clicking filters.

​
4. Resume-to-Jobs Matching

Use: POST /v2/resumes/embed → POST /v2/jobs/vsearch with search_type: "resume" If your product takes a candidate’s resume (PDF, DOCX, etc.) and recommends jobs, do it in two steps:
  1. Upload the resume to /v2/resumes/embed. You get back parsed structured data plus an artifact_id.
  2. Pass the artifact_id into /v2/jobs/vsearch with search_type: "resume" to get a ranked list of matching jobs.
# Step 1 — embed
curl -X POST https://api.hirebase.org/v2/resumes/embed \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@candidate-resume.pdf"

# Step 2 — find matching jobs (artifact_id from step 1's response)
curl -X POST https://api.hirebase.org/v2/jobs/vsearch \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "search_type": "resume",
    "artifact_id": "ARTIFACT_ID_FROM_STEP_1",
    "top_k": 25
  }'
You can store the artifact_id and re-query against it whenever new jobs come in — no need to re-upload the resume each time.

​
5. Company Profiles and Sales Prospecting

Use: POST /v2/hirebase/companies/search + GET /v2/hirebase/companies/{company_slug} If you’re building company profile pages, a “companies hiring now” directory, or a sales prospecting tool that targets companies with active job openings, the company endpoints are the right place to start. A common pattern: search for companies matching your ICP (e.g., Series A–C fintech in the US), then for each result pull their open roles to see what they’re hiring for and at what scale. The job count is a strong signal of growth.

​
6. Keeping a Synced Database Fresh

Use: GET /v2/jobs/expired-jobs on a schedule If you’ve taken the export route and have a local copy of Hirebase data, you need two things to keep it fresh:
  1. New jobs — run a small daily export with days_ago: 1 (or since_date) and upsert into your DB.
  2. Removed jobs — call /v2/jobs/expired-jobs?since=YYYY-MM-DD daily, and mark the returned (company_slug, job_slug) pairs as expired in your DB.
curl -X GET 'https://api.hirebase.org/v2/jobs/expired-jobs?since=2026-04-24&limit=1000' \
  -H 'x-api-key: YOUR_API_KEY'
This pair of jobs (export for new, expired-jobs for removed) is enough to keep a local mirror within ~24 hours of the live source.

​
Combining Endpoints

Most real products use more than one endpoint. A typical job-board build looks like:
  1. Search — POST /v2/jobs/search powers the search bar.
  2. Detail — GET /v2/jobs/{job_id} powers the job detail page.
  3. Similar — POST /v2/jobs/vsearch (with search_type: "job") powers the “Similar jobs” rail at the bottom.
  4. Company — GET /v2/hirebase/companies/{slug} powers the company sidebar.
A typical recommendations product looks like:
  1. Embed — POST /v2/resumes/embed once per user when they sign up.
  2. Match — POST /v2/jobs/vsearch (with search_type: "resume") on a schedule to surface new matches.
A typical analytics or LLM-agent product looks like:
  1. Backfill — one big POST /v2/jobs/export to seed your DB.
  2. Daily delta — small export + expired-jobs calls on a cron.
  3. Query locally — once the data is yours, you can index, embed, and serve it however you want.

​
Still not sure?

Pick /v2/jobs/search and start prototyping. If you find yourself paginating past page ~2,000, switch to /v2/jobs/export. If you find yourself running the same query repeatedly to refresh data, switch to /v2/jobs/export + /v2/jobs/expired-jobs on a schedule. If users are typing natural-language queries instead of clicking filters, add /v2/jobs/vsearch. Email spencer@hirebase.org if you want a sanity check on which endpoint fits — happy to talk through a specific use case.