Search a person's publications

POST

https://api.aventure.vc/v1/people/:personId/content/search

POST

/v1/people/:personId/content/search

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

{
  "interpretation": {
    "confidence": "HIGH",
    "filter": {
      "contentType": "newsArticle",
      "relation": "by",
      "topic": "string",
      "year": 1
    },
    "interpretation": "string",
    "sort": {
      "order": [
        {
          "descending": true,
          "field": "CONTENT_ID"
        }
      ]
    },
    "unsupported": "string"
  },
  "result": {
    "content": [
      {
        "contentId": "string",
        "contentType": "newsArticle",
        "title": "string",
        "canonicalUrl": "string",
        "createdAt": "2024-01-15T09:30:00Z",
        "publishedAt": "2024-01-15T09:30:00Z",
        "relation": "by",
        "sourceDomain": "string",
        "sourceName": "string",
        "summary": "string",
        "topic": "string",
        "updatedAt": "2024-01-15T09:30:00Z",
        "url": "string",
        "year": 1
      }
    ],
    "number": 1,
    "size": 1,
    "totalElements": 1,
    "totalPages": 1
  }
}

Translates plain-English constraints for one person’s content index. Bearer access requires ROLE_ADMIN or ROLE_CLIENT.

Authentication

AuthorizationBearer

User bearer token: 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

personIdstringRequiredformat: "uuid"

Person UUID whose publications are 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. Defaults to auto: the fast name layer runs first (a single-token query as keyword search, a multiword query as an exact normalized name) and the language-model planner runs only on a miss, so name lookups never pay for planning. Any other value forces exactly that strategy: exact and keyword skip planner model resolution and its rate limit. Entity and person natural-search take every value; news and federated search accept only auto and keyword; content search accepts only auto.

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

Publication 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