Find people with natural language

POST

https://api.aventure.vc/v1/people/natural-search

POST

/v1/people/natural-search

$ curl -X POST https://api.aventure.vc/v1/people/natural-search \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "search": {
>     "query": "Companies founded in the last year that raised venture capital"
>   }
> }'

1 {
2   "interpretation": {
3     "confidence": "HIGH",
4     "execution": {
5       "modeRequested": "auto",
6       "modeUsed": "auto"
7     },
8     "fallbackUsed": true,
9     "filter": {
10       "arrayFilter": {
11         "amountInvestedRange": [
12           {
13             "max": 1.1,
14             "min": 1.1
15           }
16         ],
17         "amountRaisedRange": [
18           {
19             "max": 1.1,
20             "min": 1.1
21           }
22         ],
23         "entityName": [
24           "string"
25         ],
26         "investedCompany": [
27           "string"
28         ],
29         "personTitle": [
30           "string"
31         ],
32         "round": [
33           "string"
34         ],
35         "totalInvestmentCount": [
36           {
37             "max": 1,
38             "min": 1
39           }
40         ],
41         "typeRecord": [
42           "Company"
43         ]
44       },
45       "entityId": "string",
46       "entitySlug": "string",
47       "firstName": "string",
48       "includeAddress": true,
49       "includeUrl": true,
50       "investorActivity": {
51         "averageAmountInvestedUsdRange": [
52           {
53             "max": 1.1,
54             "min": 1.1
55           }
56         ],
57         "largestAmountInvestedUsdRange": [
58           {
59             "max": 1.1,
60             "min": 1.1
61           }
62         ],
63         "smallestAmountInvestedUsdRange": [
64           {
65             "max": 1.1,
66             "min": 1.1
67           }
68         ],
69         "totalAmountInvestedUsdRange": [
70           {
71             "max": 1.1,
72             "min": 1.1
73           }
74         ],
75         "totalInvestmentRange": [
76           {
77             "max": 1,
78             "min": 1
79           }
80         ]
81       },
82       "isCurrent": true,
83       "lastName": "string",
84       "letter": "A",
85       "role": "string",
86       "search": "AI",
87       "semanticQuery": "string",
88       "status": "string"
89     },
90     "interpretation": "string",
91     "sort": {
92       "order": [
93         {
94           "descending": true,
95           "field": "ID"
96         }
97       ]
98     },
99     "unsupported": "string"
100   },
101   "result": {
102     "content": [
103       {
104         "id": "string",
105         "image": {
106           "isMonogram": true,
107           "picture": "string"
108         },
109         "nameAlias": [
110           {
111             "name": "Bun",
112             "displayable": true,
113             "type": "nickname"
114           }
115         ],
116         "nameFull": "string",
117         "slug": "aventure-vc",
118         "source": {
119           "changedAt": "2024-01-15T09:30:00Z",
120           "dataSourceUpdatedAt": "2024-01-15T09:30:00Z",
121           "detail": "string",
122           "kind": "string",
123           "pendingApproval": 1,
124           "sourceId": "string",
125           "status": "string"
126         },
127         "text": {
128           "expanded": "Canonical expanded summary for grouped text assertions.",
129           "generatedDescription": "Acme AI builds AI copilots for growth teams.",
130           "short": "Canonical short summary"
131         },
132         "createdAt": "2024-01-15T09:30:00Z",
133         "gender": "string",
134         "lastModifiedAt": "2024-01-15T09:30:00Z",
135         "nameFirst": "string",
136         "nameLast": "string",
137         "nameMiddle": "string",
138         "nickname": "string",
139         "publicId": "pV1StGXR8Z5ab",
140         "semanticMatch": {
141           "computedAt": "2024-01-15T09:30:00Z",
142           "cosineDistance": 1.1,
143           "cosineScore": 1.1,
144           "modelVersion": "string",
145           "rank": 1,
146           "sourceHash": "string",
147           "sourceId": "string",
148           "sourceJson": "string",
149           "sourceText": "string",
150           "sourceType": "entity"
151         },
152         "suffix": "string",
153         "updatedAt": "2024-01-15T09:30:00Z"
154       }
155     ],
156     "number": 1,
157     "size": 1,
158     "totalElements": 1,
159     "totalPages": 1
160   }
161 }

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.

Authentication

AuthorizationBearer

User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

X-API-Keystring

Admin API key for system-to-system write operations

X-Client-Secretstring

Client secret for read-only service-to-service access (no writes)

Query parameters

permitMonogrambooleanOptional

When false, generated monogram pictures are stripped from person rows.

includePrivatebooleanOptional

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.

pageintegerOptional>=0Defaults to 0

Zero-based page index (0..N)

sizeintegerOptional>=1Defaults to 20

The size of the page to be returned

sortlist of stringsOptional

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Request

This endpoint expects an object.

searchobjectRequired

Canonical plain-English search request and strategy.

filterobjectOptional

Explicit people constraints. Caller-supplied fields override planner values; the planner fills only fields left at their canonical defaults.

Response

interpretationobject

Structured interpretation used to run the people query.

resultobject

Person page returned by the canonical person list engine.

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