Skip to main content

Trigger a search against a corpus

POST 
/api/v1/cvds/search

Start a search of one corpus for the best-first candidates against a position. Returns immediately with a run id and status: "pending"; the search runs asynchronously. Read the result by polling GET /api/v1/cvds/runs/{id} or via the completion webhook.

Position config (position_metadata)​

position_metadata is the position-config object the search plans against. It is the same shape CV DeepMatch consumes as its requirements config — see the CvdsPositionMetadata schema and the Position config reference for the field-by-field contract (the 1–5 importance scale, where each requirement belongs, education ON/OFF, cardinality limits). The search does not constrain the inner shape beyond requiring a non-empty object.

Job updates & caching​

The search planner caches a plan per position_id. Set job_updated: true when the position's requirements changed since the last search so the plan is rebuilt; leave it false (default) to reuse the cached plan and re-rank.

top_n​

How many best-first candidates to return (default 100). Values above the server cap (1000) are clamped.

Webhook URL requirements​

  • Optional. Omit to poll-only.
  • When provided, must use https:// (INSECURE_WEBHOOK_URL otherwise) and must not resolve to a private / loopback / link-local address (PRIVATE_WEBHOOK_URL). DNS is re-checked before each delivery attempt (DNS-rebinding defense).

Idempotency​

Pass an idempotency_key to make the trigger safe to retry — the same key replays the existing run id instead of starting a new search.

Required permission​

Client's permissions[] must contain cvdeepsearch (403 MISSING_PERMISSION otherwise).

Request​

Responses​

The search was triggered (or an idempotency replay returned the existing run). Poll the run id for the result.