Public Discover lists

Responses

• 200 The public lists
  • lists array of DiscoverList required

    Every list cleared for public reads, in the order staff arranged them.

    • slug string required

      The list slug.

    • title string required

      The list title.

    • blurb string required

      One line on who is on the list. Empty when it has none.

    • icon string | null required

      A lucide icon name (https://lucide.dev/icons, kebab-case) shown next to the list title. Null when the list has none.

    • logoUrl string | null required

      An https image URL (usually a company logo) shown next to the list title in place of the icon. Null when the list has none.

    • builtAt string required

      When the list was packaged, as an ISO 8601 instant.

    • complete boolean required

      False while a developer on the list is still waiting for a written description. They are left out of `rows` until it lands, and a later rebuild adds them.

    • rows array of object required

      The developers on the list, best first. Only developers with a written description.

      • developer object required

        The developer profile, as `POST /v1/developers` returns it.

        • developerId string required

          The stable Vamo identifier for this developer (GitHub's numeric user id, stringified). This is the id every other endpoint takes: facets, reports, contacts, shortlists, steering. Use it, not `login` — a login can be renamed and then belongs to someone else.

          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
        • currentRole string | null required

          A single free-text role line for the developer. Best-effort and unverified; `professional.title` is the LinkedIn-sourced equivalent when we hold a LinkedIn overlay.

          max 200 chars
        • organization object | null required

          The developer's current employer, when one is known. Null means we hold no employer, NOT that they are unemployed.

          • name string required

            The organization name as recorded.

            max 200 chars
          • logoUrl string | null required

            Organization logo URL, null when absent.

            max 2048 chars
        • university string | null required

          Most recent institution, when the LinkedIn overlay carries education. Null when unknown.

          max 200 chars
        • profiles object required

          Where this developer can be found, plus the addresses if you have already bought them.

          • github string required

            The developer’s github.com profile URL. Always present — GitHub is the identity anchor for every developer in the index.

            max 2048 chars
          • linkedin string | null required

            LinkedIn profile URL when we hold a GitHub↔LinkedIn match for this person. Null for the large majority of developers: only a minority of the indexed GitHub population carries a LinkedIn overlay, so null means "no match held", never "no LinkedIn account".

            max 2048 chars
          • emails array of string

            Every email address we hold for this developer. Present ONLY when this account has already paid to reveal them and the purchase is still within its reveal window; a base search or profile read never populates it. ABSENT is not the same as "no email": absent means you have not bought it, while `hasEmail: false` means we hold none. These are addresses we have OBSERVED — from public commit metadata and GitHub profile data — and we do not check deliverability, so treat the order as meaningless and expect some to bounce. Buy them with the `contact.emails` facet.

            max 50 items
        • 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.

        • bio string | null required

          The developer’s GitHub bio, verbatim. Null when empty.

          max 5000 chars
        • location object | null required

          Self-reported location, plus our geocoding of it. Self-reported and never verified against anything: a developer can leave it stale or blank. `source` says whether the clean city/country came from the LinkedIn overlay or from geocoding GitHub. Null when we hold nothing at all.

          • 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
        • joinedAt string | null required

          When the GitHub account was created, as an ISO 8601 instant. Null when unknown.

          max 40 chars
        • stats object | null required

          Snapshot counts and standing for this developer. These are from our index and go stale between refreshes; `GET /v1/developers/{id}` returns live GitHub equivalents alongside the contribution garden when you need current numbers. Null when we hold no stats at all.

          • followers integer | null required

            GitHub follower count at snapshot time.

            min 0, max 100000000
          • following integer | null required

            How many accounts this developer follows, at snapshot time.

            min 0, max 100000000
          • totalStars integer | null required

            Sum of stargazers across the repositories ATTRIBUTED to this developer — the same set as `repos`, so the count can never contradict the list. Owned and contributed-to repositories both count; forks do not.

            min 0, max 100000000
          • crackedScore number | null required

            Devrank: a 0–100 standing for this developer within the WHOLE indexed GitHub developer population (tens of millions of accounts), not within a language, region, or seniority peer group — so it is not a like-for-like comparison between two candidates for the same role. It is derived from the follower/contribution graph, is recomputed upstream on its own schedule, and carries no version on the wire, so the same developer can read differently across two snapshots. It contributes one term to the page-local `score` and backs the `levers.github.minDevrank` filter. Null when the developer is not in the devrank table.

          • tier string | null required

            The upstream provider’s own coarse label for `crackedScore` (for example "Elite"). The label set is the provider’s and is not a Vamo-stable vocabulary — treat it as display text and branch on `crackedScore` if you need a threshold. Null when the developer is not in the devrank table.

            max 200 chars
        • repos array of object required

          The developer’s top ATTRIBUTED public repositories — owned or authored-into, forks excluded — stars descending, capped at 12. This is a sample of their best work, not a complete repository list, and it is not an answer to "why did this person match my query" — read `evidence.matchedRepos` for that.

          max 12 items
          • 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
        • languages array of string required

          Distinct primary languages across the developer’s repositories, at most 8. Presence means they have shipped public code in it; the list is not ranked by proficiency and carries no line counts.

          max 8 items
        • experience array of object required

          Employment history from the LinkedIn overlay, newest first. Empty for any developer we hold no LinkedIn match for, which is most of them.

          max 25 items
          • title string | null

            Job title, on an experience entry.

            max 200 chars
          • company string | null

            Employer name, on an experience entry.

            max 200 chars
          • companyCanonicalId string | null

            Vamo canonical company id for the employer (`li_co:<LinkedIn company id>`, `dom:<domain>` or `name:<key>`). Absent when the employer is not matched to a verified company.

            max 200 chars
          • companyDomain string | null

            The employer's verified website domain (`vercel.com`). Absent when unknown; never derived from the name.

            max 200 chars
          • companyLogoUrl string | null

            The employer's logo image URL (https). Absent when we hold no verified logo.

            max 2048 chars
          • companyGithubOrg string | null

            The employer's GitHub organization login, verified by its website matching the company domain.

            max 200 chars
          • companyKind string

            `placeholder` when the employer is not a company (self-employed, freelance, stealth, between roles, ...). Such a row never carries a company domain, logo or id.

            placeholder
          • placeholderType string

            Which kind of placeholder employer, when `companyKind` is `placeholder`.

            self_employedfreelancestealthindependentconsultantbetween_rolesstudent
          • school string | null

            Institution name, on an education entry.

            max 200 chars
          • degree string | null

            Degree awarded, on an education entry.

            max 200 chars
          • fieldOfStudy string | null

            Field of study, on an education entry.

            max 200 chars
          • startDate string | null

            Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.

            max 200 chars
          • endDate string | null

            End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.

            max 200 chars
          • current boolean | null

            The source's own "still there" flag. Set on experience entries; null on education entries.

        • education array of object required

          Education history from the LinkedIn overlay. Empty for any developer we hold no LinkedIn match for.

          max 25 items
          • title string | null

            Job title, on an experience entry.

            max 200 chars
          • company string | null

            Employer name, on an experience entry.

            max 200 chars
          • companyCanonicalId string | null

            Vamo canonical company id for the employer (`li_co:<LinkedIn company id>`, `dom:<domain>` or `name:<key>`). Absent when the employer is not matched to a verified company.

            max 200 chars
          • companyDomain string | null

            The employer's verified website domain (`vercel.com`). Absent when unknown; never derived from the name.

            max 200 chars
          • companyLogoUrl string | null

            The employer's logo image URL (https). Absent when we hold no verified logo.

            max 2048 chars
          • companyGithubOrg string | null

            The employer's GitHub organization login, verified by its website matching the company domain.

            max 200 chars
          • companyKind string

            `placeholder` when the employer is not a company (self-employed, freelance, stealth, between roles, ...). Such a row never carries a company domain, logo or id.

            placeholder
          • placeholderType string

            Which kind of placeholder employer, when `companyKind` is `placeholder`.

            self_employedfreelancestealthindependentconsultantbetween_rolesstudent
          • school string | null

            Institution name, on an education entry.

            max 200 chars
          • degree string | null

            Degree awarded, on an education entry.

            max 200 chars
          • fieldOfStudy string | null

            Field of study, on an education entry.

            max 200 chars
          • startDate string | null

            Start date exactly as the source rendered it. Free text, NOT a normalised date: expect "2019", "Jan 2019" and "2019-01" from different records. Parse defensively.

            max 200 chars
          • endDate string | null

            End date in the same unnormalised free-text form as `startDate`. Absent or null on a current role.

            max 200 chars
          • current boolean | null

            The source's own "still there" flag. Set on experience entries; null on education entries.

        • professional object | null

          LinkedIn-sourced professional scalars, present only when we hold a LinkedIn match for this developer. Absent or null for the majority of developers, which says nothing about their employment — only that we hold no overlay.

          • headline string | null required

            The LinkedIn headline, verbatim.

            max 5000 chars
          • title string | null required

            Current job title per LinkedIn, e.g. "Chief Technology Officer".

            max 200 chars
          • company string | null required

            Current employer per LinkedIn. Distinct from the GitHub-sourced `organization` field, and the two disagree often — LinkedIn is usually the fresher of the two.

            max 200 chars
          • seniority string | null required

            A coarse seniority label from the LinkedIn overlay ("c-level", "senior", …). Free text from the source, not a Vamo enum; do not switch on the exact string.

            max 200 chars
          • expertise array of string required

            Self-declared skill tags from the LinkedIn profile. Claimed, not demonstrated — the demonstrated equivalent is the repositories under `repos` and `evidence`.

            max 25 items
      • garden object | null required

        The contribution garden and live GitHub stats. Null when GitHub declined the read.

        • counts object required

          Contribution counts as a sparse map: `YYYY-MM-DD` → contributions GitHub counted that day (commits to default branches, opened issues and pull requests, and reviews). A day inside the [from, to] window that is absent here had ZERO contributions — zero days are omitted on purpose.

        • from string required

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

          max 10 chars
        • to string required

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

          max 10 chars
        • total integer required

          Total contributions across `days`. Public activity only: work in private repositories is invisible here, so a low total is not evidence of a low output.

          min 0, max 1000000
        • fetchedAt string required

          When the garden was last read from GitHub, as an ISO 8601 instant. It can be older than your request.

          max 40 chars
        • liveStats object

          Live GitHub counts fetched alongside the calendar. Absent on older gardens.

          • followers integer required

            Current GitHub follower count, live.

            min 0, max 100000000
          • following integer required

            How many accounts they currently follow, live.

            min 0, max 100000000
          • totalStars integer required

            Sum of stargazers across the repositories this developer OWNS (`repos[].owned === true`), forks excluded, computed live. Stars on repositories they merely contribute to are NOT counted: those stars were earned by whoever built the project. Read this as "stars on their own work", never as their total reach. Never a provider-reported aggregate.

            min 0, max 100000000
          • repos array of object required

            Their attributed repositories as they exist right now — owned plus the org-owned projects they author commits and pull requests into, each flagged by `owned` — ordered by how much of the work is theirs, weighing their own commit count against the repository’s stars rather than stars alone, with a modest weight toward what they own. Same shape as the profile’s snapshot repos, so one renderer handles both.

            max 12 items
      • cells array of object required

        The facet cells held for this developer (`ai.person_summary`, `ai.repo_summaries`, `tags.repos`). Delivered cells only, so every one has status `ok`, and `ai.person_summary` is always among them.

        • developerId string required

          The developer this cell is about.

          max 64 chars
        • facetKey string required

          Which facet this cell answers.

        • status string required

          The outcome for this one (developer × facet) pair. Exactly one status is billed: `ok`. `ok` = delivered, `value` is populated, and you were charged for it (or you already owned it). `pending` = a background job is computing it; poll the report until it settles. Not charged now; the charge is settled by the job. `unavailable` = we ran and there is genuinely nothing to return for this developer, including the case where the source answered with an empty result. Not charged. `failed` = the attempt errored. Not charged, and never retried inside the same report. `report_required` = this facet needs a background report and this call does not start background work. Not charged; request it via `POST /v1/developers/reports` to get it. Treat every status other than `ok` as "no data", not as a value.

          okpendingunavailablefailedreport_required
        • value object

          The facet payload. Present only when `status` is `ok`; its shape is specific to the facet key, so read it against the facet you asked for. A cell whose payload came back with nothing in it is downgraded to `unavailable` rather than returned as an empty `ok`, so an `ok` cell always carries at least one real field.

        • jobId string

          The background compute job producing this cell. Present only when `status` is `pending`.

      • featuredRepos array of object required

        The repositories that put this developer on the list. Can be empty.

        • fullName string required

          The repository, as owner/name.

        • contributions number | null required

          How many contributions the developer made to it. Null when not counted.

        • trending boolean required

          Whether the repository is trending right now.

        • eliteStars30d number | null required

          Stars from highly ranked developers over the last 30 days. Null when not measured.

        • language string | null required

          The primary language. Null when unknown.

        • createdAt string | null required

          When the repository was created, as an ISO 8601 instant. Null when unknown.

        • description string | null required

          The repository's own GitHub description, verbatim. Null when it has none or it is not known. Present whether or not the repository is among the developer's own `developer.repos`.

        • stars number | null required

          The repository’s star count when the list was packaged. Null when not known.

        • summary string | null required

          A plain-English blurb on what the repository is, written by AI. Null when none is written yet.

        • tags array of string required

          Up to 5 technologies, then subjects, the repository is about. Empty when none are held.

      • highlight object | null required

        What the developer did in one of `featuredRepos`, and when. Null when they have no featured repository, or no merged pull request of theirs in it is on record. A developer is on the list either way.

        • text string required

          One or two sentences on what the developer did in the repository, and when.

        • repo string required

          The repository it is about, as owner/name. Always one of `featuredRepos`.

        • at string | null required

          When the most recent pull request it was written from merged, as an ISO 8601 instant. Null when that is not dated.

      • spotlight object | null required

        What the developer did in one of `featuredRepos` and what that repository is, written once and kept. Null when they have no featured repository, when nothing on record says what they did there, or until it has been written. A developer is on the list either way.

        • repo string required

          The repository it is about, as owner/name. Always one of `featuredRepos`.

        • text string required

          One or two short lines separated by a newline, each under 15 words, with no bullet marker and no closing full stop. Line 1 is what the developer did in the repository and names it. Line 2, when present, is what the repository is, in plain words.

    • requests array of object

      The `POST /v2/developers/search` bodies that find this list, in order, exactly as staff saved them. Send them yourself to get the same people. Present only on a list defined by search requests.

• 404 Discover lists are not enabled
  • 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_unavailabletrial_not_offeredcheckout_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.

• 429 A rate limit or a usage quota is exhausted. Back off and retry; the `x-quota-*` response headers report the remaining allowance.
  • 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_unavailabletrial_not_offeredcheckout_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.