Skip to main content

​
Overview

Bot store endpoints provide discovery and search functionality for finding and accessing shared bots.

​
Search Bots

​
Query Parameters

​
query
string
required
Search query string to match against bot titles and descriptions
​
limit
integer
default:"20"
Maximum number of results to return

​
Response

Returns an array of bot metadata objects:
​
id
string
Bot identifier
​
title
string
Bot title
​
description
string
Bot description
​
create_time
float
Unix timestamp of creation
​
last_used_time
float
Unix timestamp of last use
​
is_starred
boolean
Whether the bot is starred by the current user
​
owned
boolean
Whether the current user owns the bot
​
available
boolean
Whether the bot is available for use
​
sync_status
string
Knowledge base synchronization status:
  • "QUEUED": Waiting to start
  • "KNOWLEDGE_BASE_STACK_CREATED": Infrastructure created
  • "RUNNING": Sync in progress
  • "SUCCEEDED": Sync completed successfully
  • "FAILED": Sync failed
  • "ORIGINAL_NOT_FOUND": Original bot was removed
​
shared_scope
string
Sharing scope of the bot:
  • "private": Only owner can access
  • "partial": Shared with specific users/groups
  • "all": Public bot
​
shared_status
string
Detailed sharing status (e.g., "private", "shared", "pinned@xxx")

​
Example Request

GET /store/search?query=technical%20support&limit=10

​
Example Response

[
  {
    "id": "tech-support-bot",
    "title": "Tech Support Assistant",
    "description": "AI assistant for technical support queries",
    "create_time": 1704067200.0,
    "last_used_time": 1704153600.0,
    "is_starred": false,
    "owned": false,
    "available": true,
    "sync_status": "SUCCEEDED",
    "shared_scope": "all",
    "shared_status": "shared"
  },
  {
    "id": "customer-service-bot",
    "title": "Customer Service Helper",
    "description": "Assists with customer service inquiries",
    "create_time": 1703980800.0,
    "last_used_time": 1704240000.0,
    "is_starred": true,
    "owned": false,
    "available": true,
    "sync_status": "SUCCEEDED",
    "shared_scope": "all",
    "shared_status": "shared"
  }
]

​
Query Parameters

​
limit
integer
default:"20"
Maximum number of results to return

​
Response

Returns an array of bot metadata objects (same structure as search results), ordered by usage count in descending order.

​
Example Request

GET /store/popular?limit=5

​
Example Response

[
  {
    "id": "general-assistant",
    "title": "General AI Assistant",
    "description": "Versatile AI assistant for general questions",
    "create_time": 1703894400.0,
    "last_used_time": 1704326400.0,
    "is_starred": true,
    "owned": false,
    "available": true,
    "sync_status": "SUCCEEDED",
    "shared_scope": "all",
    "shared_status": "pinned@featured"
  }
]

​
Get Pickup Bots

​
Query Parameters

​
limit
integer
default:"20"
Maximum number of results to return

​
Response

Returns an array of bot metadata objects (same structure as search results), in random order.

​
Example Request

GET /store/pickup?limit=3

​
Example Response

[
  {
    "id": "code-reviewer",
    "title": "Code Review Assistant",
    "description": "Helps review code and suggest improvements",
    "create_time": 1703808000.0,
    "last_used_time": 1704067200.0,
    "is_starred": false,
    "owned": false,
    "available": true,
    "sync_status": "SUCCEEDED",
    "shared_scope": "all",
    "shared_status": "shared"
  },
  {
    "id": "writing-helper",
    "title": "Writing Assistant",
    "description": "Assists with writing and editing tasks",
    "create_time": 1703721600.0,
    "last_used_time": 1704153600.0,
    "is_starred": false,
    "owned": false,
    "available": true,
    "sync_status": "SUCCEEDED",
    "shared_scope": "all",
    "shared_status": "shared"
  },
  {
    "id": "data-analyst",
    "title": "Data Analysis Bot",
    "description": "Helps analyze and visualize data",
    "create_time": 1703635200.0,
    "last_used_time": 1704240000.0,
    "is_starred": true,
    "owned": false,
    "available": true,
    "sync_status": "SUCCEEDED",
    "shared_scope": "all",
    "shared_status": "shared"
  }
]

​
Bot Discovery Flow

Here’s a typical flow for discovering and using bots from the store:
  1. Browse Popular Bots: Start with /store/popular to see the most used bots
  2. Check Pickup Selection: Use /store/pickup to discover featured bots
  3. Search for Specific Needs: Use /store/search with keywords to find bots matching your requirements
  4. Get Bot Details: Use /bot/summary/{bot_id} to see full details before using
  5. Start Conversation: Create a conversation with the bot using /conversation endpoint

​
Bot Visibility Levels

Bots in the store can have different sharing configurations:
Shared ScopeDescriptionVisibility in Store
privateOnly owner can accessNot shown in store (unless you’re the owner)
partialShared with specific users/groupsShown only to allowed users
allPublic botShown to all users

​
Notes

  • Search results include private bots only if you are the owner
  • Popular and pickup endpoints exclude private bots entirely
  • Admin users may see partial shared bots not accessible to them
  • The available field indicates if the bot can be used (false if original bot was removed)
  • The sync_status shows the knowledge base synchronization state

Build docs developers (and LLMs) love

Get started for freeTalk to us