Search entity content

POST

https://api.aventure.vc/v1/entities/:entityId/content/search

POST

/v1/entities/:entityId/content/search

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

1 {
2   "interpretation": {
3     "confidence": "HIGH",
4     "filter": {
5       "contentType": "newsArticle",
6       "relation": "by",
7       "topic": "string",
8       "year": 1
9     },
10     "interpretation": "string",
11     "sort": {
12       "order": [
13         {
14           "descending": true,
15           "field": "CONTENT_ID"
16         }
17       ]
18     },
19     "unsupported": "string"
20   },
21   "result": {
22     "content": [
23       {
24         "contentId": "string",
25         "contentType": "newsArticle",
26         "title": "string",
27         "canonicalUrl": "string",
28         "createdAt": "2024-01-15T09:30:00Z",
29         "publishedAt": "2024-01-15T09:30:00Z",
30         "relation": "by",
31         "sourceDomain": "string",
32         "sourceName": "string",
33         "summary": "string",
34         "topic": "string",
35         "updatedAt": "2024-01-15T09:30:00Z",
36         "url": "string",
37         "year": 1
38       }
39     ],
40     "number": 1,
41     "size": 1,
42     "totalElements": 1,
43     "totalPages": 1
44   }
45 }

Translates plain-English constraints for one entity’s content index.

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)

Path parameters

entityIdstringRequiredformat: "uuid"

Entity UUID whose content is searched.

Query parameters

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.

querystringRequired>=1 character

Plain-English search request.

modeenumOptional

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.

modelstring or nullOptional

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.

Response

interpretationobject

Structured interpretation used to run the content query.

resultobject

Content page.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found 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