Pagination and Filtering

The examples use GET /v1/entities with an API key in AUTH_TOKEN. Other list operations share the page fields, but their defaults and sortable fields differ; check each operation in the API reference.

Paging

Set size explicitly so page sizes stay predictable across API versions.

curl -H "Authorization: Bearer $AUTH_TOKEN" \
  "https://api.aventure.vc/v1/entities?page=2&size=50&sort=nameBrand,asc"

Sort order is ascending when you omit the direction, so sort=nameBrand and sort=nameBrand,asc are the same request.

Only some fields are sortable, and they are not the same set as the filter names. Sorting by a filter name such as entityName returns 422, and its detail lists every sortable property. POST /v1/search does not accept sort, because each record type in its response is ordered by relevance.

Reading the Page Object

Records are in content. The other fields tell you where you are:

{
  "content": [ ... ],
  "number": 2,
  "size": 50,
  "numberOfElements": 50,
  "totalElements": 12345,
  "totalPages": 247,
  "first": false,
  "last": false,
  "empty": false
}

Request pages until last is true instead of computing the final page index yourself, because totalElements can change between requests as records are added.

Filtering

Filters are query parameters. Most accept repetition, and repeating a filter means any of these:

# Companies headquartered in either country
curl -H "Authorization: Bearer $AUTH_TOKEN" \
  "https://api.aventure.vc/v1/entities?typeRecord=Company&headquartersCountry=US&headquartersCountry=CA"

Different filters must all match:

# Seed-stage companies headquartered in the US
curl -H "Authorization: Bearer $AUTH_TOKEN" \
  "https://api.aventure.vc/v1/entities?typeRecord=Company&stage=Seed&headquartersCountry=US"

GET /v1/entities accepts more than sixty filters. The main groups are:

• Identity: entityId, slug, entityName (exact match on the normalized name), url, urlDomain
• Classification: industry, mainProduct, typeModel, typeOwnership, typeCustomer, typeRecord, tag
• Location: headquartersCountry, headquartersState, headquartersCity
• Accelerator: acceleratorBrand, acceleratorName, acceleratorCohort, acceleratorStatus
• Funding: the fundraiseActivity.* parameters, covering round, amounts raised and invested, valuation, and last round year
• Ranges: yearFoundedRange, employeeCountRange, and the .min and .max parameters of createdAtRange and updatedAtRange
• Presence and quality: hasLogo, hasFundraising, operatingStatus, qualityGate

Location filters take full names, not postal abbreviations: headquartersState=Texas matches, and headquartersState=TX returns no records.

GET /v1/entities/filters lists each filter with its accepted values, so use it to discover what a classification filter accepts:

curl -H "Authorization: Bearer $AUTH_TOKEN" \
  "https://api.aventure.vc/v1/entities/filters?typeRecord=Company"

Keyword, Exact-Name, and Plain-English Search

Three inputs look similar and do different things:

• entityName matches the normalized brand or legal name exactly. Use it when you know the company’s name.
• textSearch runs keyword and full-text search across the record.
• POST /v1/search takes a plain-English request, turns it into filters, and searches companies, people, and news together. It requires a credential and a plan that includes search.

When the Query Outgrows a URL

A long filter set can exceed practical query-string limits. POST /v1/entities/search takes the same company filters as a JSON body and is still a read. It requires a credential. page, size, and sort stay in the query string, and its default size is 25. Its body also accepts semanticQuery, which matches on meaning instead of wording.

Counting Without Fetching

On POST /v1/entities/search, countOnly=true returns the number of matches in totalElements and returns no records. content is empty even when records match, so do not use empty to decide whether the query matched.