> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.aventure.vc/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aventure.vc/_mcp/server. # Find people with natural language POST https://api.aventure.vc/v1/people/natural-search Content-Type: application/json Translate a plain-English people search into the canonical PersonFilter contract, execute the existing people list engine, and return both the interpretation and ranked people page. Broad role and profile requests use person semantic search. Explicit filter fields are hard constraints: they override planner values, while the planner fills fields left unset. Reference: https://docs.aventure.vc/api-reference/a-venture-api/people/natural-search-people ## Authentication - `Authorization` header (bearer token, required) — User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key - `X-API-Key` header (required) — Admin API key for system-to-system write operations - `X-Client-Secret` header (required) — Client secret for read-only service-to-service access (no writes) ## Request ### Query parameters - `permitMonogram` (boolean, optional) — When false, generated monogram pictures are stripped from person rows. - `includePrivate` (boolean, optional) — Privileged admin readback scope. Includes hidden or off-sitemap people. Defaults to private for admin API key or ROLE_ADMIN callers; client-secret/client-read callers stay public. - `page` (integer, optional, default: 0) — Zero-based page index (0..N) - `size` (integer, optional, default: 20) — The size of the page to be returned - `sort` (list of string, optional) — Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported. ### Body (application/json) - `search` (object, required) — Canonical plain-English search request and strategy. - `query` (string, required) — Plain-English search request. - `mode` (enum, optional) — Search strategy to run. Accepted values narrow per surface: entity and person natural-search take every value (`exact` is entity-only); news and federated search accept only `auto` and `keyword`; content search accepts only `auto`. Defaults to `auto`, which keeps the server-chosen pipeline; any other value forces exactly that strategy. - Allowed values: `auto`, `exact`, `keyword`, `semantic`, `natural` - `model` (string, optional, nullable) — Optional chat model for planning; null uses the configured natural-search default. CLIENT_SECRET callers may only choose client-secret-eligible models; admin keys are unrestricted. - `filter` (object, optional) — Explicit people constraints. Caller-supplied fields override planner values; the planner fills only fields left at their canonical defaults. - `arrayFilter` (object, optional) — Array and range filters - `amountInvestedRange` (list of object, optional, nullable) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `amountRaisedRange` (list of object, optional, nullable) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `entityName` (list of string, optional, nullable) — Associated entity names. - `investedCompany` (list of string, optional, nullable) — Invested company names. - `personTitle` (list of string, optional, nullable) — Person titles. - `round` (list of string, optional, nullable) — Fundraise round labels. - `totalInvestmentCount` (list of object, optional, nullable) - `max` (integer, optional, nullable) — Inclusive maximum integer. - `min` (integer, optional, nullable) — Inclusive minimum integer. - `typeRecord` (list of enum, optional, nullable) — Associated entity type scope. Omit or use [] for any associated type. - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service` - `entityId` (string, optional, nullable) — Associated entity UUID. - `entitySlug` (string, optional, nullable) — Associated entity slug. - `firstName` (string, optional, nullable) — Person first name. - `includeAddress` (boolean, optional, nullable) — Include addresses on each person - `includeUrl` (boolean, optional, nullable) — Include URL links on each person - `investorActivity` (object, optional) — Aggregate investor activity filters. - `averageAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `largestAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `smallestAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `totalAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `totalInvestmentRange` (list of object, optional) - `max` (integer, optional, nullable) — Inclusive maximum integer. - `min` (integer, optional, nullable) — Inclusive minimum integer. - `isCurrent` (boolean, optional, nullable) — Filter current associations. - `lastName` (string, optional, nullable) — Person last name. - `letter` (string, optional, nullable) — First-name initial. - `role` (string, optional, nullable) — Associated entity role or title. - `search` (string, optional, nullable) — Search keyword or phrase. Single characters valid; stop words rejected. - `semanticQuery` (string, optional, nullable) — Semantic person search phrase. - `status` (string, optional, nullable) — Person workflow status. ## Response ### 200 OK - `interpretation` (object, required) — Structured interpretation used to run the people query. - `confidence` (enum, required) — Planner confidence in the structured interpretation. - Allowed values: `HIGH`, `MEDIUM`, `LOW` - `execution` (object, required) — Requested and executed search strategy. - `modeRequested` (enum, required) — Search mode requested by the caller. - Allowed values: `auto`, `exact`, `keyword`, `semantic`, `natural` - `modeUsed` (enum, required) — Search mode executed by the canonical engine. - Allowed values: `auto`, `exact`, `keyword`, `semantic`, `natural` - `fallbackUsed` (boolean, required) — True when the semantic fallback replaced an unconstrained planner result with a semantic search over the original query. - `filter` (object, required) — Canonical person filter generated from the natural-language query. - `arrayFilter` (object, optional) — Array and range filters - `amountInvestedRange` (list of object, optional, nullable) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `amountRaisedRange` (list of object, optional, nullable) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `entityName` (list of string, optional, nullable) — Associated entity names. - `investedCompany` (list of string, optional, nullable) — Invested company names. - `personTitle` (list of string, optional, nullable) — Person titles. - `round` (list of string, optional, nullable) — Fundraise round labels. - `totalInvestmentCount` (list of object, optional, nullable) - `max` (integer, optional, nullable) — Inclusive maximum integer. - `min` (integer, optional, nullable) — Inclusive minimum integer. - `typeRecord` (list of enum, optional, nullable) — Associated entity type scope. Omit or use [] for any associated type. - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service` - `entityId` (string, optional, nullable) — Associated entity UUID. - `entitySlug` (string, optional, nullable) — Associated entity slug. - `firstName` (string, optional, nullable) — Person first name. - `includeAddress` (boolean, optional, nullable) — Include addresses on each person - `includeUrl` (boolean, optional, nullable) — Include URL links on each person - `investorActivity` (object, optional) — Aggregate investor activity filters. - `averageAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `largestAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `smallestAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `totalAmountInvestedUsdRange` (list of object, optional) - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. - `totalInvestmentRange` (list of object, optional) - `max` (integer, optional, nullable) — Inclusive maximum integer. - `min` (integer, optional, nullable) — Inclusive minimum integer. - `isCurrent` (boolean, optional, nullable) — Filter current associations. - `lastName` (string, optional, nullable) — Person last name. - `letter` (string, optional, nullable) — First-name initial. - `role` (string, optional, nullable) — Associated entity role or title. - `search` (string, optional, nullable) — Search keyword or phrase. Single characters valid; stop words rejected. - `semanticQuery` (string, optional, nullable) — Semantic person search phrase. - `status` (string, optional, nullable) — Person workflow status. - `interpretation` (string, required) — Human-readable summary of how the query was interpreted. - `sort` (object, required) — Sort applied to the result page. Empty when the page was ordered by semantic relevance rank instead of a sortable column. - `order` (list of object, required) — Ordered sort terms. Empty list means unspecified at the HTTP boundary (defaults apply). - `descending` (boolean, required) — true for descending (DESC), false for ascending (ASC) - `field` (enum, required) — Sort field for this resource (entity list uses EntityFilter.Sortable / published sort keys). - Allowed values: `ID`, `FIRST_NAME`, `LAST_NAME`, `FULL_NAME`, `SLUG`, `CREATED_AT`, `UPDATED_AT`, `STATUS`, `GENDER`, `AMOUNT_INVESTED`, `TOTAL_INVESTMENTS` - `unsupported` (string, optional, nullable) — Constraint the planner could not translate into the canonical PersonFilter contract; null when every material constraint was supported. - `result` (object, required) — Person page returned by the canonical person list engine. - `content` (list of object, required) - `id` (string, required) — Canonical person UUID - `image` (object, required) — Read projection: person image fields for detail/list responses - `isMonogram` (boolean, required) — Whether person image monogram - `picture` (string, optional, nullable) - `nameAlias` (list of object, required) — Display and search aliases for this person - `name` (string, required) — Alternate name text - `displayable` (boolean, optional, nullable) — Show this alias in public name displays. - `type` (enum, optional, nullable) — Alias type classification - Allowed values: `nickname`, `maidenName`, `formerName`, `stageName` - `nameFull` (string, required) - `slug` (string, required) — Canonical lowercase URL slug for the resource - `source` (object, required) — Grouped source/provenance metadata for private v1 response fields - `changedAt` (datetime, optional, nullable) - `dataSourceUpdatedAt` (datetime, optional, nullable) - `detail` (string, optional, nullable) - `kind` (string, optional, nullable) - `pendingApproval` (integer, optional, nullable) - `sourceId` (string, optional, nullable) - `status` (string, optional, nullable) - `text` (object, required) — Grouped person text content - `expanded` (string, optional, nullable) — Expanded summary text - `generatedDescription` (string, optional, nullable) — Generated SEO meta description text - `short` (string, optional, nullable) — Short summary text - `createdAt` (datetime, optional, nullable) — Record creation timestamp - `gender` (string, optional, nullable) - `lastModifiedAt` (datetime, optional, nullable) — Provenance-grounded last-modified watermark (schema.org dateModified): the latest effective time across all writes attributed to this person. - `nameFirst` (string, optional, nullable) - `nameLast` (string, optional, nullable) - `nameMiddle` (string, optional, nullable) - `nickname` (string, optional, nullable) - `publicId` (string, optional, nullable) — Stable, immutable public handle (e.g. `pV1StGXR8Z5ab`). Never changes once assigned, unlike the slug. Null on projections that do not select it and on rows still awaiting handle backfill. - `semanticMatch` (object, optional, nullable) — Semantic embedding match evidence populated only for semantic people reads. - `computedAt` (datetime, required) — Timestamp when the embedding row was computed. - `cosineDistance` (double, required) — pgvector cosine distance where lower is closer. - `cosineScore` (double, required) — Cosine similarity score where higher is closer. - `modelVersion` (string, required) — Embedding model/profile version for this row. - `rank` (integer, required) — One-based semantic rank within the returned ANN candidate set. - `sourceHash` (string, required) — SHA-256 hash of the source content. - `sourceId` (string, required) — Content embedding source identifier. - `sourceJson` (string, required) — Serialized JSONB source document stored for the embedding row. - `sourceText` (string, required) — Source text used to compute the stored embedding. - `sourceType` (enum, required) — Stored content embedding source partition. - Allowed values: `entity`, `person`, `newsArticle`, `blogPost`, `text`, `classificationTag`, `classificationCode`, `product`, `service`, `agentHelpDoc` - `suffix` (string, optional, nullable) - `updatedAt` (datetime, optional, nullable) — Last modification timestamp - `number` (integer, required) - `size` (integer, required) - `totalElements` (long, required) - `totalPages` (integer, required) ## Examples **Request** ```json { "search": { "query": "Companies founded in the last year that raised venture capital" } } ``` **Response** ```json { "interpretation": { "confidence": "HIGH", "execution": { "modeRequested": "auto", "modeUsed": "auto" }, "fallbackUsed": true, "filter": { "arrayFilter": { "amountInvestedRange": [ { "max": 1.1, "min": 1.1 } ], "amountRaisedRange": [ { "max": 1.1, "min": 1.1 } ], "entityName": [ "string" ], "investedCompany": [ "string" ], "personTitle": [ "string" ], "round": [ "string" ], "totalInvestmentCount": [ { "max": 1, "min": 1 } ], "typeRecord": [ "Company" ] }, "entityId": "string", "entitySlug": "string", "firstName": "string", "includeAddress": true, "includeUrl": true, "investorActivity": { "averageAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "largestAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "smallestAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "totalAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "totalInvestmentRange": [ { "max": 1, "min": 1 } ] }, "isCurrent": true, "lastName": "string", "letter": "A", "role": "string", "search": "AI", "semanticQuery": "string", "status": "string" }, "interpretation": "string", "sort": { "order": [ { "descending": true, "field": "ID" } ] }, "unsupported": "string" }, "result": { "content": [ { "id": "string", "image": { "isMonogram": true, "picture": "string" }, "nameAlias": [ { "name": "Bun", "displayable": true, "type": "nickname" } ], "nameFull": "string", "slug": "aventure-vc", "source": { "changedAt": "2024-01-15T09:30:00Z", "dataSourceUpdatedAt": "2024-01-15T09:30:00Z", "detail": "string", "kind": "string", "pendingApproval": 1, "sourceId": "string", "status": "string" }, "text": { "expanded": "Canonical expanded summary for grouped text assertions.", "generatedDescription": "Acme AI builds AI copilots for growth teams.", "short": "Canonical short summary" }, "createdAt": "2024-01-15T09:30:00Z", "gender": "string", "lastModifiedAt": "2024-01-15T09:30:00Z", "nameFirst": "string", "nameLast": "string", "nameMiddle": "string", "nickname": "string", "publicId": "pV1StGXR8Z5ab", "semanticMatch": { "computedAt": "2024-01-15T09:30:00Z", "cosineDistance": 1.1, "cosineScore": 1.1, "modelVersion": "string", "rank": 1, "sourceHash": "string", "sourceId": "string", "sourceJson": "string", "sourceText": "string", "sourceType": "entity" }, "suffix": "string", "updatedAt": "2024-01-15T09:30:00Z" } ], "number": 1, "size": 1, "totalElements": 1, "totalPages": 1 } } ``` **SDK Code** ```python import requests url = "https://api.aventure.vc/v1/people/natural-search" payload = { "search": { "query": "Companies founded in the last year that raised venture capital" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.aventure.vc/v1/people/natural-search'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"search":{"query":"Companies founded in the last year that raised venture capital"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.aventure.vc/v1/people/natural-search" payload := strings.NewReader("{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.aventure.vc/v1/people/natural-search") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.aventure.vc/v1/people/natural-search") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.aventure.vc/v1/people/natural-search', [ 'body' => '{ "search": { "query": "Companies founded in the last year that raised venture capital" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.aventure.vc/v1/people/natural-search"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["search": ["query": "Companies founded in the last year that raised venture capital"]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/people/natural-search")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```