aVenture APIEntities V1

Review entity duplicate gates

View as Markdown

Review duplicate candidates before entity create or update using slug, names, URLs, or domains. Empty results are not proof no entity exists; 409 create responses remain authoritative. Use entity detail for exact lookups and entity list for browsing.

Authentication

X-Client-Secretstring

Client secret for read-only service-to-service access (no writes)

Query parameters

pageintegerOptional

Zero-based page index (0..N)

sizeintegerOptional

The size of the page to be returned; duplicate-check default 10, maximum 100.

sortlist of stringsOptional
Sorting is not supported
includePrivatebooleanOptional

Privileged read scope for admin callers. Bypasses the public visibility filter so hidden, unverified, and not-yet-published records are returned instead of being silently dropped. Defaults to private for admin API key or ROLE_ADMIN callers; client-secret/client-read callers stay public.

Request

This endpoint expects an object.
excludeIdstring or nullOptionalformat: "uuid"

Entity id to exclude from duplicate candidates; not a lookup id

locationstring or nullOptional
Location
nameAnystring or nullOptional
Loose name match
nameBrandstring or nullOptional
Brand name
nameLegalstring or nullOptional
Legal name
productServiceProviderIdstring or nullOptionalformat: "uuid"

Provider entity UUID that scopes Product/Service duplicate candidates to that provider’s current productService catalog, including hidden rows. Product and Service slugs are provider-pair scoped, so cross-provider name reuse is not a duplicate; supply this id to review the one catalog that can collide.

qwen4bFp16Embeddinglist of float or nullOptional

Embedding vector pinned to qwen-4b-fp16 (Qwen3-Embedding-4B-f16.gguf) from https://huggingface.co/Qwen/Qwen3-Embedding-4B-GGUF?show_file_info=Qwen3-Embedding-4B-f16.gguf; only this fp16 model is accepted and exactly 2560 floats are required

slugstring or nullOptional

URL-safe identifier

typeRecordenum or nullOptional
Entity type
urlstring or nullOptional
Joined entity URL
urlCandidatelist of objectsOptional
Additional URL candidates to match
urlDomainstring or nullOptional
URL domain match
urlMatchModeenum or nullOptional
URL match mode
urlStrictnessenum or nullOptional
Optional URL match strictness. Omit for strict matching. Send loose or any only when the caller intentionally widens URL matching.
urlTypeenum or nullOptional
URL type

Response

OK
contentlist of objectsOptional
emptybooleanOptional
firstbooleanOptional
lastbooleanOptional
numberintegerOptional
numberOfElementsintegerOptional
pageableobjectOptional
sizeintegerOptional
sortobjectOptional
totalElementslongOptional
totalPagesintegerOptional

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