Knowledge Base

The SendSeven Knowledge Base is an AI-powered system that stores your organization's documents, FAQs, and website content. When queried, it uses retrieval-augmented generation (RAG) to find relevant information and generate accurate answers with source citations.

Required Scopes

Scope	Purpose
`knowledge_base:read`	Search and list documents and FAQ entries
`knowledge_base:create`	Create documents and folders
`knowledge_base:update`	Edit entries and resolve flags on FAQ entries
`knowledge_base:delete`	Delete documents; merge FAQ entries
`knowledge_base:admin`	Start and manage website crawls

Key Capabilities

AI-powered search -- ask natural language questions and receive synthesized answers
Document management -- upload text documents, FAQs, and files
Website crawling -- automatically import content from your website
Folder organization -- organize documents into folders (each folder becomes a separate search corpus)
Confidence scoring -- every answer includes a confidence score indicating reliability

Pricing

Knowledge base queries draw from the same monthly included pool as messages and campaign messages, and any overage is billed at the same per-unit rate:

Plan	Base fee	Included pool / month	Per KB query beyond the pool
Professional	EUR 79	2,500	EUR 0.020
Scale	EUR 199	10,000	EUR 0.015
Enterprise	EUR 499	40,000	EUR 0.010
API Only	EUR 9 per connected channel	1,000 per connected channel	EUR 0.005

There is no separate KB allowance — a message, a campaign send, and a KB query all draw down the same pool.

Knowledge Base is not included on Basic. On API Only the Knowledge Base UI is disabled, but the API documented below is fully usable and billed exactly as shown above.

Search the Knowledge Base

Ask a natural language question and receive an AI-generated answer with source references.

POST /api/v1/knowledge-base/search

Request Body

Field	Type	Required	Description
`query`	string	Yes	The question or search query
`limit`	integer	No	Max source documents to consider (default: 5, max: 20)
`folder_id`	string	No	Restrict search to a specific folder

curl

curl -X POST "https://api.sendseven.com/api/v1/knowledge-base/search" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is your return policy for electronics?",
    "limit": 5
  }'

Response

{
  "answer": "Our return policy for electronics allows returns within 30 days of purchase. Items must be in original packaging with all accessories included. Refunds are processed within 5-7 business days after we receive the returned item. For defective products, we offer free return shipping. For non-defective returns, a flat EUR 5 return shipping fee applies.",
  "confidence": 0.92,
  "sources": [
    {
      "id": "doc_return_policy",
      "title": "Return Policy - Electronics",
      "relevance": 0.95,
      "snippet": "Electronics may be returned within 30 days of purchase in original packaging..."
    },
    {
      "id": "doc_shipping_faq",
      "title": "Shipping & Returns FAQ",
      "relevance": 0.78,
      "snippet": "For defective products, we offer free return shipping..."
    }
  ],
  "tokens": {
    "input": 1250,
    "output": 180
  }
}

Confidence Scores

Range	Meaning	Recommended Action
0.70 -- 1.00	High confidence	Safe to present directly to customers
0.40 -- 0.69	Medium confidence	Review before presenting, may need clarification
0.00 -- 0.39	Low confidence	Answer may be incomplete or speculative

tip

Use the confidence score to decide how to present the answer. High-confidence answers can be sent directly to customers via your bot. Medium and low confidence answers should be routed to a human agent.

Python

import requests

BASE_URL = "https://api.sendseven.com/api/v1"
HEADERS = {
    "Authorization": "Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00",
    "Content-Type": "application/json",
}

result = requests.post(
    f"{BASE_URL}/knowledge-base/search",
    headers=HEADERS,
    json={"query": "How do I cancel my subscription?", "limit": 5},
).json()

print(f"Answer: {result['answer']}")
print(f"Confidence: {result['confidence']}")
for source in result["sources"]:
    print(f"  Source: {source['title']} (relevance: {source['relevance']})")

JavaScript

const BASE_URL = "https://api.sendseven.com/api/v1";
const HEADERS = {
  "Authorization": "Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00",
  "Content-Type": "application/json",
};

