Search developers

Request body DeveloperQuery

Responses

• 200 Developers with evidence and their index card
  • results array of DeveloperV2 required

    Best match first, in the v1 developer shape.

    • id string required

      The stable GitHub numeric id for this developer. Immutable (unlike the login) — this is the handle to pass to every other endpoint.

      max 64 chars
    • login string required

      The GitHub handle as of the last snapshot. Display it, do not key on it: handles are renameable and reusable.

      max 200 chars
    • name string | null required

      Display name as the developer set it on GitHub. Null when they set none.

      max 200 chars
    • avatarUrl string | null required

      GitHub avatar image URL. Null when absent.

      max 2048 chars
    • hasEmail boolean required

      Whether we hold at least one email address for this developer. It says we have an address on file, not that the address works — we do not check deliverability. The addresses themselves are never returned by a search or a base profile read: this boolean is the free signal, and the paid `contact.emails` facet is the only way to get them. Use `hasEmail` on a search request to filter to developers we hold an address for, without paying.

    • hasLinkedin boolean required

      Whether we hold a LinkedIn match for this developer — i.e. whether `enriched` will return `identity.*` and `contact.socials` for them. Available on the same base row as `hasEmail`: read both to decide what depth is worth requesting.

    • hasLocation boolean required

      Whether we hold any resolved location for this developer (from LinkedIn or a geocoded GitHub string). A free presence flag alongside `hasEmail`/`hasLinkedin`. The resolved `location` OBJECT rides `details.contact.location` at `enriched` (like the LinkedIn URL), not on the spine. Filter on it with `requireLocation=true`.

    • details PublicDetails required

      Every detail about this developer beyond the identity spine, as a KEYED object grouped by section. A section and its members appear only when resolved; absent details are omitted entirely. The set grows with depth: `core` fills `githubProfile.*` and `score.cracked`; `enriched` adds `identity.*`, `contact.socials` and `contact.location`; `deep` adds `github.garden`. À-la-carte: `tags.repos` folds onto `githubProfile.repos[]`, the emails route fills `contact.emails`.

      • githubProfile object

        The free GitHub profile: `githubProfile.core` (bio, org, languages, snapshot counts) and `githubProfile.repos`. Named for its source — everything here comes straight from GitHub.

        • core object

          bio, currentRole, organization, university, languages, joinedAt, followers, following, totalStars.

        • repos array of ProfileRepoWithTags

          Top repositories (default 4), with `owned`/`commits` and, when resolved, `subjects`/`technologies` (`tags.repos`) and a plain-English `summary`/`themes` (`ai.repo_summaries`) folded on. The full set of blurbs is also on `details.ai.repo_summaries.value`.

          • name string required

            The repository name alone, without the owner (`linux`).

            max 200 chars
          • fullName string required

            GitHub `owner/name`. This is the join key: an evidence repo and a profile repo describing the same repository carry the same `fullName`.

            max 200 chars
          • description string | null required

            The repository's own GitHub description, verbatim. Null when it has none.

            max 5000 chars
          • language string | null required

            GitHub's primary language for the repository. Null when GitHub reports none (an empty or docs-only repo); never inferred from the code.

            max 200 chars
          • stars integer required

            Stargazer count at the time this profile was snapshotted, not at request time.

            min 0, max 100000000
          • commits integer

            How many commits THIS developer authored to this repository over the trailing year. This is the difference between a project they wrote and a project they landed one drive-by fix in — a 385k-star repository with 4 of their commits is not their work. Absent when no commit signal was captured; 0 means none in the trailing year, which for older dormant work is not the same as none ever.

            min 0, max 100000000
          • owned boolean

            True when the repository sits under the developer's own account, false when it is someone else's (an organisation's or another person's) and they are a contributor to it. This is the difference between "they built this" and "they committed to this", and it is the ONLY honest basis for crediting a repository's stars to a person. Absent when no ownership signal was captured; treat absent as unknown, never as false.

          • url string required

            The public github.com URL of the repository.

            max 2048 chars
          • subjects array of string

            Subject/domain tags for this repository. Present only when `tags.repos` was resolved and this repo carried tags.

          • technologies array of string

            Technology tags for this repository. Present only when `tags.repos` was resolved and this repo carried tags.

          • summary string

            A one-line, plain-English blurb on what this repository is, written for a non-technical reader. Present only when `ai.repo_summaries` was resolved and the model could describe this repo. Folded onto the repos shown here; `details.ai.repo_summaries.value.repoSummaries` lists every repository that was summarized, including ones past `repoLimit`.

          • themes array of string

            A few short themes the AI drew from this repository. Present alongside `summary` when `ai.repo_summaries` was resolved.

      • score object

        The cracked score (`score.cracked`).

        • cracked object

          crackedScore, tier.

      • identity object

        The resolved external identity (`enriched`): `identity.linkedin`, `identity.experience`, `identity.education`.

        • linkedin object

          The resolved LinkedIn identity scalars (linkedin, headline, title, company, seniority, expertise, location).

        • experience array of object

          Employment history, newest first. Present only when non-empty.

          • title string | null

            Job title.

            max 200 chars
          • company string | null

            Employer name.

            max 200 chars
          • startDate string | null

            Start date exactly as the source rendered it. Free text, not normalised.

            max 200 chars
          • endDate string | null

            End date, same unnormalised free-text form. Null on a current role.

            max 200 chars
          • current boolean | null

            The source's own "still there" flag.

        • education array of object

          Education history, in the order the source listed it. Present only when non-empty. Entries are not ordered by level and can include secondary schools, so read every entry when confirming a university or a graduation year.

          • school string | null

            Institution name.

            max 200 chars
          • degree string | null

            Degree awarded.

            max 200 chars
          • fieldOfStudy string | null

            Field of study.

            max 200 chars
          • startDate string | null

            Start date as the source rendered it.

            max 200 chars
          • endDate string | null

            End date as the source rendered it.

            max 200 chars
      • contact object

        Contact channels: `contact.socials` (enriched), `contact.location` (enriched), `contact.emails` (the emails route).

        • socials object

          github, linkedin social links.

        • emails array of string

          Every address we observe for this developer, ranked, the best one first. Present only when we hold at least one, resolved via the emails route.

        • bestEmail string | null

          The address to use: the first unflagged personal address, else the first unflagged one; null when every address is flagged. On v2 only.

        • emailDetails array of object

          Every address with its type and flags, ranked, the most reliable first; within a source, personal, then work, then other. On v2 only.

          • address string required
          • type string required

            personal: a free-mail or own-name domain; work: a company domain; other: academic or government.

            personalworkother
          • flags array of string required

            Why it may not reach this person. `name_mismatch`: it names neither their current name nor their login (a prior name, or someone else). `low_link_confidence`: it came through a LinkedIn link we are not sure of. `ambiguous_link`: they map to several LinkedIn profiles. Flagged addresses are kept, never dropped.

        • location object | null

          Where this developer is, resolved once and LinkedIn-preferred: `source` says whether the clean city/country came from their LinkedIn (`linkedin`) or from geocoding their GitHub location string (`github`). Present at `enriched`+ whenever `hasLocation` is true — the spine carries only the `hasLocation` flag. Note the GitHub geocode is rough (it often drops a country string into `city`); trust `source: "linkedin"` over `"github"`.

          • raw string | null required

            The location string exactly as the developer typed it on GitHub ("SF / remote").

            max 200 chars
          • city string | null required

            City resolved from `raw` by geocoding. Null when `raw` was empty or unresolvable.

            max 200 chars
          • state string | null

            The country subdivision (US state, province, region) as a full name, e.g. "Ohio". Present only from the clean LinkedIn overlay, for the developers we hold a match for. Absent otherwise: the GitHub geocoder does not reliably resolve it (so we do not surface its guess), and it is legitimately absent for city-states and metro-only profiles.

            max 200 chars
          • country string | null required

            Country resolved from `raw`. Null when `raw` was empty or unresolvable. It can also be null while `city` is set, so read `city` and `raw` beside it before treating a location as unknown.

            max 200 chars
          • source string

            Where the resolved city/country came from: `linkedin` when our LinkedIn overlay supplied it (clean, self-reported on LinkedIn), `github` when it is geocoded from the GitHub `raw` string. Most developers have no LinkedIn match, so `github` is the common case and its city/country are often sparse. Absent on unresolved payloads.

            linkedingithub
      • github object

        The live-GitHub block (`deep`): `github.gardenSummary` by default, or the full `github.garden` with `garden=full`.

        • garden object

          The full contribution heatmap: every day’s count for the trailing year. Only with `garden=full`.

        • gardenSummary GardenSummary

          The contribution garden as a compact read (the default `garden=summary`): totals, active days and weeks, the last 90 days, per-month counts.

          • from string required

            First day of the garden window, `YYYY-MM-DD`, inclusive.

          • to string required

            Last day of the garden window, `YYYY-MM-DD`, inclusive.

          • total integer required

            Public contributions across the window.

          • activeDays integer required

            Days in the window with at least one contribution.

          • activeWeeks integer required

            Distinct weeks in the window with at least one contribution. Steady contributors score close to 52.

          • last90Days integer required

            Contributions in the 90 days ending on `to`.

          • lastActiveDay string | null required

            The most recent day with a contribution, `YYYY-MM-DD`. Null when the window is empty.

          • byMonth object required

            Contributions per calendar month, `YYYY-MM` → count. Months with none are omitted.

          • fetchedAt string required

            When the underlying garden was read from GitHub, as an ISO 8601 instant.

          • followers integer | null required

            Current GitHub follower count, live. Null on older gardens.

          • totalStars integer | null required

            Stars on repositories they OWN, live. Null on older gardens.

        • status string

          Present only when the garden did not come back, in place of it: `pending` (being read, re-fetch after `retryAfterMs`), `failed` (the GitHub read errored; a retry can succeed), `unavailable` (no garden exists for this developer). None of the three is charged.

          pendingfailedunavailable
        • retryable boolean

          With `status`: whether re-fetching this call can return the garden.

        • retryAfterMs number

          With `status: pending`: milliseconds to wait before re-fetching.

      • ai object

        À-la-carte AI prose. `person_summary`/`repo_summaries` come from the `/developers/summaries` route or `facets=ai.person_summary,ai.repo_summaries` on enrich, at every depth (never on the v2 search or similar). `match_rationale` comes from `facets=ai.match_rationale` on SEARCH, judged against your `q`. Compute is async, so each member carries a `status`: `ok` (the `value` is here), `pending` (with `retryAfterMs`: wait that long, then re-fetch this call once; the value is computed once, so a retry returns quickly), `failed` (with `retryable: true`: the write errored, and a re-fetch requests it again) or `unavailable` (with `retryable: true`: there is nothing to summarize yet, and a later read may return it). A member you asked for is never silently left out. A pending `person_summary`/`repo_summaries` can also be collected from `/developers/summaries` with the same ids: there, reading a developer is free while a summary your account has paid for is still being written, and for the one read that returns it finished. Read status before value.

        • person_summary object

          A short pitch for this developer. On `ok`, `value` is `{ personSummary, headline, body? }`: `personSummary` is the whole pitch as one string of two lines, a headline (who they are across their career) over one or two plain sentences on the kind of work they do and their most notable projects. `headline` is the first line, ready to set as a title. `body` is the rest, absent when the pitch is one line.

          • status string required

            `ok`: `value` is here. `pending`: being written, re-fetch after `retryAfterMs`. `failed`: the write errored and a re-fetch requests it again. `unavailable`: there is nothing to summarize yet, and a later read may return it.

            okpendingfailedunavailable
          • value object

            On `ok` only.

          • retryable boolean

            On `failed` and `unavailable`: whether re-fetching this call can return the value.

          • retryAfterMs number

            On `pending` only: milliseconds to wait before re-fetching this call. The value is computed once, so a retry returns `ok` quickly once it lands.

        • repo_summaries object

          The per-repo AI blurbs. On `ok`, `value` is `{ repoSummaries: [{ fullName, blurb, themes? }] }`, one entry for every repository that was summarized (not only the ones `repoLimit` shows). The same blurbs also fold onto `githubProfile.repos[].summary`/`.themes` for the repos shown.

          • status string required

            `ok`: `value` is here. `pending`: being written, re-fetch after `retryAfterMs`. `failed`: the write errored and a re-fetch requests it again. `unavailable`: there is nothing to summarize yet, and a later read may return it.

            okpendingfailedunavailable
          • value object

            On `ok` only.

          • retryable boolean

            On `failed` and `unavailable`: whether re-fetching this call can return the value.

          • retryAfterMs number

            On `pending` only: milliseconds to wait before re-fetching this call. The value is computed once, so a retry returns `ok` quickly once it lands.

        • match_rationale object

          Whether and why this developer matches the search query, judged against it. SEARCH ONLY (there is no query to judge against on an id lookup). `value` is `{ matched, reasons? }`: a real match is `{ matched: true, reasons: ["Currently Staff Engineer at Stripe on payments", "Maintains a Go ISO-20022 library", "8 years shipping Go"] }` — a list of short, positive, recruiter-facing bullets (repos, languages, LinkedIn role/company, organisation, location, tenure). A weak/non-match is `{ matched: false }` (no reasons — an honest verdict, not a manufactured one). Check `matched` before reading `reasons`.

          • status string required

            `ok`: `value` is here. `pending`: being written, re-fetch after `retryAfterMs`. `failed`: the write errored and a re-fetch requests it again. `unavailable`: there is nothing to summarize yet, and a later read may return it.

            okpendingfailedunavailable
          • value object

            On `ok` only.

          • retryable boolean

            On `failed` and `unavailable`: whether re-fetching this call can return the value.

          • retryAfterMs number

            On `pending` only: milliseconds to wait before re-fetching this call. The value is computed once, so a retry returns `ok` quickly once it lands.

    • match DeveloperMatch required

      Query attribution for this result: the matched repositories and whether the lane could attribute at all.

      • repos array of MatchRepo required

        The repositories that connect this developer to your query. Empty whenever `status` is `unattributed`.

        max 12 items
        • fullName string required

          GitHub `owner/name`. The join key onto `developer.repos[].fullName`, so you can match an evidence repo back to the profile repo it refers to.

          max 160 chars
        • stars integer required

          Stargazer count at retrieval time. 0 also means "the source returned no count", so do not read 0 as proof the repo is unstarred.

          min 0, max 100000000
        • language string | null

          GitHub’s primary language for the repository. Null when none was returned; never inferred from the code. Absent on pages produced before this field existed.

          max 200 chars
        • role string | null

          This person’s relationship to the repository, and it is deliberately conservative. `owner` means the repository sits under THEIR account. `contributor` means everything else, including the person who wrote most of the code in someone else’s or an organisation’s repository — a top committer on a company repo is a `contributor`, so do not read `contributor` as "minor" or `owner` as "wrote it". Null means the lane that produced this row genuinely cannot tell; absent means an older producer did not emit the field.

          ownercontributor
      • status string required

        Whether `repos` genuinely answers "why did this person come back for my query". `attributed` = it does. `unattributed` = the lane that answered cannot attribute repositories to the query, and `repos` is empty.

        attributedunattributed
    • hasEmail boolean | null

      null at depth core: the index card does not carry it. enriched and deep read it.

    • evidence DevsEvidence required
      • matches array of object required
        • kind string required
          profilereporole
        • similarity number | null required

          How close this row is to the query, 0 to 1; null when the row matched on a filter or keywords.

      • rerank object required

        The re-rank that ordered this person: `mode`, plus `status` (scored, skipped or timeout) and `reason` when the model re-rank fell back to rules.

        • mode string required
          nonerulesclefjev
      • similarity number | null required

        The best match similarity, 0 to 1; null when nothing scored the person (a filter or field order).

      • sort object

        The field values that placed this person when the query sorts by fields, e.g. `{devrank: 91}`.

      • hop integer

        /v2/developers/similar: 1 = like the person directly, 2 or more = reached by `widen` through the people they work with.

    • index object required

      The index card the search ran on: profile, top_repos, recent_roles.

      • profile object | null required
      • top_repos array of object required
      • recent_roles array of object
  • cursor string | null required

    Send it back as `cursor` with the same query for the next page; null at the end.

  • countStatus one of required
  • cached boolean required
  • rerank_applied string required
    nonerulesclefjev
  • rerank_skipped string | null required
  • rerank_judged object | null required
    • scored integer required
    • of integer required
  • filters_applied array of object required
    • lane number required
    • attr string required
    • op string required
    • value any
  • ids_resolved object required
  • places_resolved array of object required

    Each place that is a metro core city: the scope it ran with, its metro and how many city ids it filtered on.

    • place string required
    • scope string required
      metrocity
    • metro string required
    • member_count integer required
  • not_live array of string required

    Fields this request used whose data is still filling in. Each is still applied exactly as sent: people whose value is missing or wrong can be left out.

  • normalizer_version string required
  • timings object required
  • warnings array of object

    Present only when the query used a field with a caveat, e.g. a filter on a field that holds no data yet (it matches nobody). GET /v2/developers/fields lists the fields a request can use.

    • field string required
    • status string required
    • message string required
  • gardens_pending array of string required

    With `garden` sent: returned developers whose contribution garden is not held yet. It is being read now, so POST /v2/developers/gardens with these ids a few seconds later returns it. Always empty without `garden`.

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