←back to manuals

Platform Guides

The platform guide system provides comprehensive, in-depth guides that help developers understand and implement conversational AI solutions.

Platform guides are comprehensive documents that cover specific topics in depth. Unlike tutorials which focus on step-by-step instructions, guides provide thorough explanations, best practices, and reference material to help you build robust conversational AI applications.

Browsing Available Guides

To retrieve the complete catalog of available guides:

Each guide entry includes:

  • id: Unique identifier for the guide (used in URLs)
  • name: Guide title
  • description: Brief overview of what the guide covers
  • category: Organizational category
  • tags: Searchable keywords associated with the guide
  • index: Display order for organizing guides hierarchically
  • link: Direct link to the official guide page

Guide Structure

Guides are organized hierarchically using categories and index values. Lower index numbers appear first in navigation, allowing logical progression from foundational concepts to advanced topics.

Using Guides in Applications

The guide API enables you to build custom documentation experiences, integrate guide content into your applications, or create AI agents that can provide comprehensive information on specific topics. You can:

  • Build custom documentation portals with your own styling and navigation
  • Create contextual help systems that show relevant guides based on user needs
  • Power AI agents with in-depth knowledge for complex questions
  • Generate documentation indexes or learning paths

Note: The list endpoint returns metadata only. To access the full content of a specific guide, use the fetch endpoint with the guide ID.

Searching Guides

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

To search the guides:

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

  • "conversation management best practices"
  • "dataset configuration options"
  • "widget customization"
  • "security and authentication"

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 guide

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

Search Performance and Indexing

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

Guides are automatically re-indexed when content is updated, ensuring search results reflect the latest documentation.

Best Practices:

  • Use natural, descriptive queries about what you want to understand
  • Adjust the take parameter based on how many guides you want to review
  • Review the excerpt field to quickly determine if a guide is relevant
  • Use the score field to gauge result confidence (scores above 0.7 are typically very relevant)

Retrieving Full Guide Content

To access the complete content of a specific guide, including all text, examples, and detailed explanations:

Replace {guideId} with the guide identifier from the list or search endpoints.

Response Structure

The fetch endpoint returns complete guide information:

  • content: Full markdown content of the guide (without frontmatter)
  • All metadata fields from the list endpoint (name, description, category, tags, index, link)
  • Timestamp information (createdAt, updatedAt)

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 programmatically
  • Index for full-text search in your own systems
  • Use as context for AI agents answering complex 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, images, and links are preserved.

Error Handling

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

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

guidesdocumentationimplementationreference