const response = await fetch(`${BASE_URL}/knowledge-base/search`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    query: "What payment methods do you accept?",
    limit: 3,
  }),
});
const result = await response.json();
console.log(`Answer (${Math.round(result.confidence * 100)}% confident):`);
console.log(result.answer);

Manage Documents

List Documents

GET /api/v1/knowledge-base/documents

Parameter	Type	Default	Description
`folder_id`	string		Filter by folder
`document_type`	string		Filter by document type (e.g. `faq`, `document`, `crawled`)
`search`	string		Search by title or source URL
`page`	integer	1	Page number
`page_size`	integer	20	Items per page (max 100)

curl -X GET "https://api.sendseven.com/api/v1/knowledge-base/documents?page=1&page_size=20" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json"

Create a Document

POST /api/v1/knowledge-base/documents

Field	Type	Required	Description
`title`	string	Yes	Document title
`type`	string	Yes	`faq` or `document`
`content`	string	Yes	Document content (plain text or HTML)
`folder_id`	string	No	Target folder ID

curl -X POST "https://api.sendseven.com/api/v1/knowledge-base/documents" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Warranty Information",
    "type": "document",
    "content": "All products sold by Acme Store come with a standard 12-month warranty. This warranty covers manufacturing defects and hardware failures under normal use.",
    "folder_id": "folder_policies"
  }'

Delete a Document

DELETE /api/v1/knowledge-base/documents/{document_id}

curl -X DELETE "https://api.sendseven.com/api/v1/knowledge-base/documents/doc_warranty_info" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"

Folders

Folders organize documents. Each folder acts as a separate search corpus, allowing targeted search with the folder_id parameter.

Create a Folder

POST /api/v1/knowledge-base/folders

curl -X POST "https://api.sendseven.com/api/v1/knowledge-base/folders" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Technical documentation and user guides for all products"
  }'

Website Crawl

Trigger a website crawl to automatically import content from a URL. Crawled pages land in the Websites system folder. Requires the knowledge_base:admin scope.

POST /api/v1/knowledge-base/documents/crawl

Field	Type	Required	Description
`url`	string	Yes	Starting URL to crawl
`follow_links`	boolean	No	Follow links and crawl multiple pages (default `true`). Set `false` to index only the single URL.
`page_limit`	integer	No	Maximum pages when `follow_links` is true (1–2000, default 200)
`max_depth`	integer	No	Maximum crawl depth when `follow_links` is true (1–10)
`title_prefix`	string	No	Prefix added to imported document titles (max 100 chars)
`rate_limit`	number	No	Seconds between requests (0.1–10.0)
`refresh`	boolean	No	Delete existing documents from this domain before crawling (default `false`)

curl -X POST "https://api.sendseven.com/api/v1/knowledge-base/documents/crawl" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.acme.com",
    "follow_links": true,
    "page_limit": 100,
    "max_depth": 3
  }'

{
  "job_id": "b3f1c2d4-5678-90ab-cdef-1234567890ab",
  "status": "queued",
  "message": "Website crawl job started. Use the poll_url to check progress.",
  "poll_url": "/api/v1/knowledge-base/documents/crawl/{job_id}/status"
}

info

Crawls run asynchronously. Poll GET /api/v1/knowledge-base/documents/crawl/{job_id}/status for progress, or watch it in the SendSeven dashboard under Knowledge Base.

FAQ Entries

FAQ entries are the curated question-and-answer pairs in the Managed FAQ folder — the answers an Assistant works from most directly. Unlike uploaded documents they follow a review lifecycle (draft → published → needs_review → archived), and only published entries are retrievable. For the concepts behind this, see the Knowledge Base for Bots guide.

List FAQ entries

GET /api/v1/knowledge-base/faq-entries

