Knowledge retrieval

Search the agent knowledge base and use the grounded flag to gate answers.

Request

curl -X POST https://app.humaner.io/api/v1/intelligence/retrieve \
  -H "Authorization: Bearer hm_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_PUBLIC_ID",
    "query": "How do I reset my password?"
  }'

Use the grounded flag

Retrieval returns chunks plus a grounded flag. Grounded means the knowledge base actually covers the question. Ungrounded means you should not improvise — either say you cannot help or open a ticket.

const { chunks, grounded } = await retrieve(query);

if (!grounded) {
  // Do not let the model fill the gap. Escalate instead.
  return createTicket({ summary: query, transcript });
}

return answerWith(chunks);

This is where hallucinations get stopped

Most Custom integrations that feel unreliable ignore grounded and let the model answer anyway. Gate on it.

Filling the knowledge base

Knowledge lives in the dashboard under Agent → Knowledge, the same as Cloud. Add sitemaps, URLs, files, or text. Auto-training and rescan schedules apply on Custom too.

Markdown

Best for retrieval

Website

Crawl + refresh

Files

PDF / DOCX

Topics

Inline FAQs

Desk

Resolved tickets