aVenture APIAddresses

Batch directory + companies payload

View as Markdown
Fetch the location directory, exact letter counts, and optional company URL slots in one request.

Authentication

AuthorizationBearer

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

Query parameters

pageintegerOptional>=0Defaults to 0

Zero-based page index (0..N)

sizeintegerOptional>=1Defaults to 100
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.
letterstringRequired
scopeenumRequired
Accepted location scope tokens for path and batch inputs
cursorstring or nullOptional

Opaque continuation from companyNextCursor; keeps deep company traversal keyset-based.

slugstring or nullOptional

Response headers

X-RateLimit-Limitinteger

Requests allowed per client IP in the current rate-limit window.

X-RateLimit-Remaininginteger

Requests left before the tightest applicable rate-limit bucket rejects.

X-RateLimit-Resetinteger

Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.

Response

The slug resolves to a publishable location: the body carries the directory, exact letter counts, and the requested company URL slots.

directoryobject
directoryLetterCountmap from strings to longs
requestedLetterstring
resolvedDirectoryLetterstring
scopestring
companyobject or nullOptional
companyNextCursorstring or nullOptional

Opaque continuation for the next company URL-slot page; absent only when the current address-refresh snapshot holds no further slot for the resolved letter.

locationobject or nullOptional

Single directory entry (country/state/city) for sitemap

locationLetterCountmap from strings to longs or nullOptional

Exact company URL-slot count per letter from the same address-refresh snapshot that serves company: locationLetterCount[letter] equals the slots a companyNextCursor traversal of that letter reaches. Both move together at the next refresh, so a traversal that straddles a refresh restarts from a fresh count.

resolvedLocationLetterstring or nullOptional
slugResolutionobject or nullOptional
Slug resolution pair for sitemap hydration

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
410
Gone Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error