Parameter	Type	Description
`status`	string	`draft`, `published`, `needs_review`, or `archived`. Accepts a comma-separated list (e.g. `draft,needs_review`) for a union.
`origin`	string	`manual`, `auto_conversation`, `migrated`, or `correction`.
`folder_id`	string	Restrict to one KB folder.
`flagged_only`	boolean	Only entries with `flagged_count > 0`.
`review_only`	boolean	The review queue: entries needing attention (`draft`/`needs_review`, or flagged). Overrides `status`/`flagged_only`.
`search`	string	Substring match on question/answer.
`sort_by`	string	`uses`, `quality`, `flags`, `retrieved`, `created_at`, `updated_at`, or `sort_order`.
`page` / `page_size`	integer	Pagination (`page_size` max 200).

Each entry includes its status, origin, question, answer, and the usage counters times_in_sent_reply (Sent), times_retrieved (Retrieved), duplicate_count (Sources — a provenance count, not a duplicate warning), and flagged_count. rag_file_name is null when the entry is not indexed for retrieval.

{
  "items": [
    {
      "id": "faq_a1b2c3",
      "status": "published",
      "origin": "auto_conversation",
      "question": "What is your return policy?",
      "answer": "You can return any unused item within 30 days...",
      "times_in_sent_reply": 12,
      "times_retrieved": 47,
      "duplicate_count": 3,
      "flagged_count": 0,
      "rag_file_name": "faq_a1b2c3.md"
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 1 }
}

Review-queue count

Powers the review-queue badge. count is the number of distinct entries in the queue (the same set as ?review_only=true). The breakdown is not a partition — a flagged draft is counted under both draft and flagged, so the parts can sum to more than count.

GET /api/v1/knowledge-base/faq-entries/review-count

{
  "count": 42,
  "breakdown": { "draft": 40, "needs_review": 1, "flagged": 3 }
}

Resolve flags

Clears an entry's flags after a reviewer has looked at it: sets flagged_count to 0 and writes an audit revision, without touching the content, status, or the corpus. Requires knowledge_base:update.

POST /api/v1/knowledge-base/faq-entries/{entry_id}/resolve-flags

Editing or re-publishing an entry clears its flags automatically, so this endpoint is only needed when you want to keep an entry as-is and just dismiss its flags.

Find and merge duplicate entries

Duplicate clusters (live entries whose normalised question matches) are candidates for merging into one:

GET /api/v1/knowledge-base/faq-entries/duplicate-clusters

POST /api/v1/knowledge-base/faq-entries/merge

Field	Type	Default	Description
`winner_id`	string	—	The entry that survives the merge.
`loser_ids`	string[]	—	Entries folded into the winner, then archived.
`dry_run`	boolean	`true`	Preview only. Set `false` to execute the destructive merge.
`keep_loser_questions_as_variants`	boolean	`true`	Keep loser phrasings as retrievable alternate questions on the winner.

dry_run: true (the default) previews the merge — the combined stats, the question variants that would be kept, and the RAG files that would be removed — and changes nothing.

warning

Merge execution (dry_run: false) is gated off in production. While the server-side flag is disabled, an execute request returns 403 before anything is deleted — this is intentional, not a transient error. Until execution is enabled, use dry_run: true to preview, then consolidate by hand. Requires knowledge_base:delete.

Error Responses

Status	Error Code	Description
401	`INVALID_TOKEN`	Token is invalid or expired
403	`INSUFFICIENT_SCOPE`	Token lacks the required `knowledge_base:*` scope for this operation (see the scope table above). Also returned when merge execution is attempted while it is gated off.
404	`RESOURCE_NOT_FOUND`	Document or folder not found
422	`VALIDATION_ERROR`	Invalid request (e.g., URL not valid, content too large)

Next Steps

Send Text Messages -- send answers to customers
Webhook Events -- receive events when knowledge base is queried
Quick Reference -- more code examples

Required Scopes​

Key Capabilities​

Pricing​

Search the Knowledge Base​

Request Body​

curl​

Response​

Confidence Scores​

Python​

JavaScript​

Manage Documents​

List Documents​

Create a Document​

Delete a Document​

Folders​

Create a Folder​

Website Crawl​

FAQ Entries​

List FAQ entries​

Review-queue count​

Resolve flags​

Find and merge duplicate entries​

Error Responses​

Next Steps​