CvdsSearchRequest

JSON body for POST /api/v1/cvds/search.

corpus_idstringrequired

The corpus to search. Mandatory + fail-closed.

Possible values: non-empty

Example: acme-eng-pool

position_idstringrequired

Your job identifier. The planner caches a plan per position_id — reuse the same id across searches for the same role.

Possible values: non-empty

Example: eng-backend-2026

position_metadata objectrequired

The position-config object a search plans against (the position_metadata field on POST /api/v1/cvds/search). This is the same shape CV DeepMatch consumes as its requirements config — see the CvDeepMatchRequirements schema and the Position config reference for the complete field-by-field contract (the 1–5 importance scale, where each requirement belongs, education ON/OFF, the language-config quirks, and the cardinality limits).

The API requires only that position_metadata be a non-empty object — the inner shape is the matching/search engine's contract, not validated field-by-field at this layer. Typically it carries a name and a requirements block:

{
  "name": "Senior Backend Engineer",
  "requirements": {
    "workExperience": { "from": 5, "to": 10, "importance": 5, "relevant_industries": ["SaaS"], "industries_config": [{ "name": "SaaS", "importance": 5 }] },
    "skills": { "importance": 5, "skills_config": { "hard_skills": [{ "name": "Node.js", "importance": 5 }], "requirements": { "minimal_qualifications": true, "preferable_qualifications": true } } }
  }
}

property name*any

The position-config object a search plans against (the position_metadata field on POST /api/v1/cvds/search). This is the same shape CV DeepMatch consumes as its requirements config — see the CvDeepMatchRequirements schema and the Position config reference for the complete field-by-field contract (the 1–5 importance scale, where each requirement belongs, education ON/OFF, the language-config quirks, and the cardinality limits).

The API requires only that position_metadata be a non-empty object — the inner shape is the matching/search engine's contract, not validated field-by-field at this layer. Typically it carries a name and a requirements block:

{
  "name": "Senior Backend Engineer",
  "requirements": {
    "workExperience": { "from": 5, "to": 10, "importance": 5, "relevant_industries": ["SaaS"], "industries_config": [{ "name": "SaaS", "importance": 5 }] },
    "skills": { "importance": 5, "skills_config": { "hard_skills": [{ "name": "Node.js", "importance": 5 }], "requirements": { "minimal_qualifications": true, "preferable_qualifications": true } } }
  }
}

Example: {"name":"Senior Backend Engineer","requirements":{"workExperience":{"from":5,"to":10,"importance":5,"relevant_industries":["SaaS","Fintech"],"industries_config":[{"name":"SaaS","importance":5},{"name":"Fintech","importance":4}]},"skills":{"importance":5,"skills_config":{"hard_skills":[{"name":"Node.js","importance":5}],"requirements":{"minimal_qualifications":true,"preferable_qualifications":true}}}}}

job_updatedboolean

true rebuilds the cached plan for this position_id (the role's requirements changed); false reuses the cached plan and re-ranks.

Default value: false

top_ninteger

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

Possible values: >= 1

Default value: 100

Example: 50

webhook_urluri

Optional HTTPS callback URL for completion delivery. Must be https:// and not resolve to a private / loopback / link-local address.

Example: https://example.com/cvds/callback

idempotency_keystring

Optional. Replays the existing run for the same key instead of starting a new search.

Possible values: non-empty and <= 255 characters

metadata object

Optional {key:value} correlation data attached to the run.

property name*string

tagsstring[]

Optional tags attached to the run for your own correlation/filtering.

Example: ["batch-3"]

CvdsSearchRequest

{
  "corpus_id": "acme-eng-pool",
  "position_id": "eng-backend-2026",
  "position_metadata": {
    "name": "Senior Backend Engineer",
    "requirements": {
      "workExperience": {
        "from": 5,
        "to": 10,
        "importance": 5,
        "relevant_industries": [
          "SaaS",
          "Fintech"
        ],
        "industries_config": [
          {
            "name": "SaaS",
            "importance": 5
          },
          {
            "name": "Fintech",
            "importance": 4
          }
        ]
      },
      "skills": {
        "importance": 5,
        "skills_config": {
          "hard_skills": [
            {
              "name": "Node.js",
              "importance": 5
            }
          ],
          "requirements": {
            "minimal_qualifications": true,
            "preferable_qualifications": true
          }
        }
      }
    }
  },
  "job_updated": false,
  "top_n": 50,
  "webhook_url": "https://example.com/cvds/callback",
  "idempotency_key": "string",
  "metadata": {
    "batch": "q2",
    "team": "emea"
  },
  "tags": [
    "batch-3"
  ]
}