{"openapi":"3.1.0","info":{"title":"Jobherder Agent API","version":"1.0.0","description":"Paid programmatic access to Jobherder job search. Two products: the full search (POST /api/v1/searches, €9.99, 7 matched roles, about an hour) and the quick match (POST /api/v1/quick-searches, $2.50 in USDC, the single best current role, 3 to 8 minutes). Both include a CV and cover letter tailored to each role. Buy full-search credits with a card (pack1: 1 search / EUR 9.99, pack3: 3 searches / EUR 24.99) or pay either product inline with x402. Credits are per product: a quick credit does not pay for a full search. No free runs. See https://jobherder.com/auth.md.","contact":{"email":"support@jobherder.com"}},"servers":[{"url":"https://jobherder.com"}],"x-x402":{"version_supported":[1,2],"scheme":"exact","network":"eip155:8453","network_v1":"base","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","pay_to":"0x6f5e9009157eceb33713af63057293b97cbf6415","facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","prices":[{"pack":"pack1","credits":1,"product":"search","amount_atomic":"11500000","amount_usdc":"11.50"},{"pack":"pack3","credits":3,"product":"search","amount_atomic":"28750000","amount_usdc":"28.75"},{"pack":"quick1","credits":1,"product":"quick","amount_atomic":"2500000","amount_usdc":"2.50"}],"request_header":"PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1)","challenge_header":"PAYMENT-REQUIRED","receipt_header":"PAYMENT-RESPONSE","payable_operations":["startSearch","startQuickSearch","createCheckout"],"resource_prices":{"https://jobherder.com/api/v1/searches":["pack1","pack3"],"https://jobherder.com/api/v1/quick-searches":["quick1"],"https://jobherder.com/api/v1/checkout":["pack1","pack3","quick1"]},"mcp_transport":{"tools":["start_job_search","quick_job_search"],"resources":["mcp://tool/start_job_search","mcp://tool/quick_job_search"],"request_field":"_meta[\"x402/payment\"]","receipt_field":"_meta[\"x402/payment-response\"]","challenge":"tool result with isError:true and PaymentRequired in structuredContent"},"note":"Settles on Base mainnet in USDC."},"x-mcp":{"url":"https://jobherder.com/mcp","transport":"streamable-http","auth":"Bearer <agent API key>; get_pricing and register_agent need none","tools":["get_pricing","register_agent","start_job_search","quick_job_search","get_search_status"],"payment":"x402 MCP transport: start_job_search and quick_job_search return PaymentRequired, retry with _meta[\"x402/payment\"]"},"x-service-info":{"categories":["jobs","ai"],"docs":{"homepage":"https://jobherder.com/agents","apiReference":"https://jobherder.com/auth.md","llms":"https://jobherder.com/llms.txt"}},"paths":{"/api/v1":{"get":{"summary":"Agent API payment challenge","operationId":"apiRoot","responses":{"402":{"description":"Payment required — register, buy credits via POST /api/v1/checkout","content":{"application/json":{"schema":{"type":"object","required":["error","message","credits_available","offers","docs"],"properties":{"error":{"type":"string","const":"payment_required"},"message":{"type":"string"},"credits_available":{"type":"integer","minimum":0},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["pack1","pack3"]},"credits":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents"},"currency":{"type":"string","example":"eur"},"label":{"type":"string"},"recommended":{"type":"boolean"},"checkout_path":{"type":"string","example":"/api/v1/checkout"},"checkout_body":{"type":"object","properties":{"pack":{"type":"string","enum":["pack1","pack3"]}}}}}},"docs":{"type":"string","format":"uri"}}}}}}},"x-payment-info":{"offers":[{"id":"pack1","amount":"999","currency":"eur","description":"One search — 7 shortlisted roles with a tailored CV and cover letter for each.","intent":"charge","method":"stripe"},{"id":"pack3","amount":"2499","currency":"eur","description":"Three searches — Three full searches to use whenever you want — about €8.33 each.","intent":"charge","method":"stripe"}]}},"post":{"summary":"Agent API payment challenge","operationId":"apiRootPost","responses":{"402":{"description":"Payment required — register, buy credits via POST /api/v1/checkout","content":{"application/json":{"schema":{"type":"object","required":["error","message","credits_available","offers","docs"],"properties":{"error":{"type":"string","const":"payment_required"},"message":{"type":"string"},"credits_available":{"type":"integer","minimum":0},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["pack1","pack3"]},"credits":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents"},"currency":{"type":"string","example":"eur"},"label":{"type":"string"},"recommended":{"type":"boolean"},"checkout_path":{"type":"string","example":"/api/v1/checkout"},"checkout_body":{"type":"object","properties":{"pack":{"type":"string","enum":["pack1","pack3"]}}}}}},"docs":{"type":"string","format":"uri"}}}}}}},"x-payment-info":{"offers":[{"id":"pack1","amount":"999","currency":"eur","description":"One search — 7 shortlisted roles with a tailored CV and cover letter for each.","intent":"charge","method":"stripe"},{"id":"pack3","amount":"2499","currency":"eur","description":"Three searches — Three full searches to use whenever you want — about €8.33 each.","intent":"charge","method":"stripe"}]}}},"/api/v1/health":{"get":{"summary":"Health check","operationId":"health","responses":{"200":{"description":"OK"}}}},"/api/v1/register":{"post":{"summary":"Register agent and receive API key (0 credits)","operationId":"register","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"key_name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created — api_key returned once; credits_available is 0","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"},"email":{"type":"string","format":"email"},"api_key":{"type":"string"},"key_id":{"type":"string"},"key_prefix":{"type":"string"}}}}}},"409":{"description":"Email already belongs to a Jobherder web account — create a key at POST /api/v1/keys while signed in"}}}},"/api/v1/checkout":{"post":{"summary":"Create Stripe Checkout for prepaid search credits","operationId":"createCheckout","security":[{"bearerAuth":[]}],"x-payment-info":{"offers":[{"id":"pack1","amount":"999","currency":"eur","description":"One search — 7 shortlisted roles with a tailored CV and cover letter for each.","intent":"charge","method":"stripe"},{"id":"pack3","amount":"2499","currency":"eur","description":"Three searches — Three full searches to use whenever you want — about €8.33 each.","intent":"charge","method":"stripe"}]},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"string","enum":["pack1","pack3"],"default":"pack3","description":"Credit pack SKU. Defaults to pack3 when omitted."}}}}}},"responses":{"200":{"description":"checkout_url for payment","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"},"session_id":{"type":"string"},"pack":{"type":"string","enum":["pack1","pack3"]},"credits":{"type":"integer"},"amount_cents":{"type":"integer"},"currency":{"type":"string","example":"eur"},"credits_available":{"type":"integer","minimum":0}}}}}},"402":{"description":"Payment required","content":{"application/json":{"schema":{"type":"object","required":["error","message","credits_available","offers","docs"],"properties":{"error":{"type":"string","const":"payment_required"},"message":{"type":"string"},"credits_available":{"type":"integer","minimum":0},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["pack1","pack3"]},"credits":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents"},"currency":{"type":"string","example":"eur"},"label":{"type":"string"},"recommended":{"type":"boolean"},"checkout_path":{"type":"string","example":"/api/v1/checkout"},"checkout_body":{"type":"object","properties":{"pack":{"type":"string","enum":["pack1","pack3"]}}}}}},"docs":{"type":"string","format":"uri"}}}}}}}},"get":{"summary":"List credits, recent orders, and available packs","operationId":"getCredits","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Credits summary","content":{"application/json":{"schema":{"type":"object","properties":{"credits_available":{"type":"integer","minimum":0},"paid_order_id":{"type":"string","nullable":true},"recent_orders":{"type":"array","items":{"type":"object"}},"packs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["pack1","pack3","quick1"]},"credits":{"type":"integer"},"amount_cents":{"type":"integer"},"label":{"type":"string"},"recommended":{"type":"boolean"}}}}}}}}}}}},"/api/v1/checkout/success":{"get":{"summary":"Confirm payment when Stripe webhook is delayed","operationId":"checkoutSuccess","security":[{"bearerAuth":[]}],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payment confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"credits_available":{"type":"integer","minimum":0}}}}}}}}},"/api/v1/searches":{"post":{"summary":"Start a paid search (consumes one credit)","operationId":"startSearch","security":[{"bearerAuth":[]}],"x-payment-info":{"offers":[{"id":"pack1","amount":"999","currency":"eur","description":"One search — 7 shortlisted roles with a tailored CV and cover letter for each.","intent":"charge","method":"stripe"},{"id":"pack3","amount":"2499","currency":"eur","description":"Three searches — Three full searches to use whenever you want — about €8.33 each.","intent":"charge","method":"stripe"}]},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. Same key replays the original response instead of consuming a second credit."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["profile","cv"],"properties":{"profile":{"type":"string","description":"JSON profile string"},"cv":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","required":["profile"],"description":"The profile, plus the CV supplied either as cv_json or as cv_base64 with cv_type.","properties":{"profile":{"$ref":"#/components/schemas/Profile"},"cv_json":{"type":"object","description":"The CV as structured data in the JSON Resume schema (jsonresume.org): basics, work, education, skills, projects, certificates, awards, publications, languages, interests. Preferred when you hold the CV as data rather than a file — no need to render a document."},"cv_base64":{"type":"string","description":"The CV as a base64-encoded file, up to 10MB."},"cv_type":{"type":"string","enum":["pdf","docx","txt"],"description":"Format of cv_base64. Plain text is accepted, so an agent with no document to upload can send the CV as text rather than rendering a PDF."}}}}}},"responses":{"201":{"description":"Search queued","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"run_id":{"type":"string"},"status":{"type":"string"},"credits_remaining":{"type":"integer","minimum":0},"order_id":{"type":"string"}}}}}},"402":{"description":"Payment required — no paid credit","content":{"application/json":{"schema":{"type":"object","required":["error","message","credits_available","offers","docs"],"properties":{"error":{"type":"string","const":"payment_required"},"message":{"type":"string"},"credits_available":{"type":"integer","minimum":0},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["pack1","pack3"]},"credits":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents"},"currency":{"type":"string","example":"eur"},"label":{"type":"string"},"recommended":{"type":"boolean"},"checkout_path":{"type":"string","example":"/api/v1/checkout"},"checkout_body":{"type":"object","properties":{"pack":{"type":"string","enum":["pack1","pack3"]}}}}}},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"A search is already running — poll it until terminal before starting another"}}},"get":{"summary":"Get search run status and matches","operationId":"getSearch","security":[{"bearerAuth":[]}],"parameters":[{"name":"run_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Run status; matches present on terminal success","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"run_id":{"type":"string"},"status":{"type":"string"},"plan":{"type":"string","enum":["one_off","agent_quick"]},"deliveries":{"type":"integer"},"target_jobs":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"terminal":{"type":"boolean"},"progress":{"type":"number"},"stage":{"type":"string"},"user_message":{"type":"string"}}},"matches":{"type":"array","description":"Present on terminal success","items":{"type":"object","properties":{"title":{"type":"string"},"company":{"type":"string"},"url":{"type":"string","format":"uri"},"score":{"type":"number"},"rank":{"type":"integer"},"source":{"type":"string"},"match_reason":{"type":"string","nullable":true,"description":"Why the candidate fits this role, from scoring. Null for runs completed before 31 Jul 2026."},"delivered_at":{"type":"string","format":"date-time"},"documents":{"type":"object","nullable":true,"description":"The tailored documents for this specific role, as markdown. The same documents are emailed as PDFs. Null on runs completed before 1 Aug 2026.","properties":{"cv_markdown":{"type":"string","nullable":true,"description":"The CV rewritten for this role"},"cover_letter_markdown":{"type":"string","nullable":true,"description":"A cover letter written for this role"}}}}}},"documents_note":{"type":"string"}}}}}}}}},"/api/v1/quick-searches":{"post":{"summary":"Start a quick match ($2.50, one role, minutes)","description":"The single best current role for this candidate, with a tailored CV and cover letter. Same request body as /api/v1/searches. Paid in USDC via x402: call it unpaid to receive the challenge, then retry with a PAYMENT-SIGNATURE header. Poll GET /api/v1/searches for status. Quick credits cannot pay for a full search, and vice versa.","operationId":"startQuickSearch","security":[{"bearerAuth":[]}],"x-payment-info":{"offers":[{"id":"quick1","amount":"250","currency":"usd","description":"One quick match — The single best current role, with a tailored CV and cover letter. Minutes, not an hour.","intent":"charge","method":"x402"}]},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional. Same key replays the original response instead of consuming a second credit."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["profile","cv"],"properties":{"profile":{"type":"string","description":"JSON profile string"},"cv":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","required":["profile"],"description":"The profile, plus the CV supplied either as cv_json or as cv_base64 with cv_type.","properties":{"profile":{"$ref":"#/components/schemas/Profile"},"cv_json":{"type":"object","description":"The CV as structured data in the JSON Resume schema (jsonresume.org): basics, work, education, skills, projects, certificates, awards, publications, languages, interests. Preferred when you hold the CV as data rather than a file — no need to render a document."},"cv_base64":{"type":"string","description":"The CV as a base64-encoded file, up to 10MB."},"cv_type":{"type":"string","enum":["pdf","docx","txt"],"description":"Format of cv_base64. Plain text is accepted, so an agent with no document to upload can send the CV as text rather than rendering a PDF."}}}}}},"responses":{"201":{"description":"Quick match queued","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"run_id":{"type":"string"},"status":{"type":"string"},"plan":{"type":"string","enum":["agent_quick"]},"target_jobs":{"type":"integer","enum":[1]},"credits_remaining":{"type":"integer","minimum":0}}}}}},"402":{"description":"Payment required — no quick credit","content":{"application/json":{"schema":{"type":"object","required":["error","message","credits_available","offers","docs"],"properties":{"error":{"type":"string","const":"payment_required"},"message":{"type":"string"},"credits_available":{"type":"integer","minimum":0},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["pack1","pack3"]},"credits":{"type":"integer"},"amount":{"type":"integer","description":"Amount in cents"},"currency":{"type":"string","example":"eur"},"label":{"type":"string"},"recommended":{"type":"boolean"},"checkout_path":{"type":"string","example":"/api/v1/checkout"},"checkout_body":{"type":"object","properties":{"pack":{"type":"string","enum":["pack1","pack3"]}}}}}},"docs":{"type":"string","format":"uri"}}}}}},"429":{"description":"A search is already running — poll it until terminal before starting another"}}}},"/api/v1/keys":{"get":{"summary":"List API keys","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Key list (prefixes only)"}}},"post":{"summary":"Create additional API key (Bearer key or signed-in session)","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"New api_key"}}},"delete":{"summary":"Revoke API key","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Revoked"}}}}},"components":{"schemas":{"Profile":{"type":"object","description":"Who the job seeker is and what they want. Twelve fields are required; the others default. cfg_seniority is retired — send cfg_seniority_level and cfg_target_titles.","required":["cfg_name","cfg_email","cfg_location","cfg_location_preference","cfg_work_style","cfg_want_remote_eu","cfg_want_remote_uk","cfg_want_usa","cfg_seniority_level","cfg_target_titles","cfg_local_country","cfg_industries"],"properties":{"cfg_name":{"type":"string","maxLength":80,"description":"Full name, as it appears on the tailored CV"},"cfg_email":{"type":"string","format":"email","description":"Must match the address this API key is registered to"},"cfg_location":{"type":"string","maxLength":100,"description":"Where they live, e.g. \"Berlin, Germany\""},"cfg_location_preference":{"type":"string","maxLength":200,"description":"Prose description of acceptable locations, read as intent rather than parsed"},"cfg_work_style":{"type":"string","enum":["remote_only","mix"],"description":"remote_only rejects anything needing office attendance; mix means local or hybrid near them plus remote in the chosen regions"},"cfg_want_remote_eu":{"type":"string","enum":["yes","no"],"description":"Include EU-remote roles"},"cfg_want_remote_uk":{"type":"string","enum":["yes","no"],"description":"Include UK-remote roles"},"cfg_want_usa":{"type":"string","enum":["yes","no"],"description":"Include USA roles. Say no unless they can work there legally"},"cfg_seniority_level":{"type":"string","maxLength":80,"description":"Seniority band, e.g. \"Director\" or \"Manager – Head of Department\""},"cfg_target_titles":{"type":"string","maxLength":200,"description":"Comma-separated target titles, e.g. \"Head of Production, COO\""},"cfg_local_country":{"type":"string","maxLength":80,"description":"ISO country name for where they live, e.g. \"Germany\""},"cfg_uk_onsite":{"type":"string","enum":["yes","no"],"default":"no","description":"Also include on-site roles in the UK"},"cfg_industries":{"type":"string","maxLength":200,"description":"Comma-separated sectors, not job functions"},"cfg_languages":{"type":"array","items":{"type":"string"},"default":["english"],"description":"Working languages. Roles needing a language not listed are dropped"},"cfg_not_interested_in":{"type":"string","maxLength":150,"default":"","description":"Comma-separated exclusions, applied as a hard filter"},"cfg_advisory_open":{"type":"string","enum":["yes","no"],"default":"yes","description":"Include advisory, fractional and board roles"},"cfg_additional_context":{"type":"string","maxLength":600,"default":"","description":"Visa position, notice period, salary floor, companies to avoid"},"cfg_share_with_employers":{"type":"string","enum":["yes","no"],"default":"no","description":"Consent to share the profile with employers"}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from POST /api/v1/register (jbr_live_…)"}}}}