docs get started

Quickstart

API key, a place lookup, and a search plan that waits for confirm.

About five minutes. You get a key, resolve Ghent, plan a search from a job note, and preview a run. Nothing is fetched or charged until you start a run.

Run the script

The script talks to https://api.recruitmcp.com by default. Set RECRUITMCP_BASE (and RECRUITMCP_MCP for the MCP host) to point it at another server.

#!/usr/bin/env bash
set -euo pipefail
DOMAIN="${RECRUITMCP_DOMAIN:-recruitmcp.com}"
BASE="${RECRUITMCP_BASE:-https://api.${DOMAIN}}"
MCP="${RECRUITMCP_MCP:-https://mcp.${DOMAIN}/mcp}"
WS=$(curl -fsS -X POST "$BASE/v1/workspaces" \
  -H 'content-type: application/json' \
  -d '{"name":"Northwind Search","email":"ada@northwind.example"}')
KEY=$(node -e 'const j=JSON.parse(process.argv[1]); if(!String(j.api_key||"").startsWith("rmcp_live_")) process.exit(1); process.stdout.write(j.api_key)' "$WS")

PLACES=$(curl -fsS "$BASE/v1/lookups/locations?q=Gent,%20Belgium&prefer_area=true" \
  -H "authorization: Bearer $KEY")
node -e 'const j=JSON.parse(process.argv[1]); if(!/^[0-9]+$/.test(j.data?.[0]?.geo_id||"")) { console.error(j); process.exit(1); }' "$PLACES"

PLAN=$(curl -fsS -X POST "$BASE/v1/search-plans" \
  -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"job_description":"Senior backend engineer in Gent, Belgium. Go, 5+ years.","target":40}')
node -e 'const j=JSON.parse(process.argv[1]); if(j.estimate?.requires_confirm!==true||typeof j.estimate.credits_min!=="number"||!j.tiers?.[0]?.id||!j.tiers[0].label||!j.summary){console.error(j); process.exit(1)}' "$PLAN"

PID=$(node -e 'process.stdout.write(JSON.parse(process.argv[1]).id)' "$PLAN")
DRY=$(curl -fsS -X POST "$BASE/v1/runs?dry_run=true" \
  -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d "$(node -e 'process.stdout.write(JSON.stringify({plan_id:process.argv[1]}))' "$PID")")
node -e 'const j=JSON.parse(process.argv[1]); if(j.estimate?.requires_confirm!==true||j.run){console.error(j); process.exit(1)}' "$DRY"
echo "$PLAN"

The script checks that the key starts with rmcp_live_, that the place lookup returns a numeric geo_id, that the plan has a summary, tiers, and estimate.requires_confirm: true, and that dry_run=true on the run returns an estimate without starting one.

What you should see

GET /v1/lookups/locations returns places with a geo_id. Ghent's metro area is 90009596.
POST /v1/search-plans reads titles, the place, years, and tools from the job text. It returns summary, tiers[] (each with id, label, and rank), applied_filters, ignored_fields, and estimate.credits_min / estimate.credits_max.
credits_min is one lead (1 credit) when the next page is not cached, otherwise 0. credits_max is the expected leads times 1 plus the expected live profiles times 2. max_profile_fetches lowers that ceiling.
balance_credits on the estimate is unchanged after planning.

You can skip the plan step: POST /v1/runs accepts job_description or an intent directly and plans first.

Ask Claude

Find a senior backend engineer in Gent, Belgium, Go, 5+ years, target 40. Tell me the summary, credits_max, and the tier labels. Do not start it yet.

Next: API layers, authentication, or the API reference for createRun.

API reference