Knowledge Bases

The knowledge base object

{
  "public_id":            "kb_00000001",
  "name":                 "Product FAQ",
  "description":          "Common product questions",
  "status":               "active",
  "source_url":           "https://help.yourcompany.com",
  "crawl_frequency":      "weekly",
  "auto_refresh_enabled": true,
  "last_crawled_at":      "2026-01-14T06:00:00Z",
  "last_refresh_status":  "idle",
  "max_depth":            3,
  "max_pages":            100,
  "entry_count":          247,
  "created_at":           "2026-01-01T00:00:00Z",
  "updated_at":           "2026-01-14T06:01:00Z"
}

curl -X POST https://api.staffifyai.com/v1/knowledge-bases \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Center",
    "source_url": "https://help.yourcompany.com",
    "crawl_frequency": "weekly",
    "auto_refresh_enabled": true,
    "max_depth": 3,
    "max_pages": 200
  }'

Note: setting source_url on create triggers an immediate crawl. Changing it to a different URL via PATCH deletes all crawled entries and re-crawls from scratch. PATCHing with the same URL that is already set does nothing (no re-crawl, no entry deletion). Setting source_url to null removes the source URL and sets status to idle.

Add Q&A entries manually. Send an array of up to 100 objects. Max 8,000 characters combined per entry.

curl -X POST https://api.staffifyai.com/v1/knowledge-bases/kb_00000001/entries \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "q": "What are your opening hours?", "a": "Monday-Friday 9am-6pm CET." },
    { "q": "Do you offer free shipping?",  "a": "Yes, free shipping over EUR 50." },
    { "q": "How do I cancel my order?",    "a": "Email [email protected] within 24h." }
  ]'

# Response
{ "added": 3 }

Response is { "added": N } — the count of entries inserted. Embeddings are generated automatically; entries that fail embedding get one automatic retry. Entries with no embedding can be retried later via POST /entries/:entryId/retry-embedding.

If your org has reached the plan entry limit, the request returns 403 with an error message indicating the current count and plan cap.

Upload a document and extract Q&A entries asynchronously. Accepts .pdf, .docx, .doc, .txt (max 50MB). Returns a job_id to poll.

curl -X POST https://api.staffifyai.com/v1/knowledge-bases/kb_00000001/entries/upload \
  -H "Authorization: Bearer sfy_live_YOUR_KEY" \
  -F "[email protected]"

# Response
{ "job_id": "42", "status": "queued" }

Semantic similarity search across entries. Use to test what your agent will retrieve for a given query.

curl "https://api.staffifyai.com/v1/knowledge-bases/kb_00000001/search?q=return+policy&limit=5" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response
{
  "results": [
    { "id": 1, "question": "What is your return policy?", "answer": "30 days...", "similarity": 0.9124 },
    { "id": 7, "question": "Can I return a sale item?",   "answer": "Yes, if...", "similarity": 0.7831 }
  ],
  "query": "return policy",
  "total_entries": 247
}

Trigger an immediate re-crawl of the configured source_url. Rate limited to once per 12 hours. Returns 409 if already crawling. Returns 429 if within the cooldown window -- the response body includes available_in_hours indicating how many hours remain before you can refresh again (e.g. {"error": "...", "available_in_hours": 4.5}).

curl -X POST https://api.staffifyai.com/v1/knowledge-bases/kb_00000001/refresh \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

# Response
{ "job_id": "44", "status": "queued" }

Other endpoints