Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/ai/*.

Knowledge Base RAG API

Document ingestion, semantic search, and retrieval-augmented generation for AI-powered support and knowledge management.

Overview

Attribute	Value
Base Path	`/api/v1/knowledge-base`
Authentication	Bearer Token
Required Roles	JWT authentication required (no specific role restriction)

Document Ingestion

Ingest Document

Ingest a document into the knowledge base for semantic search.

POST /api/v1/knowledge-base/ingest

Request Body

{
  "content": "# Food Safety Guidelines\n\nAll staff must wash hands for 20 seconds...",
  "metadata": {
    "title": "Food Safety Guidelines",
    "category": "compliance",
    "source": "training_materials",
    "version": "2.1",
    "effective_date": "2026-01-01"
  },
  "options": {
    "chunk_size": 512,
    "chunk_overlap": 50,
    "extract_entities": true
  }
}

Response

{
  "document_id": "doc_001",
  "status": "processed",
  "chunks_created": 8,
  "metadata": {
    "title": "Food Safety Guidelines",
    "category": "compliance",
    "word_count": 1250,
    "language": "en"
  },
  "entities_extracted": [
    {"type": "topic", "value": "food_safety"},
    {"type": "topic", "value": "hygiene"},
    {"type": "regulation", "value": "FDA_guidelines"}
  ],
  "created_at": "2026-01-24T19:30:00Z"
}

Ingest File

Upload and ingest a file (PDF, DOCX, TXT, MD).

POST /api/v1/knowledge-base/ingest/file

Request (multipart/form-data)

file: employee_handbook.pdf
metadata: {"category": "hr", "department": "all"}
options: {"extract_tables": true}

Response

{
  "document_id": "doc_002",
  "status": "processing",
  "file_info": {
    "name": "employee_handbook.pdf",
    "size_bytes": 2456789,
    "pages": 45,
    "type": "application/pdf"
  },
  "estimated_completion": "2026-01-24T19:35:00Z"
}

Bulk Ingest

Ingest multiple documents in a single request.

POST /api/v1/knowledge-base/ingest/bulk

Request Body

{
  "documents": [
    {
      "content": "Menu item description guidelines...",
      "metadata": {"category": "menu", "type": "guidelines"}
    },
    {
      "content": "POS troubleshooting steps...",
      "metadata": {"category": "support", "type": "troubleshooting"}
    }
  ],
  "options": {
    "parallel": true,
    "notify_on_complete": true
  }
}

Response

{
  "batch_id": "batch_001",
  "status": "processing",
  "documents": [
    {"index": 0, "document_id": "doc_003", "status": "processed"},
    {"index": 1, "document_id": "doc_004", "status": "processing"}
  ],
  "total": 2,
  "completed": 1
}

Ingest Support Tickets

Ingest resolved support tickets for knowledge extraction.

POST /api/v1/knowledge-base/ingest/tickets

Request Body

{
  "tickets": [
    {
      "ticket_id": "TKT-2026-0042",
      "subject": "POS not printing receipts",
      "description": "Customer reported POS terminal not printing...",
      "resolution": "Restarted print spooler service and verified printer connection",
      "category": "hardware",
      "resolved_at": "2026-01-24T15:00:00Z"
    }
  ],
  "options": {
    "extract_qa_pairs": true,
    "anonymize": true
  }
}

Response

{
  "ingested": 1,
  "qa_pairs_extracted": 3,
  "documents_created": [
    {
      "document_id": "doc_ticket_001",
      "qa_pairs": [
        {
          "question": "How do I fix POS receipt printing issues?",
          "answer": "Restart the print spooler service and verify printer connection..."
        }
      ]
    }
  ]
}

Semantic Search

Search Knowledge Base

Perform semantic search across the knowledge base.

POST /api/v1/knowledge-base/search

Request Body

{
  "query": "How do I handle food allergies?",
  "filters": {
    "category": ["safety", "compliance"],
    "source": "training_materials"
  },
  "options": {
    "limit": 10,
    "min_score": 0.7,
    "search_type": "hybrid",
    "include_context": true
  }
}

Response

{
  "query": "How do I handle food allergies?",
  "results": [
    {
      "document_id": "doc_001",
      "chunk_id": "chunk_015",
      "score": 0.92,
      "content": "When a customer reports a food allergy, immediately notify the kitchen manager. All allergy orders must be prepared using dedicated equipment...",
      "metadata": {
        "title": "Allergy Handling Procedures",
        "category": "safety",
        "section": "Kitchen Protocols"
      },
      "context": {
        "before": "...proper food handling techniques.",
        "after": "Common allergens include nuts, shellfish..."
      },
      "highlights": [
        "food allergy",
        "kitchen manager",
        "dedicated equipment"
      ]
    },
    {
      "document_id": "doc_005",
      "chunk_id": "chunk_042",
      "score": 0.87,
      "content": "The top 8 food allergens that must be disclosed: milk, eggs, fish, shellfish, tree nuts, peanuts, wheat, and soybeans...",
      "metadata": {
        "title": "FDA Allergen Guidelines",
        "category": "compliance"
      }
    }
  ],
  "total_results": 15,
  "search_metadata": {
    "search_type": "hybrid",
    "vector_weight": 0.7,
    "keyword_weight": 0.3,
    "duration_ms": 45
  }
}

Search Types

Type	Description
`semantic`	Vector similarity search only
`keyword`	Traditional keyword/BM25 search
`hybrid`	Combined semantic + keyword (recommended)

Get Similar Documents

Find documents similar to a given document.

GET /api/v1/knowledge-base/documents/{document_id}/similar

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 5)
`min_score`	float	Minimum similarity score

Answer Generation

Generate Answer

Generate an AI answer using retrieved context (RAG).

POST /api/v1/knowledge-base/answer

Request Body

{
  "question": "What is the proper temperature for storing raw chicken?",
  "options": {
    "include_citations": true,
    "max_sources": 3,
    "response_style": "concise",
    "language": "en"
  }
}

Response

{
  "answer": "Raw chicken must be stored at 40°F (4°C) or below. For freezer storage, maintain temperatures at 0°F (-18°C) or below. Never store raw chicken above cooked items to prevent cross-contamination.",
  "confidence": 0.94,
  "citations": [
    {
      "document_id": "doc_001",
      "title": "Food Safety Guidelines",
      "excerpt": "Raw poultry must be stored at 40°F (4°C) or below...",
      "page": 12
    },
    {
      "document_id": "doc_008",
      "title": "FDA Food Code Requirements",
      "excerpt": "Cold storage requirements for raw proteins...",
      "page": 5
    }
  ],
  "sources_used": 2,
  "metadata": {
    "model": "claude-haiku-4.5",
    "tokens_used": 350,
    "duration_ms": 890
  }
}

Chat with Knowledge Base

Multi-turn conversation with knowledge base context.

POST /api/v1/knowledge-base/chat

Request Body

{
  "session_id": "kb_sess_001",
  "message": "What about for beef?",
  "context": {
    "previous_topic": "food_storage_temperatures"
  }
}

Response

{
  "session_id": "kb_sess_001",
  "response": "For beef, the safe storage temperature is also 40°F (4°C) or below for refrigeration. Ground beef should be used within 1-2 days, while steaks and roasts can be stored for 3-5 days. Frozen beef at 0°F will remain safe indefinitely, but quality is best within 4-12 months depending on the cut.",
  "citations": [...],
  "follow_up_suggestions": [
    "What are the cooking temperatures for beef?",
    "How long can cooked beef be stored?"
  ]
}

Document Management

List Documents

GET /api/v1/knowledge-base/documents

Query Parameters

Parameter	Type	Description
`category`	string	Filter by category
`source`	string	Filter by source
`status`	string	`active`, `archived`, `processing`
`search`	string	Search document titles
`page`	integer	Page number
`limit`	integer	Results per page

Response

{
  "documents": [
    {
      "id": "doc_001",
      "title": "Food Safety Guidelines",
      "category": "compliance",
      "source": "training_materials",
      "status": "active",
      "chunks": 8,
      "word_count": 1250,
      "created_at": "2026-01-24T19:30:00Z",
      "updated_at": "2026-01-24T19:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156
  }
}

Get Document

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

Response

{
  "id": "doc_001",
  "title": "Food Safety Guidelines",
  "content": "# Food Safety Guidelines\n\nAll staff must wash hands...",
  "metadata": {
    "category": "compliance",
    "source": "training_materials",
    "version": "2.1"
  },
  "chunks": [
    {
      "id": "chunk_001",
      "content": "All staff must wash hands for 20 seconds...",
      "position": 0,
      "token_count": 128
    }
  ],
  "stats": {
    "search_hits": 45,
    "answer_uses": 23,
    "avg_relevance_score": 0.85
  }
}

Update Document

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

Request Body

{
  "content": "# Updated Food Safety Guidelines\n\n...",
  "metadata": {
    "version": "2.2"
  },
  "options": {
    "reindex": true
  }
}

Delete Document

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

Archive Document

POST /api/v1/knowledge-base/documents/{document_id}/archive

Categories & Tags

GET /api/v1/knowledge-base/categories

Response

{
  "categories": [
    {
      "name": "compliance",
      "document_count": 25,
      "subcategories": ["food_safety", "labor_law", "accessibility"]
    },
    {
      "name": "operations",
      "document_count": 45,
      "subcategories": ["pos", "inventory", "scheduling"]
    },
    {
      "name": "hr",
      "document_count": 18,
      "subcategories": ["policies", "benefits", "onboarding"]
    }
  ]
}

Manage Tags

POST /api/v1/knowledge-base/documents/{document_id}/tags

Request Body

{
  "add": ["featured", "manager_required"],
  "remove": ["draft"]
}

Analytics

Get Knowledge Base Stats

GET /api/v1/knowledge-base/analytics

Response

{
  "overview": {
    "total_documents": 156,
    "total_chunks": 2340,
    "total_tokens": 485000,
    "storage_mb": 12.5
  },
  "usage": {
    "searches_today": 234,
    "answers_generated_today": 89,
    "avg_search_latency_ms": 42,
    "avg_answer_latency_ms": 890
  },
  "quality": {
    "avg_search_relevance": 0.85,
    "answer_satisfaction_rate": 0.92,
    "citation_accuracy": 0.97
  },
  "top_queries": [
    {"query": "food storage temperature", "count": 45},
    {"query": "allergy handling", "count": 38},
    {"query": "pos troubleshooting", "count": 32}
  ],
  "gaps_identified": [
    {
      "query": "gift card refund policy",
      "searches": 15,
      "avg_relevance": 0.45,
      "suggestion": "Add gift card policy documentation"
    }
  ]
}

Webhooks

Event	Description
`kb.document_ingested`	Document successfully ingested
`kb.document_updated`	Document content updated
`kb.document_deleted`	Document removed
`kb.search_performed`	Search query executed
`kb.answer_generated`	AI answer generated
`kb.gap_detected`	Knowledge gap identified

Error Responses

Status	Code	Description
400	`invalid_document`	Document format invalid
400	`chunk_too_large`	Content exceeds chunk limit
404	`document_not_found`	Document ID not found
413	`file_too_large`	Uploaded file exceeds limit
422	`unsupported_format`	File format not supported
429	`quota_exceeded`	Storage/API quota exceeded

RAG Knowledge Base Guide - Setup guide
LangGraph Agents - Agent integration
AI Gateway - Model routing

Overview​

Document Ingestion​

Ingest Document​

Ingest File​

Bulk Ingest​

Ingest Support Tickets​

Semantic Search​

Search Knowledge Base​

Search Types​

Get Similar Documents​

Answer Generation​

Generate Answer​

Chat with Knowledge Base​

Document Management​

List Documents​

Get Document​

Update Document​

Delete Document​

Archive Document​

Categories & Tags​

List Categories​

Manage Tags​

Analytics​

Get Knowledge Base Stats​

Webhooks​

Error Responses​

Related Documentation​

Overview

Document Ingestion

Ingest Document

Ingest File

Bulk Ingest

Ingest Support Tickets

Semantic Search

Search Knowledge Base

Search Types

Get Similar Documents

Answer Generation

Generate Answer

Chat with Knowledge Base

Document Management

List Documents

Get Document

Update Document

Delete Document

Archive Document

Categories & Tags

List Categories

Manage Tags

Analytics

Get Knowledge Base Stats

Webhooks

Error Responses

Related Documentation