Platform Tutorials

Platform tutorials are hands-on guides that walk you through specific use cases and implementation patterns. Each tutorial includes detailed instructions, code examples, and best practices to help you build real-world conversational AI applications.

Browsing Available Tutorials

To retrieve the complete catalog of available tutorials:

GET /api/v1/platform/tutorial/list

http

Each tutorial entry includes:

  • id: Unique identifier for the tutorial (used in URLs)
  • name: Tutorial title
  • description: Brief overview of what the tutorial covers
  • category: Organizational category (e.g., "Getting Started", "Integrations")
  • tags: Searchable keywords associated with the tutorial
  • index: Display order for organizing tutorials hierarchically
  • link: Direct link to the official tutorial page

Tutorial Structure

Tutorials are organized hierarchically using categories and index values. Lower index numbers appear first in navigation, allowing logical progression from beginner to advanced topics. The category field groups related tutorials together, making it easier to browse by topic area.

{
  "id": "how-to-get-started-with-chatbotkit",
  "name": "How to Get Started with ChatBotKit",
  "description": "A beginner's guide to creating your first AI chatbot",
  "category": "Getting Started",
  "tags": ["quickstart", "beginner", "tutorial"],
  "index": 1,
  "link": "https://chatbotkit.com/tutorials/how-to-get-started-with-chatbotkit"
}

javascript

Using Tutorials in Applications

The tutorial API enables you to build custom learning experiences, integrate tutorial content into your applications, or create AI agents that can guide users through specific implementation patterns. You can:

  • Build custom tutorial portals with your own styling and navigation
  • Create contextual help systems that show relevant tutorials based on user goals
  • Power AI agents with practical implementation knowledge
  • Generate tutorial indexes or learning paths

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

Searching Tutorials

When you need to find specific implementation examples or step-by-step guides, semantic search helps you discover the most relevant tutorials quickly. The search uses vector embeddings and similarity matching to understand the meaning behind your query, returning tutorials that best match your intent.

To search the tutorials:

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

{
  "search": "how to integrate with Slack",
  "take": 10
}

http

The search parameter accepts natural language queries. Describe what you're trying to build or the use case you're interested in:

  • "creating a WhatsApp chatbot"
  • "integrating with Notion"
  • "building an AI agent with custom abilities"
  • "embedding widget in a website"

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 tutorial

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

{
  "items": [
    {
      "id": "how-to-integrate-chatbotkit-with-slack",
      "name": "How to Integrate ChatBotKit with Slack",
      "description": "Learn how to connect your bot to Slack",
      "score": 0.92,
      "excerpt": "To integrate with Slack, first create a Slack app...",
      "tags": ["slack", "integration", "messaging"],
      "link": "https://chatbotkit.com/tutorials/how-to-integrate-chatbotkit-with-slack"
    }
  ]
}

javascript

Search Performance and Indexing

Tutorial 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 tutorial content
  • Uses cosine similarity to rank results
  • Returns results typically within 1-2 seconds

Tutorials are automatically re-indexed when content is updated, ensuring search results reflect the latest tutorials. 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 about what you want to build
  • Adjust the take parameter based on how many examples you want to review
  • Review the excerpt field to quickly determine if a tutorial is relevant
  • Use the score field to gauge result confidence (scores above 0.7 are typically very relevant)

Retrieving Full Tutorial Content

To access the complete content of a specific tutorial, including all text, code examples, and step-by-step instructions:

GET /api/v1/platform/tutorial/{tutorialId}/fetch

http

Replace {tutorialId} with the tutorial identifier from the list or search endpoints. For example, to fetch the getting started tutorial:

GET /api/v1/platform/tutorial/how-to-get-started-with-chatbotkit/fetch

http

Response Structure

The fetch endpoint returns complete tutorial information:

  • content: Full markdown content of the tutorial (without frontmatter)
  • All metadata fields from the list endpoint (name, description, category, tags, index, link)
  • Timestamp information (createdAt, updatedAt)
{
  "id": "how-to-get-started-with-chatbotkit",
  "name": "How to Get Started with ChatBotKit",
  "description": "A beginner's guide to creating your first AI chatbot",
  "category": "Getting Started",
  "tags": ["quickstart", "beginner", "tutorial"],
  "index": 1,
  "content": "# How to Get Started with ChatBotKit\n\nThis tutorial will guide you...",
  "link": "https://chatbotkit.com/tutorials/how-to-get-started-with-chatbotkit",
  "createdAt": 1700000000000,
  "updatedAt": 1700000000000
}

javascript

Working with Content

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

  • Render in your own tutorial 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 guiding users through implementations
  • 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, images, and links are preserved.

Error Handling

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

  • The tutorial ID is misspelled
  • The tutorial 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 tutorials or falling back to search.

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

Go to cbk.ai