Enrichment and facets

Search and lookup return each developer at a depth: core by default, which is the identity, GitHub profile, top repositories and devRank. That is enough to decide whether you care. Everything beyond it is a facet, which you ask for by name.

Most people in a search are not the person you want, so the useful pattern is to search at core, keep the few that fit, and add depth only to those.

The /v1/developers routes still work and are deprecated. Use /v2/developers.

Depth tiers and facets

core: profile, repositories, devRank.
enriched: adds LinkedIn identity and socials.
deep: adds the contribution garden.

A facet is one fact about one developer: contact details, activity signals, grades, generated summaries. GET /v1/pricing/catalog lists every facet, what it gives you, and which other facets it depends on. Two properties matter when you plan a request:

requires names facets this one depends on.
requiresReport marks a facet that must be computed rather than read from cache, which means it comes back through a report.

The ways to ask

1. With a search. POST /v2/developers/search and POST /v2/developers/similar take depth and up to five facets. Every developer in results comes back at that depth, with facets under details.

2. With a lookup. POST /v2/developers takes logins, linkedin or ids, plus depth or facets, and returns whatever is already held. This call never starts a computation. A facet that would have to be computed comes back marked report_required.

3. For developers you already hold. GET /v2/developers/enrich?ids=...&depth=enriched deepens rows you took at core without running the search again. It takes up to 25 comma separated ids or logins.

4. Emails. GET /v2/developers/emails?ids=... gets every address we observe for each developer, under details.contact.emails. A developer we hold no address for comes back without it.

5. Summaries. GET /v2/developers/summaries?ids=... returns ai.person_summary and ai.repo_summaries under details. A summary that is not written yet comes back pending; read the same id again to collect it.

6. As a durable report. POST /v2/developers/reports requests facets that must be computed, such as dossiers. It returns a reportId immediately; poll GET /v2/developers/reports/{reportId} until its status is ready.

The rule of thumb: if POST /v2/developers hands you report_required, move that request to POST /v2/developers/reports.

Worked example

Find people, keep a few, add depth only to those.

# 1. Search at core.
curl -X POST https://api.vamotalent.ai/v2/developers/search \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"filters": ["location_ids", "ContainsAny", {"place": ["Berlin"]}], "rank_by": ["v", "ANN", ["Embed", "Rust systems programming"]], "limit": 50}'

# 2. Get emails for the ones you kept (their results[].id values).
curl 'https://api.vamotalent.ai/v2/developers/emails?ids=...' \
  -H "Authorization: Bearer vamo_sk_..."

# 3. Request computed facets as a report, then poll it.
curl -X POST https://api.vamotalent.ai/v2/developers/reports \
  -H "Authorization: Bearer vamo_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"developerIds": ["..."], "facets": ["dossier.core"]}'

Every field name above is in the reference, which is generated from the API and is the thing to trust.