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). For an inline, unsaved search the API does not constrain the inner shape beyond requiring a non-empty object.

Saved-job references​

Instead of sending position_metadata inline, reference a job saved in the Jobs catalog:

  • At least one of position_id / job_id is required. position_id is your own key; job_id is the platform id. When both are sent they must resolve to the same saved job (400 INVALID_INPUT otherwise); job_id wins for resolution.
  • Omit position_metadata to run with the referenced job's stored content, composed as {...config, job_description}. A reference that resolves to no saved job for your client returns 400 JOB_NOT_FOUND.
  • saveJob: true saves the inline position_metadata as a job before running. The blob is decomposed — the reserved job_description key becomes the job's JD prose, the remainder its config — and strictly validated with the save-time contract. On failure the search returns 400 INVALID_INPUT with per-field detail, nothing is saved and no run is started. Inline searches without saveJob stay unvalidated exactly as before. A job_id alone can only update an existing job — it never creates one (use position_id to create).
  • The run responses expose the run's job_id attribution (null for pure inline runs).

Job updates & caching​

The search planner caches a plan per position. For an inline (unsaved) search, 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.

For a run whose content comes from a saved job (a reference-only search, or a saveJob that just updated it), the platform derives job_updated automatically — true exactly when the job changed since the last search of that job against the same corpus (or when it is the first such search) — and ignores the client-sent value. You never need to track plan staleness for saved jobs.

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.