Search the live web

POST

https://api.aventure.vc/v1/search/web

POST

/v1/search/web

$ curl -X POST https://api.aventure.vc/v1/search/web \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "search": "OpenAI latest funding news"
> }'

1 {
2   "document": {
3     "cacheHitCount": 1,
4     "createdAt": "2024-01-15T09:30:00Z",
5     "documentType": "string",
6     "id": "string",
7     "provider": "string",
8     "sourceKey": "string",
9     "expiresAt": "2024-01-15T09:30:00Z",
10     "httpStatus": 1,
11     "lastAccessedAt": "2024-01-15T09:30:00Z",
12     "providerRequestId": "string",
13     "rawByteCount": 1,
14     "rawCharset": "string",
15     "rawMediaType": "string",
16     "upstreamContentEncoding": "string"
17   },
18   "result": [
19     {
20       "relevanceScore": 1.1,
21       "snippet": "string",
22       "title": "string",
23       "url": "string"
24     }
25   ],
26   "search": {
27     "search": "OpenAI latest funding news",
28     "bypassCache": false,
29     "cacheKey": "OpenAI",
30     "language": "en",
31     "region": "us",
32     "resultLimit": 5,
33     "source": "string"
34   }
35 }

Runs a live web search through SerpAPI, returns a stored result when a fresh version exists, and durably records fresh results in the source-document store.

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)

Request

This endpoint expects an object.

searchstringRequired

Search text sent to the upstream web search provider

bypassCachebooleanOptionalDefaults to false

Skip cache lookup and refresh from the search provider

cacheKeystring or nullOptional

Stable lookup text for cache keying when generated search text varies between runs

languagestring or nullOptional

Search language code

regionstring or nullOptional

Search region code

resultLimitinteger or nullOptional

Maximum number of normalized results to keep

sourcestring or nullOptional<=64 characters

Optional caller identity for source-document attribution and abuse triage. Any non-blank string up to 64 characters is accepted and persisted with the resolved request context.

Response

documentobject

Source-document ledger row backing this result

resultlist of objects

Normalized result items in provider rank order

searchobject

Web search request represented by this result

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