Platform Documentation

Platform documentation is organized into structured guides covering various aspects of building with the platform - from getting started tutorials to advanced integration patterns and API references. Each document is carefully maintained, categorized, and tagged to help you find relevant information quickly.

Browsing Available Documentation

To retrieve the complete catalog of available documentation:

GET /api/v1/platform/doc/list

http

Each documentation entry includes:

  • id: Unique identifier for the document (used in URLs)
  • name: Document title
  • description: Brief overview of the document's content
  • category: Organizational category (e.g., "Getting Started", "API Reference")
  • tags: Searchable keywords associated with the document
  • index: Display order for organizing documentation hierarchically
  • link: Direct link to the official documentation page

Documentation Structure

Documentation is organized hierarchically using categories and index values. Lower index numbers appear first in navigation, allowing logical progression from foundational concepts to advanced topics. The category field groups related documents together, making it easier to browse documentation by topic area.

{
  "id": "quickstart",
  "name": "Quick Start Guide",
  "description": "Get started building your first conversational AI agent",
  "category": "Getting Started",
  "tags": ["quickstart", "tutorial", "beginner"],
  "index": 1,
  "link": "https://chatbotkit.com/docs/quickstart"
}

javascript

Using Documentation in Applications

The documentation API enables you to build custom documentation browsers, integrate help content into your applications, or create AI agents that can reference official documentation when answering questions. You can:

  • Build custom documentation portals with your own styling and navigation
  • Create contextual help systems that show relevant docs based on user actions
  • Power AI agents with up-to-date platform knowledge
  • Generate documentation indexes or sitemaps

Note: The list endpoint returns metadata only. To access the full content of a specific document, use the fetch endpoint with the document ID. The URL field provides a direct link to the official web-based documentation for user-facing references.

Searching Documentation

When you need to find specific information or answers to questions, semantic search helps you discover the most relevant documentation quickly. The search uses vector embeddings and similarity matching to understand the meaning behind your query, returning documents that best match your intent.

To search the documentation:

POST /api/v1/platform/doc/search
Content-Type: application/json

{
  "search": "how to create a bot with custom abilities",
  "take": 10
}

http

The search parameter accepts natural language queries. Describe what you're trying to accomplish or the information you're seeking:

  • "deploying a bot to multiple channels"
  • "authentication and API keys"
  • "processing uploaded files in conversations"
  • "webhook configuration for external integrations"

The optional take parameter limits the number of results returned (1-100, default is 10).

Understanding Search Results

Search results include additional fields beyond the basic metadata:

  • score: Similarity score indicating relevance (higher is more relevant)
  • excerpt: Text snippet from the most relevant section of the document

Results are automatically ranked by relevance, with the most similar documents appearing first. The excerpt field shows the specific section that matched your query, giving you context before opening the full document.

{
  "items": [
    {
      "id": "bot-abilities",
      "name": "Bot Abilities Guide",
      "description": "Learn how to add and configure abilities",
      "score": 0.89,
      "excerpt": "To add custom abilities to your bot, navigate to...",
      "tags": ["bots", "abilities", "configuration"],
      "link": "https://chatbotkit.com/docs/bot-abilities"
    }
  ]
}

javascript

Search Performance and Indexing

Documentation search uses pre-generated embeddings for fast response times. The system:

  • Generates embeddings for your search query in real-time
  • Compares against pre-computed embeddings of documentation content
  • Uses cosine similarity to rank results
  • Returns results typically within 1-2 seconds

Documents are automatically re-indexed when content is updated, ensuring search results reflect the latest documentation. The embedding model uses the same technology as the platform's semantic search features, providing consistent and reliable results.

Best Practices:

  • Use natural, descriptive queries rather than single keywords
  • Adjust the take parameter based on how many alternatives you want to review
  • Review the excerpt field to quickly determine if a document is relevant
  • Use the score field to gauge result confidence (scores above 0.7 are typically very relevant)

Retrieving Full Documentation Content

To access the complete content of a specific documentation page, including all text, code examples, and formatting:

GET /api/v1/platform/doc/{docId}/fetch

http

Replace {docId} with the document identifier from the list or search endpoints. For example, to fetch the quickstart guide:

GET /api/v1/platform/doc/quickstart/fetch

http

Response Structure

The fetch endpoint returns complete document information:

  • content: Full markdown content of the document (without frontmatter)
  • All metadata fields from the list endpoint (name, description, category, tags, index, link)
  • Timestamp information (createdAt, updatedAt)
{
  "id": "quickstart",
  "name": "Quick Start Guide",
  "description": "Get started building your first conversational AI agent",
  "category": "Getting Started",
  "tags": ["quickstart", "tutorial", "beginner"],
  "index": 1,
  "content": "# Quick Start Guide\n\nThis guide will help you...",
  "link": "https://chatbotkit.com/docs/quickstart",
  "createdAt": 1700000000000,
  "updatedAt": 1700000000000
}

javascript

Working with Content

The content field contains markdown-formatted text that you can:

  • Render in your own documentation browser using a markdown parser
  • Extract specific sections or code examples programmatically
  • Index for full-text search in your own systems
  • Use as context for AI agents answering questions
  • Convert to other formats (HTML, PDF, plain text)

The content is clean markdown without frontmatter metadata, making it easy to process and display. All original formatting, headings, lists, code blocks, and links are preserved.

Error Handling

If the requested document doesn't exist, the endpoint returns a 404 status with an appropriate error message. This can happen if:

  • The document ID is misspelled
  • The document has been removed or renamed
  • There's a mismatch between index metadata and content storage

Always handle 404 responses gracefully in your application, potentially suggesting alternative documents or falling back to search.

Note: Documentation content is cached for performance. If you're building a system that needs real-time documentation updates, consider implementing a periodic refresh mechanism or cache invalidation strategy based on update timestamps.

Go to cbk.ai