Retrieval
This capability is granted by an API key scoped to the ai-suite product (product face). See the product reference below.
Hybrid retrieval as a shared capability — dense (ollama embeddings) + lexical + rerank over a durable pgvector store; per-org ingest + query. Consumers: dialog-core's RAG (C7 split) + vagary-platform's migrated vector-search (D5, post-D-3 pgvector) = ≥2. INTERNAL (D-4). Not a clean cut — a shared LIVE dependency the ARCG rides; changes are staged + the org-brain deployment is convergence-owned.
- Group: Voice & AI
- Contract:
contracts/retrieval/v1/openapi.yaml - Public base:
https://api.vagarylabs.com(the consolidated API gateway — one host, per-brand siblingapi.<zone>) - Auth: a product API key (
vgk_…) issued from the console —Authorization: Bearer vgk_… - Product face (customer-keyed):
https://api.vagarylabs.com/product/v1/retrieval/search
- Capability face (internal first-party — NOT customer-keyed):
https://api.vagarylabs.com/v1/retrievehttps://api.vagarylabs.com/v1/ingest
Endpoints
| Method | Path | Summary |
|---|---|---|
POST | /retrieve | Hybrid retrieve (dense+lexical+rerank) for an org's corpus |
POST | /ingest | Synchronous ingest of documents into an org's corpus (embedded to pgvector) |
POST | /delete | Retire a KB source's documents for an org (managed-KB, Row10c) |
GET | /stats | corpus + index stats per org |
GET | /health | liveness (recaller SLO-gated) |
GET | /metrics | Prometheus |
Product face
The external, paying-customer surface served by the edge at /product/v1/* (contracts/retrieval/product/v1/openapi.yaml).
| Method | Path | Summary |
|---|---|---|
POST | /search | Search your org's corpus (managed, metered) — wraps the capability's hybrid retrieve |
Schemas
RetrieveRequest
| Field | Type | Description |
|---|---|---|
organization_id | string | |
query | string | |
top_k | integer | |
rerank | boolean | |
hybrid | boolean | dense+lexical (default true) |
include_citations | boolean | managed-KB (Row10c): add a citation object per result, derived from kb_* metadata. Default false; additive (sealed result shape unchanged when absent). |
RetrieveResponse
| Field | Type | Description |
|---|---|---|
results | array |
Citation
| Field | Type | Description |
|---|---|---|
title | string | |
url | string | |
source_id | string | |
source_type | string | doc |
published_at | string |
DeleteRequest
| Field | Type | Description |
|---|---|---|
organization_id | string | |
source_id | string | delete every KB doc ingested from this source (kb_source_id) |
DeleteResponse
| Field | Type | Description |
|---|---|---|
deleted | integer | |
organization_id | string | |
source_id | string |
IngestRequest
| Field | Type | Description |
|---|---|---|
organization_id | string | |
documents | array |
IngestResponse
| Field | Type | Description |
|---|---|---|
ingested | integer | documents embedded + upserted this call |
organization_id | string | product-tier tenant (I6) |
ids | array | stored document ids (client-supplied or generated) |
Error
| Field | Type | Description |
|---|---|---|
error | string |
Generated by scripts/gen-capability-docs.py from contracts/retrieval/v1/openapi.yaml — the contract IS the source of truth; edit the contract, not this page.