The Query Generator AI Agent turns a job description into a refined Elasticsearch person-search query. Submit a JD asynchronously and receive progress plus the final query/candidates via signed webhooks. Use agent_reasoning: true for the full evaluate/optimize loop, or leave it false (default) to generate criteria and the Elasticsearch query only.
Query Generator AI Agent — submit job description
Submit a job description to the Query Generator AI Agent. The agent extracts hiring criteria and builds an Elasticsearch person-search query.
You receive a 202 Accepted immediately. Progress updates and the final result are delivered via signed webhooks to your callback_url.
agent_reasoning (default false):
false— Fast path: extract criteria and generate the boolean search + Elasticsearch query only (no evaluate/optimize loop).true— Full agent loop: multiple iterations that evaluate results and optimize the query until confirmed.
Flow:
- POST a job description with
callback_url,callback_secret, andsearch_id. - Optionally set
agent_reasoningtotruefor the full optimize/evaluate loop. - Receive
step.progresswebhooks while the agent works. - Receive a terminal
run.completedorrun.failedwebhook with the finales_query,boolean_search, criteria, hit count, and top candidates.
Webhooks: Every event is POSTed to callback_url with header X-Signature: hex(hmac_sha256(raw_body, callback_secret)). Verify the signature before trusting the payload. Respond with any 2xx quickly (under 5 seconds). Deduplicate on (task_id, sequence).
step.progress: Best-effort (1 attempt). Safe to miss - the terminal event carries the full result.run.completed/run.failed: Reliable (retries with backoff).
Idempotency: Send an Idempotency-Key header on retries to avoid starting a duplicate run.
Authentication: All requests require ONLY the X-API-Key header with your API key.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredRequired. Your API key for authentication. This is the only authentication header needed for this endpoint.
Idempotency-KeystringOptional unique key. A repeated key returns the original
202body instead of starting a new run.
Request Body
job_descriptionstring · minLength: 1 · requiredRaw job description text. The agent extracts titles, skills, location, seniority, and other hiring criteria from this.
callback_urlstring · uri · requiredHTTPS webhook URL that receives progress and terminal events. Must be on the allowed domain list.
callback_secretstring · minLength: 1 · requiredShared secret used to HMAC-SHA256-sign every webhook payload (
X-Signatureheader).search_idstring · minLength: 1 · requiredYour reference ID. Echoed unchanged on every response and webhook event; never interpreted by the agent.
indexstringElasticsearch index to target. Defaults to
person.Default: personagent_reasoningbooleanControls how deeply the agent works the query.
false(default) — Extract criteria and generate the boolean search + Elasticsearch query only. No evaluate/optimize loop.true— Full reasoning mode: multiple iterations that evaluate hit results and optimize the query until confirmed.
Default: falseshould_emit_eventbooleanWhen
false, suppressesstep.progresswebhooks; you still receive the terminalrun.completed/run.failed.Default: trueoptionsobjectOptional tuning for the agent evaluator loop. Most relevant when
agent_reasoningistrue.
Responses
Job accepted. Wait for signed webhooks on your callback_url.
task_idstringUnique run ID. Use for webhook correlation.
search_idstringYour reference ID, echoed from the request.
statusstring · enumInitial status after accept.
Enum values:ACCEPTED