Resource

Knowledge Base

Each tenant has one or more knowledge bases. Voice agents retrieve relevant chunks during conversations. Add or remove documents headlessly via the API; ingestion is async (chunks + embeds via Voyage).

Tenancy

Agency keys see all KBs in the org by default. Pass X-Gary-Client-Id to scope to one client. Client-bound keys (cl_live_…) only see their own client's KBs.

List knowledge bases#

List active knowledge bases for your tenant

GET/v1/kb

Request

curl https://agency.gary.club/api/public/v1/kb \
  -H "Authorization: Bearer gc_live_EXAMPLE_AbCdEfGhIj0123456789"

List documents in a KB#

Documents in a knowledge base

GET/v1/kb/{id}/documents

Cursor-paginated. Each row exposes title, source_type, byte_size, char_count, chunk_count, status (pending → ready / failed), and credits_charged.

Path parameters

iduuidrequired

Knowledge base id.

Query parameters

limitintegerdefault: 50

page_tokenstring

Add a document#

Add a manual / URL / uploaded document

POST/v1/kb/{id}/documents

Inserts the row in pending status and kicks off the backend ingestion worker (chunks + embeds via Voyage). The doc becomes searchable once status flips to ready.

Path parameters

iduuidrequired

Knowledge base id.

Body parameters

titlestring

Required. ≤200 chars.

source_typestring

Required. manual, url, or upload.

contentstring

Required when source_type=manual. Up to 200,000 chars.

source_urlstring

Required when source_type=url. Must be http(s).

storage_pathstring

Required when source_type=upload. Must be an R2 URL under your org's kb-uploads/<org-id>/ prefix (presigned via the dashboard).

mime_typestring

Optional metadata for upload sources.

byte_sizeinteger

Optional size hint for upload sources.

Request

curl -X POST \
  https://agency.gary.club/api/public/v1/kb/kb_EXAMPLE_aaaa/documents \
  -H "Authorization: Bearer gc_live_EXAMPLE_AbCdEfGhIj0123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Spring promo terms",
    "source_type": "manual",
    "content": "10% off any service booked between Apr 28 and May 12. ..."
  }'

Response

{
  "document": {
    "id": "kbdoc_EXAMPLE_aaaa",
    "kb_id": "kb_EXAMPLE_aaaa",
    "title": "Spring promo terms",
    "source_type": "manual",
    "source_url": null,
    "mime_type": null,
    "byte_size": null,
    "status": "pending",
    "created_at": "2026-04-28T01:18:53.000Z"
  }
}

Read a document#

Single document with ingestion status

GET/v1/kb/{id}/documents/{docId}

Includes char_count, chunk_count, error_message (when status=failed), and credits_charged.

Path parameters

iduuidrequired

KB id.

docIduuidrequired

Document id.

Soft-delete a document#

Soft-delete a KB document

DELETE/v1/kb/{id}/documents/{docId}

Sets status='deleted'. Chunks are removed asynchronously by the cleanup cron. R2 source files are NOT removed by this call — they age out via a separate retention sweep.

Path parameters

iduuidrequired

KB id.

docIduuidrequired

Document id.

Webhooks for KB#

kb.document.ready — ingestion finished, doc is searchable.
kb.document.failed — ingestion failed, see error_message.

Future — async Q&A#

POST /v1/ai/kb/answer (sync RAG retrieval, FUEL-metered, returns answer + citation chunks) is on the roadmap. For now, agents query KBs internally during voice calls — the public-API surface is read + write, not query.