vamo
Book a demo
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 Turbopuffer filter: `[attr, Op, value]`, `[And|Or, [...]]` or `[Not, f]`.

  • rank_by one of

    A Turbopuffer rank_by: ANN (`[Embed, text]`, a vector, or `{like: [...]}`), exact kNN (a vector or `{like}`; pair it with filters), BM25 (options as a 4th element), attribute order (up to 8 keys), or a score expression.

  • limit one of

    Single lane: a number counts people (1 to 100); `{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.

    min 2 items, max 32 items
    • filters one of

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

    • rank_by one of

      A Turbopuffer rank_by: ANN (`[Embed, text]`, a vector, or `{like: [...]}`), exact kNN (a vector or `{like}`; pair it with filters), BM25 (options as a 4th element), attribute 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.

    coreenricheddeep
  • facets array of string default: []

    À-la-carte facet keys on top of the depth tier.

    max 5 items
  • garden string

    Which shape the contribution garden comes back in. `summary` (the default) is a compact `gardenSummary`: totals, active days and weeks, the last 90 days, the last active day and per-month counts, with `garden` null. `full` is the whole `garden`: every day’s count for the trailing year, for drawing a heatmap.

    fullsummary
  • 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

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
  • 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_failed
    • 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_mailbox
      • 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_failed
    • 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_mailbox
      • 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_failed
    • 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_mailbox
      • 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
  • 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
  • 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
vamo
PricingLearning CenterSupport CenterAgent skillsBook a demoChangelogPrivacyTerms

© 2026 Vamo Holdings, Inc.