vamo
Book a call
Documentation navigation
POST /v2/developers/search/validate

Validate a developer search

Access
Authenticated
search:read
Cost
Free
Rate limit
10 / second per actor
Quota
None

Checks and compiles the query exactly as POST /v2/developers/search would (names resolved, text normalised, defaults filled) without running it. Free.

Request body DeveloperQuery

  • version number default: 1

    Optional here: 1.

    1
  • ask string

    The ask in words; the re-rank reads it.

    max 2000 chars
  • filters one of

    A filter: `[field, Op, value]`, `[And|Or, [...]]` or `[Not, f]`.

  • rank_by one of

    How to rank: by meaning (`[v, ANN, [Embed, text]]`, a vector, or `{like: [...]}`), exact nearest neighbours (`kNN`: a vector or `{like}`; pair it with filters), keywords (`BM25`, options as a 4th element), field order (up to 8 keys), or a score expression.

  • limit one of

    Single lane: a number counts people (1 to 1000); `{total, per}` counts rows. With queries: people.

  • include array of string
    max 50 items
  • compute any
  • queries array of DevsLane

    2 or more lanes (3 by default), fused by person. Top-level `filters` are ANDed into every lane; `rank_by`, `include` and `compute` go inside each lane.

    min 2 items, max 32 items
    • filters one of

      A filter: `[field, Op, value]`, `[And|Or, [...]]` or `[Not, f]`.

    • rank_by one of

      How to rank: by meaning (`[v, ANN, [Embed, text]]`, a vector, or `{like: [...]}`), exact nearest neighbours (`kNN`: a vector or `{like}`; pair it with filters), keywords (`BM25`, options as a 4th element), field order (up to 8 keys), or a score expression.

    • limit one of

      Rows: a number, or `{total, per}` (per = rows per person, 1 to 5, default 3).

    • include array of string
      max 50 items
    • compute any
  • fuse one of
  • rerank string

    none, rules (default when the query has text), clef or jev.

    nonerulesclefjev
  • sort string

    relevance (default) or a person field, highest first. With no text and no rank_by the index sorts by it; otherwise the people found are re-ordered by it (nulls last). recent = last_active_at (GH Archive, partial).

    relevancedevrankstarsfollowersrecent
  • consistency string

    eventual (default; the index is written in batches) or strong (every write before the query).

    eventualstrong
  • repos object

    People who own and/or contributed to 1 to 10 repos (owner/name), combined with every other filter, text and sort.

    • names array of string required
      min 1 items, max 10 items
    • role string default: "either"

      owner, contributor, or either (default).

      ownercontributoreither
    • hops one of

      1: the people on the repos; 2: worked with them (people who share another repo with them, members excluded).

  • judge object

    clef / jev: how many of the rules top the model scores (default 20) and the per-call cap (default 900 ms).

    • top integer
      min 1, max 30
    • timeout_ms integer
      min 100, max 3000
  • depth string default: "core"

    The depth ladder: core (the default), enriched, deep. Each step returns more of the profile. Deep adds the contribution garden only when `garden` is sent; without it deep is enriched.

    coreenricheddeep
  • facets array of string default: []

    À-la-carte facet keys on top of the depth tier, resolved at every depth (core included): `identity.linkedin`, `contact.socials`, `contact.emails`, `tags.repos` or `ai.match_rationale` (judged against the query). A depth tier name (`core`, `enriched`, `deep`) is also accepted. Anything else is a 400. The AI summaries (`ai.person_summary`, `ai.repo_summaries`) are sold on GET /v2/developers/summaries and GET /v2/developers/enrich only: naming one here is a 400.

    max 5 items
  • garden one of

    Opt in to each developer’s contribution garden. Off unless sent: a garden is a GitHub read and a large block for an agent to carry. `true` or `summary` returns the compact `gardenSummary` (totals, active days and weeks, the last 90 days, per-month counts); `full` returns the whole daily `garden`, for drawing a heatmap.

  • repoLimit integer default: 4
    min 1, max 12
  • cursor string

    The previous page’s `cursor`: the next people for the same query.

    max 16384 chars
  • exclude array of string

    Developer ids never to return (up to 1000), e.g. people you already hold.

    max 1000 items
  • include_thin_profiles boolean

    true also returns profiles whose profile_quality is empty (no email, no profile README, no recent activity and little else to go on) or bot, which search and similar hide by default. Thin profiles are always returned.

