Skip to main content
POST
Search talents by prompt

First time? Set up Authentication

Learn how to authenticate your API requests with your API key.
Search the Kalent talent database with a plain-language description of who you are looking for. Instead of building a filters array yourself, you send a single prompt and the API converts it into structured filters automatically — the same engine that powers the Kalent MCP search_talents tool. Results are ranked by best overall match. This endpoint is the natural-language counterpart of POST /v1/search/talents. The success response is identical to that endpoint. Only ready profiles are returned: talents that are already up to date, or that were synchronously refreshed and passed refiltering. Profiles currently being updated asynchronously are excluded from the current response and counted in pendingRefreshCount.

Request body

string
required
A natural-language description of the talent you are looking for — e.g. "Senior React developer in Paris with 5+ years experience". The API interprets the prompt and derives the structured filters (job title, location, skill, years of experience, etc.) used to run the search. If the prompt cannot be turned into any usable filter, the request returns prompt_interpretation_failed.
Array of searchTransactionId values from previous search responses. When provided, talents that were returned in those previous searches are excluded from the current results. Use this field for pagination: after each search, collect the searchTransactionId from the response and include it (along with any earlier ones) in your next request to receive fresh, non-overlapping results. See Pagination below.

Response

boolean
Whether the request completed without errors.
object
Present when success is true.
object
Error details, present when success is false.

Pagination

Pagination works exactly like the filter-based endpoint: it uses a transaction-based pagination model instead of traditional page numbers. Send the same prompt again and accumulate previous searchTransactionId values in the relatedSearchTransactionIds array — each new request excludes all talents from every prior transaction so you never see the same talent twice. See the Pagination section of POST /v1/search/talents for the full mechanism.
Non-deterministic results — Search results are not guaranteed to be identical across requests, even with the same prompt. This is by design:
  • Prompt interpretation: the same prompt may be interpreted slightly differently between calls, which can shift the result pool.
  • Real-time profile refresh: talent profiles are enriched and updated in real time during search. A profile that did not match moments ago may match now (and vice versa) after a refresh.
  • AI-powered scoring: result ranking uses AI models whose outputs can vary slightly between calls.
  • Database updates: new talents are continuously indexed and existing profiles are updated from external sources.
The relatedSearchTransactionIds mechanism guarantees that you will not see the same talent twice across paginated requests, but the total pool of matching talents may shift between calls. This is inherent to a live, AI-augmented search engine and does not affect result accuracy.Read more in the Non-deterministic Results guide.

Response examples

Request
Response
Returned when the prompt could not be turned into any usable filter. Rephrase your prompt with more concrete search criteria (a role, a location, a skill, etc.).
Request
Response
Returned when the request body does not match the expected schema — for example when prompt is missing or empty.
Request
Response
Returned when the API key is missing or invalid.
Request
Response (missing key)
Response (invalid key)
Returned when your account does not have enough API credits to run the search. Top up your credits and retry.
Response