search (house keys)

`GET /v1/search`

Title search over open jobs: shape=page (the card) or shape=match (GUIDs for a campaign)

Title search over open jobs. Needs the search scope, which only house keys carry today: it opens to paid keys in a later release (step 16 of the plan), free, with the data still coming from the full feed. shape=page answers the card (title, company, source, posted_date) with each GUID; shape=match answers GUIDs with title_distance only, up to 10,000, for a campaign. Held closures and closed jobs are never in it.

Charged: nothing.

Parameters

Name	Type	Default	Allowed	What
`q` required	text	none	a title query	what to search for
`country`	list	none	country names	the cut by country
`system`	list	none	ATS names	the cut by system
`employment`	list	none	FULL_TIME, PART_TIME, CONTRACTOR, INTERN	a job with no type passes
`workplace`	list	none	On-site, Hybrid, Remote Solely, Remote OK
`posted_since`	time	none	ISO 8601
`visa`	boolean	none	true, false	visa sponsorship
`company`	list	none	company GUIDs	only these companies
`exclude_company`	list	none	company GUIDs	never these
`floor`	number	the store's 0.40	0 to 1	the similarity floor
`limit`	integer	20 (page), 1000 (match)	1 to 100 (page), 1 to 10000 (match)
`offset`	integer	0	0 to 5000	page 2 and on, shape=page only
`shape`	text	page	page, match

An unknown parameter is a 400 bad_request. country and system take one value, a comma list (country=Canada,Mexico) or a repeat (country=Canada&country=Mexico); the country is its English name as the data holds it; the system is the ATS name (greenhouse, lever.co, workday, ...): /v1/jobs/count lists the sizes, /docs/sizes shows them.

Answer

{
 "jobs": [
  {
   "job_guid": "<guid>",
   "title": "Registered Nurse",
   "company": "...",
   "source": "workday",
   "posted_date": "<time>",
   "title_distance": 0.0,
   "score": 0.0328
  }
 ],
 "capped": false,
 "path": "walk",
 "count": 2
}

Example

curl -s 'https://api.jobmonkey.ai/v1/search?q=registered%20nurse&country=United%20States&workplace=Hybrid&limit=2' -H 'Authorization: Bearer cb_live_XXXXXXXX'

{
 "jobs": [
  {
   "job_guid": "0f4a2c1e-7b3d-4a5e-8c9f-0a1b2c3d4e5f",
   "title": "Registered Nurse",
   "company": "Mercy Health",
   "source": "workday",
   "posted_date": "2026-11-04T08:12:00Z",
   "title_distance": 0.0,
   "score": 0.0328
  },
  {
   "job_guid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
   "title": "RN - Registered Nurse",
   "company": "Baptist Health",
   "source": "workday",
   "posted_date": "2026-11-03T15:40:00Z",
   "title_distance": 0.08,
   "score": 0.0411
  }
 ],
 "capped": false,
 "path": "walk",
 "count": 2
}

In Python

import json, urllib.request

KEY = "cb_live_XXXXXXXX"
req = urllib.request.Request("https://api.jobmonkey.ai/v1/search?q=registered%20nurse&country=United%20States&workplace=Hybrid&limit=2", headers={"Authorization": f"Bearer {KEY}"})
with urllib.request.urlopen(req) as r:
    answer = json.load(r)
    print(r.headers.get("X-Request-Id"), r.headers.get("X-Units-Charged"))
print(json.dumps(answer, indent=1)[:800])

Errors

400 bad_request
401 no_key / bad_key / account_off
403 no_scope
429 rate_limited

Headers

X-Request-Id
X-Units-Charged
RateLimit (limit=10, remaining=n, reset=s)
RateLimit-Policy (10;w=1, plus 10;w=86400 on a free key calling a free route)
X-Plan-Jobs-Remaining (the full feed and snapshots, when the plan has a cap)
X-Account: past_due (while an invoice is unpaid)

Every answer carries X-Request-Id; quote it to [email protected]. Times are UTC, ISO 8601.