For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Returns status MATCHED, NO_MATCH, or NEEDS_REVIEW. MATCHED: match.record.id is the person; read their detail with people get --person-id. NO_MATCH: no record you can see is this person; create them. NEEDS_REVIEW: show candidate (most probable first) to the user and ask which one it is or whether the person is new; never create on NEEDS_REVIEW. stage names the step that settled it: DETERMINISTIC (URL proof, no model call), JUDGMENT (decision model), or WEB_EVIDENCE (added a web search). Send their LinkedIn or personal URL whenever you have it, and employer and title as context; the same name at a different employer is a different person. For the full detail of an exact slug or URL use people lookup get. Example: people lookup --name "Jane Doe" --context "CEO at Acme AI". Output: --text (default) is compact text, --json the full envelope, --data the Identification object for scripts.
Authentication
AuthorizationBearer
User bearer token: Clerk session JWT, Clerk OAuth access token, or Clerk API key
Query parameters
includePrivatebooleanOptional
Also considers hidden and unpublished records; needs private-visibility authority. Without it, NO_MATCH covers only records you can see.
Request
This endpoint expects an object.
namestringRequired0-200 characters
Name exactly as the source writes it, such as Acme AI or Jane Doe.
contextstring or nullOptional0-2000 characters
Specific facts in plain words: product, industry, employer and title, or founder names. Generic words like startup add nothing.
locationstring or nullOptional0-2000 characters
City, region, or country, such as Austin, TX. Tells namesakes apart; not proof on its own.
sourceNewsIdinteger or nullOptional
aVenture news id of the article that mentions the subject; an unknown id is a 400.
sourceUrlstring or nullOptional0-2000 characters
URL of the article that mentions the subject; read from aVenture news when stored there, otherwise fetched.
urllist of stringsOptional
URLs the subject owns: its website, its LinkedIn company or person profile, or a registry page. At most 10. Put articles in sourceUrl.
Response headers
X-RateLimit-Limitinteger
Requests allowed per client IP in the current rate-limit window.
X-RateLimit-Remaininginteger
Requests left before the tightest applicable rate-limit bucket rejects.
X-RateLimit-Resetinteger
Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.
Response
The identification as canonical JSON or compact text/plain.
candidatelist of objects
Records considered, most probable first.
detailstring
One sentence naming what settled the answer or what the user must decide.
stageenum
The ladder step that settled the answer.
Allowed values:
statusenum
What the caller does next: act on match, create, or ask the user.
Allowed values:
matchobject or nullOptional
The matched record when status is MATCHED.
officialUrlstring or nullOptional
The subject's own website or profile page found in web search. Use it as the website when creating the record only if it is the subject's own domain, not a LinkedIn, Crunchbase, or other profile page.
Errors
400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
Returns status MATCHED, NO_MATCH, or NEEDS_REVIEW. MATCHED: match.record.id is the person; read their detail with people get —person-id. NO_MATCH: no record you can see is this person; create them. NEEDS_REVIEW: show candidate (most probable first) to the user and ask which one it is or whether the person is new; never create on NEEDS_REVIEW. stage names the step that settled it: DETERMINISTIC (URL proof, no model call), JUDGMENT (decision model), or WEB_EVIDENCE (added a web search). Send their LinkedIn or personal URL whenever you have it, and employer and title as context; the same name at a different employer is a different person. For the full detail of an exact slug or URL use people lookup get. Example: people lookup —name “Jane Doe” —context “CEO at Acme AI”. Output: —text (default) is compact text, —json the full envelope, —data the Identification object for scripts.