Responses

  • 200 The compiled request
    • ok boolean required
      true
  • 400 The query does not compile; `hint` says what to change
    • ok boolean required
      false
    • error string required
    • hint string required
    • code string

      Why the index failed: index_busy, too_many_in_flight, engine_timeout, upstream_failed, ...

      bad_requestnot_foundindex_busytoo_many_in_flightengine_timeoutupstream_failednot_enabled
    • requestId string

      Quote it when reporting a failure

    • retryAfterMs integer

      Wait this long before retrying (also Retry-After, in seconds)

  • 401 Missing or invalid API key
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_errorbuild_failedself_serve_checkout_disabledwork_email_requiredtrial_unavailablecheckout_pendingchange_email_not_allowed
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at how to restore access).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailboxbook_callcheckout
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

  • 402 Your plan does not include this capability
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_errorbuild_failedself_serve_checkout_disabledwork_email_requiredtrial_unavailablecheckout_pendingchange_email_not_allowed
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at how to restore access).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailboxbook_callcheckout
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

  • 403 The key lacks search:read
    • code string required

      Stable machine-readable error code. Branch on this, never on the numeric status.

      bad_requestunauthorizedsignature_requiredpayment_requiredforbiddennot_foundconflictgonepayload_too_largeunprocessable_entitytoo_many_requestsinternal_errornot_implementedbilling_unavailablenot_contactablemailbox_link_unavailablemailbox_requiredmail_engine_unavailablewebhook_publisher_unavailabledatabase_unavailableclient_errorbuild_failedself_serve_checkout_disabledwork_email_requiredtrial_unavailablecheckout_pendingchange_email_not_allowed
    • message string required

      Human-readable explanation of the refusal.

    • status integer required

      The HTTP status code, repeated in the body.

    • remedy object

      A self-serve path forward, when one exists (a 402 points at how to restore access).

      • kind string required

        What kind of remedy this is, so a client can route it: whether the caller can clear the condition through the API, or a person must act in the web app.

        topupconnect_mailboxbook_callcheckout
      • url string required

        Where to go to clear the condition: an API path, or a web app page when only a person can.

  • 404 The seed is not in the index
    • ok boolean required
      false
    • error string required
    • hint string required
    • code string

      Why the index failed: index_busy, too_many_in_flight, engine_timeout, upstream_failed, ...

      bad_requestnot_foundindex_busytoo_many_in_flightengine_timeoutupstream_failednot_enabled
    • requestId string

      Quote it when reporting a failure

    • retryAfterMs integer

      Wait this long before retrying (also Retry-After, in seconds)

  • 429 Rate limit (10 requests per second per key), or the index is busy; see Retry-After
    • ok boolean required
      false
    • error string required
    • hint string required
    • code string

      Why the index failed: index_busy, too_many_in_flight, engine_timeout, upstream_failed, ...

      bad_requestnot_foundindex_busytoo_many_in_flightengine_timeoutupstream_failednot_enabled
    • requestId string

      Quote it when reporting a failure

    • retryAfterMs integer

      Wait this long before retrying (also Retry-After, in seconds)

  • 503 Search is not enabled in this environment, or the index is unavailable; see Retry-After
    • ok boolean required
      false
    • error string required
    • hint string required
    • code string

      Why the index failed: index_busy, too_many_in_flight, engine_timeout, upstream_failed, ...

      bad_requestnot_foundindex_busytoo_many_in_flightengine_timeoutupstream_failednot_enabled
    • requestId string

      Quote it when reporting a failure

    • retryAfterMs integer

      Wait this long before retrying (also Retry-After, in seconds)

  • 504 The index did not answer in time; retry, and see Retry-After
    • ok boolean required
      false
    • error string required
    • hint string required
    • code string

      Why the index failed: index_busy, too_many_in_flight, engine_timeout, upstream_failed, ...

      bad_requestnot_foundindex_busytoo_many_in_flightengine_timeoutupstream_failednot_enabled
    • requestId string

      Quote it when reporting a failure

    • retryAfterMs integer

      Wait this long before retrying (also Retry-After, in seconds)

vamo
PricingLearning CenterSupport CenterAgent skillsBook a callCase studiesChangelogPrivacyTerms

© 2026 Vamo Holdings, Inc.