# Treechat Documentation > Learn how to use Treechat - a social knowledge platform powered by Bitcoin SV Source: https://docs.treechat.com/ ## Welcome to Treechat Docs This is the official documentation for [Treechat](https://treechat.com), a social knowledge platform powered by Bitcoin SV (BSV). Here you'll find guides, tutorials, and references to help you get the most out of Treechat. ## Quick Start New to Treechat? Start here: 1. **[Creating an Account](https://docs.treechat.com/guides/creating-an-account/)** - Set up your Treechat account 2. **[Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/)** - Add Bitcoin SV to start tipping and earning 3. **[Understanding Upvalue](https://docs.treechat.com/guides/understanding-upvalue/)** - Learn how to tip and earn on Treechat ## Key Features - **Bitcoin SV Integration** - Earn and send micropayments for quality content - **Action Tags** - Use AI-powered commands to generate images, videos, and more - **Advanced Search** - Find content with powerful search operators - **Threaded Conversations** - Branch any message into its own discussion ## Need Help? - Browse the **[Guides](https://docs.treechat.com/guides/searching-treechat/)** section for how-to articles - Check out [treechat.com](https://treechat.com) to explore the platform --- # Creating an Account > Learn how to sign up and create your Treechat account Source: https://docs.treechat.com/guides/creating-an-account/ Getting started with Treechat is simple. Follow this guide to create your account and start exploring. ## Sign Up 1. **Visit Treechat**: Go to [app.treechat.com/signup](https://app.treechat.com/signup) 2. **Choose a Username**: Pick a unique username that will be your identity on Treechat - Usernames are case-insensitive - Choose something memorable - other users will find you by this name 3. **Enter Your Email**: Provide a valid email address - Used for account recovery and important notifications - We respect your privacy - see our [privacy policy](https://treechat.com/privacy) 4. **Set a Password**: Create a secure password for your account - Use a strong, unique password - Consider using a password manager 5. **Complete Registration**: Click the sign-up button to create your account ## First Steps Once you've created your account: ### Explore the Public Feed Visit the [public stream](https://app.treechat.com/stream/public) to see what people are talking about and get a feel for Treechat. ### Set Up Your Profile Add a profile picture and bio to help others get to know you. ### Fund Your Wallet (Optional but Recommended) To tip other users (upvalue) and earn Bitcoin SV, you'll need to fund your wallet. See the [Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/) guide to get started. ## Mobile Apps Treechat is also available on mobile: - **iOS**: Join the [TestFlight beta](https://treechat.com/ios.html) - **Android**: Download from [Google Play](https://treechat.com/android) Use the same username and password to log in on mobile. ## Troubleshooting ### Can't receive confirmation email? - Check your spam folder - Make sure you entered the correct email address - Try registering again with a different email - For help, mention @metamitya or @arghzero in the app ### Username already taken? - Choose a different username - Usernames must be unique across Treechat ## Next Steps - **[Fund Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/)** - Add Bitcoin SV to start tipping - **[Understanding Upvalue](https://docs.treechat.com/guides/understanding-upvalue/)** - Learn how to earn and tip - **[Searching Treechat](https://docs.treechat.com/guides/searching-treechat/)** - Find content and conversations --- # Funding Your Wallet > Learn how to add Bitcoin SV to your Treechat wallet Source: https://docs.treechat.com/guides/funding-your-wallet/ Treechat runs on Bitcoin SV (BSV), which powers the platform's micropayment system. To send upvalue (tips) to other users and earn BSV for your content, you'll need to fund your Treechat wallet. ## What is Bitcoin SV (BSV)? Bitcoin SV (Satoshi Vision) is a cryptocurrency that enables fast, low-cost transactions. Treechat uses BSV for: - **Upvalue** - Tipping other users for quality content - **Earnings** - Receiving tips from users who appreciate your posts - **On-chain posting** - Publishing public content to the blockchain ## Getting Bitcoin SV Before you can fund your Treechat wallet, you need to acquire some BSV. Here are recommended wallets and exchanges: ### Recommended Wallets #### RockWallet - **Website**: [rockwallet.com](https://rockwallet.com) - **Features**: Buy BSV directly with credit/debit card or bank transfer - **Platforms**: iOS, Android, Web - **Best for**: Beginners - easy to use with built-in purchase options #### Exodus - **Website**: [exodus.com](https://exodus.com) - **Features**: Multi-currency wallet with built-in exchange - **Platforms**: Desktop (Windows, Mac, Linux), Mobile (iOS, Android) - **Best for**: Users who want to manage multiple cryptocurrencies #### Orange Gateway - **Website**: [orangegateway.io](https://orangegateway.io) - **Features**: BSV-focused exchange and wallet - **Best for**: BSV enthusiasts and larger purchases ## Funding Your Treechat Wallet Once you have BSV in one of the above wallets: ### Step 1: Get Your Treechat Wallet Address 1. Log in to [Treechat](https://app.treechat.com) 2. Click on your profile or wallet icon 3. Find your BSV wallet address (a long string starting with `1` or `3`) 4. Copy this address ### Step 2: Send BSV to Treechat 1. Open your BSV wallet (RockWallet, Exodus, or Orange Gateway) 2. Select "Send" or "Transfer" 3. Paste your Treechat wallet address 4. Enter the amount of BSV you want to transfer 5. Confirm the transaction ### Step 3: Wait for Confirmation - BSV transactions are typically confirmed within minutes - Your balance will update in Treechat once the transaction is confirmed - Check your Treechat wallet to see the updated balance ## How Much Should I Fund? BSV amounts on Treechat are small since upvalue (tips) are typically just a few cents. Consider: - **$5-10 USD in BSV** - Good starting amount for tipping and experimenting - **$20-50 USD in BSV** - Comfortable amount for regular users - **More** - If you plan to tip frequently or run promotional campaigns Remember: When you receive upvalue from others, your balance will grow over time. ## Transaction Fees - **BSV network fees**: Extremely low (typically fractions of a cent) - **Treechat platform fee**: 15% of upvalue transactions - 85% goes to the content creator - 15% goes to Treechat for platform maintenance ## Safety Tips - **Double-check addresses**: Always verify the wallet address before sending - **Start small**: Test with a small amount first - **Keep backups**: Save your wallet recovery phrases securely - **Never share**: Don't share your private keys or recovery phrases with anyone ## Troubleshooting ### Transaction not showing up? - Check the transaction status in your sending wallet - BSV transactions usually confirm within 10 minutes - If it's been over an hour, mention @metamitya or @arghzero in the app for help ### Sent to wrong address? - Blockchain transactions cannot be reversed - Always double-check addresses before sending ## Next Steps - **[Understanding Upvalue](https://docs.treechat.com/guides/understanding-upvalue/)** - Learn how to tip and earn - **[Action Tags](https://docs.treechat.com/guides/action-tags/)** - Use AI features (requires BSV for some actions) - **[Searching Treechat](https://docs.treechat.com/guides/searching-treechat/)** - Find content to support with upvalue --- # Private vs Public Posts > Understanding the difference between private and public posting modes in Treechat Source: https://docs.treechat.com/concepts/private-vs-public/ Treechat offers two fundamental posting modes: **private** and **public**. Understanding the difference helps you control who sees your content and how you share it. ## Treechat's Unique Threading System One of Treechat's most powerful features is its **infinite tree-based threading system**. Unlike traditional forums or chat apps with linear conversations, Treechat lets you branch off from any message to create new discussion threads. ### How Threading Works **Tree Structure:** - Every post can have unlimited replies - Every reply can itself have unlimited replies - You can branch into **any message at any point** in a conversation - Each branch maintains its own context and conversation flow **Infinite Branching:** ``` Main Post ├─ Reply 1 │ ├─ Reply 1.1 │ │ └─ Reply 1.1.1 (branch into this!) │ └─ Reply 1.2 ├─ Reply 2 │ └─ Reply 2.1 └─ Reply 3 ``` **Why This Matters:** - **No more derailed conversations** - side discussions get their own threads - **Multiple simultaneous discussions** - explore different angles without chaos - **Preservation of context** - each branch maintains its own conversation history - **Natural knowledge organization** - ideas branch and evolve organically ### Practical Examples **Research & Brainstorming:** 1. Start with a question: "How do I optimize my website?" 2. Get several suggestions in replies 3. Branch into each suggestion to explore it deeply 4. Each branch becomes its own mini-discussion **Collaborative Work:** 1. Share a design mockup 2. Multiple people comment on different aspects 3. Branch into each comment for detailed refinement 4. Parallel discussions don't interfere with each other **AI-Powered Workflows:** 1. Ask an AI to generate an image: `!flux cyberpunk city` 2. Branch to try variations: `!edit_nb make it darker and more moody` 3. Branch again for different styles: `!edit_nb make it more colorful` 4. Each branch explores a different direction This tree structure is **fundamental to Treechat** and makes it ideal for deep exploration, collaborative work, and AI-assisted creation. ## What is Private Mode? Private mode is for personal conversations and content you want to keep restricted to specific people. ### Private Mode Features **Who can see it:** - Only you (the author) - People you explicitly mention with `@username` - People who participate in the thread by replying **Visibility:** - Not visible in public feeds or public search results - Not discoverable by others - Not posted to the Bitcoin SV blockchain - Can only be accessed via direct link by permitted users **Use cases:** - Personal notes and thoughts - Private conversations with specific people - Draft content before making it public - Sensitive discussions ## What is Public Mode? Public mode makes your content visible to everyone and posts it to the Bitcoin SV blockchain. ### Public Mode Features **Who can see it:** - Anyone on Treechat - Anonymous visitors (without signing in) - Anyone with the link - Searchable by all users **Visibility:** - Appears in public feeds and search results - Posted permanently to the BSV blockchain - Can be discovered through search and browsing - Part of the public knowledge graph **Blockchain benefits:** - Permanent, censorship-resistant storage - Verifiable timestamp and authorship - Cannot be deleted or modified (only marked as deleted) - Part of the decentralized web **Use cases:** - Sharing knowledge publicly - Building your reputation - Contributing to public discussions - Creating content for others to discover ## Key Differences | Feature | Private | Public | | ------------------ | ---------------------------- | ------------------------------------ | | **Visibility** | Restricted to specific users | Visible to everyone | | **Search** | Not searchable | Fully searchable | | **Blockchain** | Not posted to BSV | Posted to BSV blockchain | | **Discovery** | Link-only access | Discoverable in feeds | | **AI Action Tags** | Available (costs BSV) | Available (some free, some cost BSV) | | **Upvotes** | Available | Available | | **Upvalue (tips)** | Available | Available | | **Editing** | Can edit freely | Edits are tracked on blockchain | ## Action Tag Costs: Private vs Public Many AI action tags are **free in public mode** but cost BSV in private mode. This encourages public knowledge sharing. **Examples:** - `!flux` image generation: ~$0.09 private, **FREE public** - `!edit_nb` image editing: ~$0.09 private, **FREE public** - `!nb` (Nano Banana): ~$0.09 private, **FREE public** Check the [Action Tags guide](https://docs.treechat.com/guides/action-tags/) for specific pricing. ## How to Switch Between Modes When creating a post, you can choose the posting mode: 1. **Look for the privacy toggle** in your post composer 2. **Select private or public** before posting 3. **Private is the default** for safety **Note:** Once published, you generally cannot change a post from public to private (since it's on the blockchain), but you can change private posts to public. ## Best Practices ### When to Use Private Mode - Brainstorming and drafting ideas - Personal conversations - Sensitive or confidential information - Testing features before public use - Notes for yourself ### When to Use Public Mode - Sharing knowledge and insights - Building your public profile - Contributing to public discussions - Creating content you want to monetize via upvalue - Making your work discoverable - Taking advantage of free AI generation ## Privacy and Security **Private posts are secure:** - Not visible to search engines - Not listed in public feeds - Access controlled by Treechat - Only visible to permitted users **Public posts are permanent:** - Once on the blockchain, cannot be fully deleted - Anyone can access and archive public content - Your username and content are permanently associated - Think carefully before posting sensitive information publicly ## Next Steps - **[Understanding Upvalue](https://docs.treechat.com/guides/understanding-upvalue/)** - Earn BSV from your public content - **[Action Tags](https://docs.treechat.com/guides/action-tags/)** - Use free AI tools in public mode - **[Searching Treechat](https://docs.treechat.com/guides/searching-treechat/)** - Discover public content --- # Understanding Upvalue > Learn how to tip and earn Bitcoin SV on Treechat public posts Source: https://docs.treechat.com/concepts/understanding-upvalue/ Upvalue is Treechat's tipping system that lets you reward quality content with Bitcoin SV on **public (on-chain) posts only**. Think of it as "upvote with money" - a way to show appreciation that actually helps creators earn. ## What is Upvalue? Upvalue is a micropayment you send to another user to show appreciation for their public post or comment. Unlike traditional social media "likes" which have no value, upvalue sends real Bitcoin SV to content creators. **Important**: Upvalue is only available on **public posts** that are stored on the Bitcoin SV blockchain. Private posts use upvotes instead (see below). ## How Upvalue Works ### Sending Upvalue (Tipping) 1. **Find public content you like** - Browse Treechat and find public posts worth supporting 2. **Click the upvalue button** - Usually shown as a coin or tip icon 3. **Choose an amount** - Select how much BSV to send (can be just a few cents) 4. **Confirm** - The transaction is processed and recorded on the blockchain The BSV is sent directly from your Treechat wallet to the creator's wallet via a blockchain transaction. ### Receiving Upvalue (Earning) When someone sends you upvalue on a public post: - **85% goes to you** - The majority of the tip - **15% goes to Treechat** - Platform fee for hosting and maintaining the service For example: - Someone tips you 100 satoshis (sats) - You receive 85 sats - Treechat receives 15 sats ## Why the 15% Fee? The platform fee covers: - Server and infrastructure costs - Development and maintenance - Blockchain transaction fees - Customer support - New feature development This model allows Treechat to operate without ads while compensating creators directly. ## Upvalue vs. Upvotes Treechat has two different engagement systems depending on whether content is public or private: | Feature | Upvote (Private Posts) | Upvalue (Public Posts) | | --------------------- | ------------------------- | -------------------------------- | | **Cost** | Free | Costs BSV | | **Value to creator** | Social signal only | Real money (85% of tip) | | **Transaction** | No blockchain transaction | On-chain BSV transaction | | **Impact on ranking** | Affects visibility | Affects visibility more strongly | | **Platform fee** | None | 15% to Treechat | | **Availability** | **Private posts only** | **Public posts only** | ### Key Differences **Upvotes (Private Posts)**: - Available only on private, off-chain posts - Free to give - Social signal with no monetary value - No BSV transaction involved - Simple engagement metric **Upvalue (Public Posts)**: - Available only on public, on-chain posts - Requires BSV in your wallet - Sends real money to content creators - Recorded as a blockchain transaction - Stronger signal of content quality **You cannot upvalue private posts, and you cannot upvote public posts.** The feature available depends on whether the content is public (on blockchain) or private (off blockchain). Upvalue carries more weight in Treechat's ranking algorithm since it represents real value, not just engagement. ## Best Practices ### For Tipping (Public Posts) - **Tip quality content** - Support public posts that provide value - **Start small** - Even a few cents is meaningful - **Be consistent** - Regular small tips add up for creators - **Tip early** - Early upvalue helps good content get discovered ### For Earning (Creating Public Content) - **Create quality public posts** - Valuable content on-chain earns upvalue - **Post publicly when appropriate** - Public posts can earn BSV rewards - **Engage with community** - Reply to comments and discussions - **Post consistently** - Regular quality content builds an audience - **Be authentic** - Genuine posts resonate more than promotional content ## Upvalue and Search Ranking Content with more upvalue ranks higher in Treechat's algorithm: - **Market-based ranking** - Content users value (with money) ranks higher - **No ad manipulation** - Rankings reflect genuine user preference - **Quality signal** - Upvalue is a stronger signal than free upvotes This creates a market-based algorithm where users, not advertisers, decide what's valuable. ## Minimum and Maximum Amounts - **Minimum tip**: Usually 1 satoshi (though the platform may set minimums) - **Maximum tip**: No technical limit - tip as much as you want - **Typical amounts**: Most tips range from a few cents to a dollar or two ## Checking Your Balance To see your upvalue earnings: 1. Click on your profile or wallet icon 2. View your BSV balance 3. See transaction history for tips received and sent ## Withdrawing Your Earnings You can withdraw your BSV earnings: 1. Go to your wallet settings 2. Enter a BSV address from an external wallet (RockWallet, Exodus, etc.) 3. Specify the amount to withdraw 4. Confirm the transaction Network fees (typically very small) will apply for withdrawals. ## Upvalue Etiquette - **Don't beg for tips** - Let your content speak for itself - **Thank tippers** - Acknowledge generous supporters (optional) - **Tip back** - Support others who create value - **Don't spam** - Quality over quantity ## Troubleshooting ### Can't send upvalue? - Check your wallet balance - you need sufficient BSV - Make sure your wallet is funded (see [Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/)) - Verify the post is public - upvalue only works on public posts ### Didn't receive upvalue? - Check your transaction history - Upvalue appears in your balance instantly - If there's an issue, mention @metamitya or @arghzero in the app ### How do I see who tipped me? - Check your notification feed - View your wallet transaction history ### Why can't I upvalue this post? - The post is likely private - upvalue only works on public (on-chain) posts - Private posts can only receive upvotes (free likes) ## Next Steps - **[Private vs Public Posts](https://docs.treechat.com/concepts/private-vs-public/)** - Understand when to use public vs private mode - **[Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/)** - Add BSV to start tipping - **[Searching Treechat](https://docs.treechat.com/guides/searching-treechat/)** - Find content worth supporting - **[Action Tags](https://docs.treechat.com/guides/action-tags/)** - Create valuable content with AI tools --- # AI Assistants > Learn how to chat with AI language models using @@ mentions Source: https://docs.treechat.com/guides/ai-assistants/ Treechat includes integrated AI assistants powered by leading language models. You can invoke these AI assistants in conversations using the `@@` mention syntax to get help, ask questions, or have deep discussions. ## What are AI Assistants? AI assistants in Treechat are conversational AI models that you can chat with directly in your threads. Unlike [Action Tags](https://docs.treechat.com/guides/action-tags/) which generate media content (images, videos, etc.), AI assistants engage in natural language conversations. ## How @@ Mentions Work To start a conversation with an AI assistant, type `@@` followed by the model name: **Syntax**: `@@model_name your question or prompt` **Example**: `@@sonnet-5.5 explain quantum entanglement` ### What Happens Next When you use `@@` mentions: 1. The AI responds in the same thread as a new post 2. You can continue the conversation naturally by replying 3. The AI has access to the full conversation history 4. Multiple back-and-forth exchanges are supported 5. The AI can reference earlier messages and context ## Available AI Models When you type `@@` in a post, Treechat displays an autocomplete menu showing available AI models. The exact list depends on your account configuration and which models are currently enabled. ### Recommended Models For the best conversational experience, we recommend: - **Claude Sonnet 5.5** (`@@sonnet-5.5`, default) - Excellent balance of intelligence, speed, and conversational ability. Well-suited for complex reasoning, creative tasks, and technical discussions. - **Claude Opus 5.5** (`@@opus-5.5`) - Anthropic's Opus model for harder reasoning and longer, more careful answers - **Claude Fable 5.2** (`@@fable-5.2`) - Anthropic's most capable model for the most demanding problems - **GPT-6 Sol** (`@@sol-6`) and **GPT-6 Astra** (`@@astra-6`) - OpenAI's GPT-6 models - **Grok 4.7** (`@@grok-4.7`) - xAI's Grok model The available models may also include options from Google (Gemini), Moonshot (Kimi), Z.ai (GLM), and others. **Tip**: Type `@@` and browse the autocomplete list to see what's currently available on your account. ## Use Cases for AI Assistants ### Getting Help and Explanations Ask the AI to explain complex topics, technical concepts, or help you understand something. **Example**: `@@sonnet-5.5 explain how blockchain consensus mechanisms work` ### Brainstorming and Ideation Use AI assistants to generate ideas, explore possibilities, or think through problems. **Example**: `@@sol-6 help me brainstorm marketing strategies for a new SaaS product` ### Code and Technical Discussions Discuss programming problems, get code suggestions, or debug issues. **Example**: `@@sonnet-5.5 review this Python function and suggest improvements` ### Analysis and Research Ask the AI to analyze information, compare options, or research topics. **Example**: `@@opus-5.5 compare the pros and cons of different database architectures` ### Creative Writing Get help with writing, editing, or generating creative content. **Example**: `@@sonnet-5.5 help me write a compelling introduction for my blog post about AI ethics` ## Conversational Context AI assistants maintain context throughout the conversation thread: - **Thread awareness**: The AI can reference previous messages in the same thread - **Multi-turn dialogues**: Have extended back-and-forth conversations - **Follow-up questions**: Ask clarifying questions or request elaboration - **Context building**: Earlier messages inform later responses **Example conversation flow**: ``` You: @@sonnet-5.5 what is machine learning? AI: [Explains machine learning basics] You: can you give me an example of supervised learning? AI: [Provides example, building on earlier explanation] You: how does that differ from unsupervised learning? AI: [Explains differences, referencing prior context] ``` ## Combining AI Assistants with Other Features You can use AI assistants alongside other Treechat features: ### With Action Tags Generate content with action tags, then discuss related topics with an AI: ``` !flux a futuristic city at sunset [AI generates image] @@sonnet-5.5 what are some techniques for creating compelling sci-fi cityscapes? [AI provides advice on composition and design] ``` **Note**: Currently, AI assistants cannot see images or videos in the thread. They can only read text content, so they can discuss concepts, techniques, and ideas, but not analyze specific visual content. ### In Public or Private Threads Use AI assistants in any conversation context: - Private personal brainstorming - Public discussions and debates - Collaborative problem-solving ## @@ vs ! (Mentions vs Action Tags) It's important to understand the difference: | Feature | @@ AI Assistants | ! Action Tags | | --------------- | ------------------------------- | --------------------------- | | **Purpose** | Conversational AI chat | Generate media content | | **Output** | Text responses | Images, videos, audio | | **Interaction** | Multi-turn dialogue | One-time generation | | **Context** | Full thread history | Prompt-based | | **Use cases** | Questions, analysis, discussion | Creative content generation | **Use @@** when you want to: - Ask questions - Get explanations - Have conversations - Analyze information - Get advice or suggestions **Use !** when you want to: - Generate images - Create videos - Make music - Edit media - Produce creative content ## Tips for Better AI Conversations ### Be Specific Clear, specific questions get better responses than vague ones. **Good**: `@@sonnet-5.5 explain the Byzantine Generals Problem in distributed systems` **Less good**: `@@sonnet-5.5 tell me about computers` ### Provide Context Give the AI relevant background information when needed. **Example**: `@@sol-6 I'm building a React app with TypeScript. How should I structure my component props for a data table?` ### Ask Follow-up Questions Don't hesitate to ask for clarification or more detail. **Examples**: - "Can you elaborate on that second point?" - "What are some alternatives to that approach?" - "Can you provide a concrete example?" ### Reference Thread History The AI can see earlier messages, so you can reference them naturally. **Example**: "Based on the explanation you gave earlier, how would that apply to my specific use case?" ### Experiment with Different Models Different AI models have different strengths. Try multiple models to find what works best for your needs. ## Costs and Billing AI assistant conversations may have costs associated with them: - Costs vary by model - Charges are typically per message or token usage - Your BSV wallet is used for payment - Public vs private threads may have different pricing **Make sure you have funded your wallet** - See [Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/) for details. ## Privacy Considerations ### Private Threads When using AI assistants in private threads: - Only you can see the conversation - Your data is processed by the AI provider - Refer to individual AI provider privacy policies for details ### Public Threads When using AI assistants in public threads: - The entire conversation is publicly visible - Anyone can see your prompts and the AI's responses - Consider what information you share ## Troubleshooting ### @@ mention not triggering? - Make sure you typed `@@` (two @ symbols) - Check that autocomplete menu appears - Verify you have sufficient BSV balance ### AI not responding? - Check if the model is temporarily unavailable - Ensure your prompt is clear and appropriate - Verify your wallet has sufficient funds ### Response seems off-topic? - The AI might be using thread context in unexpected ways - Try starting a new thread for unrelated topics - Provide more specific context in your prompt ## Next Steps - **[Action Tags](https://docs.treechat.com/guides/action-tags/)** - Generate images, videos, and other media - **[Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/)** - Add BSV to use AI assistants - **[Understanding Upvalue](https://docs.treechat.com/guides/understanding-upvalue/)** - Earn BSV from your content - **[Searching Treechat](https://docs.treechat.com/guides/searching-treechat/)** - Find others using AI assistants --- # Action Tags > Learn how to use AI-powered action tags to generate images, videos, music, and more Source: https://docs.treechat.com/guides/action-tags/ Action tags are special commands in Treechat that let you invoke AI models and services directly from your posts. Simply type a command starting with `!` followed by your prompt, and Treechat will generate content for you. ## What are Action Tags? Action tags are commands that start with `!` (exclamation mark) that trigger AI processing. For example: - `!flux create a sunset over mountains` - Generates an AI image - `!edit_nb make the sky more dramatic` - Edits an image earlier in the thread - `!veo3 a bird flying through clouds` - Generate a video - `!animate bring this image to life` - Animates an image from earlier in the thread ## How to Use Action Tags 1. **Type the command**: Start your post with `!` followed by the action tag name 2. **Add your prompt**: Write what you want the AI to create or do 3. **Post it**: Submit your post like normal 4. **Wait for results**: The AI will process your request and attach the result to your post ### Example ``` !flux a beautiful cyberpunk cityscape at night ``` This will generate an AI image of a cyberpunk city and attach it to your post. ## Image Generation **Quality Tip**: For the best quality image generation, use **!nb** (Nano Banana / Gemini 2.5 Flash) - it's currently the highest quality image generator available. ### !nb Generate images with Google's Gemini 2.5 Flash (aka "Nano Banana") - **best quality image generator available**. **Usage**: `!nb [your image description]` **Examples**: - `!nb a serene mountain landscape at sunset` - `!nb portrait of a futuristic robot` - `!nb abstract geometric patterns in vibrant colors` **Cost**: ~$0.09 private, **FREE public** **Note**: This is currently the highest quality image generation model in Treechat. ### !flux Generate images with Flux.1 by Black Forest Labs - fast and high quality. **Usage**: `!flux [your image description]` **Examples**: - `!flux a cat wearing a space suit` - `!flux photorealistic portrait of an astronaut` - `!flux abstract art with vibrant colors` **Cost**: ~$0.09 per image (private), **FREE (public)** ### !qwen Generate images with Qwen - advanced image generation with excellent text rendering capabilities. **Usage**: `!qwen [your image description]` **Examples**: - `!qwen a neon sign saying "Hello World"` - `!qwen poster design with the text "AI Art"` **Cost**: ~$0.05 per image (private), **FREE (public)** **Note**: Qwen excels at generating images with complex text and typography. ### !dalle Generate images with DALL-E 3 by OpenAI. **Usage**: `!dalle [your image description]` **Example**: `!dalle a cozy coffee shop in autumn` **Cost**: ~$0.09 per image (private), **FREE (public)** ### !gpt4o Generate images using OpenAI's GPT-4o multimodal image generation. **Usage**: `!gpt4o [your image description]` **Example**: `!gpt4o realistic photo of a mountain sunrise` **Cost**: ~$0.30 per image ## Video Generation ### !veo3 Generate high-quality videos with Google Veo 3 - **best quality video generator available**. **Usage**: `!veo3 [your video description]` **Examples**: - `!veo3 a bird flying through clouds` - `!veo3 cinematic shot of waves crashing on beach` **Output**: High-quality video **Cost**: ~$7.99 per video **Note**: This is currently the highest quality video generation model available in Treechat. ### !veo2 Generate high-quality videos with Google Veo 2 - can be used for both text-to-video and image-to-video. **Usage**: `!veo2 [your video description]` **Examples**: - `!veo2 a person walking down a city street` - `!veo2 aerial view of mountains at sunrise` **Output**: 5-second video **Cost**: ~$2.99 per video **Note**: Veo 2 can generate videos from text prompts and can also animate existing images (see !animate_veo below) ### !luma Generate photorealistic videos with Luma Dream Machine - can be used for both text-to-video and image-to-video. **Usage**: `!luma [your video description]` **Example**: `!luma waves crashing on a beach at sunset` **Output**: 5-second video **Cost**: ~$0.99 per video **Note**: Luma can generate videos from text prompts and can also animate existing images (see !animate_luma below) ### !kling Generate high-quality videos with Kling v2.1 - can be used for both text-to-video and image-to-video. **Usage**: `!kling [your video description]` **Examples**: - `!kling a beautiful sunset timelapse` - `!kling dancing cat in a disco` **Output**: 5-second videos **Cost**: ~$1.99 per video **Note**: Kling can generate videos from text prompts and can also animate existing images (see !animate_kling below) ### !wan Generate videos with Alibaba WAN 2.5 - can be used for both text-to-video and image-to-video. **Usage**: `!wan [your video description]` **Example**: `!wan a serene mountain landscape with flowing water` **Note**: WAN can generate videos from text prompts and can also animate existing images (see !animate_wan below) **Output**: 5 seconds at 480p **Cost**: ~$0.99 per video ### !seedance Generate videos with ByteDance SeedAnce-1-Pro - can be used for both text-to-video and image-to-video. **Usage**: `!seedance [your video description]` **Example**: `!seedance a person walking through a misty forest` **Output**: 5 seconds at 720p, 24fps **Cost**: ~$0.99 per video **Note**: SeedAnce can generate videos from text prompts and can also animate existing images (see !animate_seedance below) ### !sora2 Generate high-quality videos with OpenAI Sora 2 - can be used for both text-to-video and image-to-video. **Usage**: `!sora2 [your video description]` **Examples**: - `!sora2 a drone flying over a mountain valley` - `!sora2 time-lapse of clouds moving across the sky` **Output**: High-quality video **Cost**: ~$0.99 per video **Note**: Sora 2 can generate videos from text prompts and can also animate existing images (see !animate_sora2 below) ### !minimax Generate videos with Minimax/Hailuo - can be used for both text-to-video and image-to-video. **Usage**: `!minimax [your video description]` **Example**: `!minimax a butterfly landing on a flower` **Output**: 5-second video **Cost**: ~$0.99 per video **Note**: Minimax can generate videos from text prompts and can also animate existing images (see !animate below) ## Audio & Music ### !suno Generate complete songs with Suno AI. **Usage**: `!suno [song description]` **Example**: `!suno create a jazz song about coffee and morning vibes` ### !stableaudio Generate music or sound effects from a text prompt with Stability AI Stable Audio 2.5. **Usage**: `!stableaudio [optional duration] [audio description]` **Example**: `!stableaudio 30s cinematic ambient synths with distant thunder` ## Remix Actions (Editing Existing Images) Remix actions let you modify images that appear earlier in the conversation thread. Instead of generating new content, they transform existing images based on your prompt. **Quality Tip**: For the best quality image editing, use **!edit_nb** (Nano Banana / Gemini 2.5 Flash) - it's currently the highest quality image editor available. ### !edit_nb Edit images using Google's Gemini 2.5 Flash (aka "Nano Banana") - **best quality image editor available**. **Usage**: `!edit_nb [editing instructions]` **Example**: `!edit_nb add snow to the landscape` **Note**: Requires an image earlier in the thread to edit. **Cost**: ~$0.09 per edit ### !edit Edit images using Google's Gemini Flash model. **Usage**: `!edit [editing instructions]` **Example**: `!edit make the sky more dramatic` **Note**: Requires an image earlier in the thread to edit. **Cost**: ~$0.09 per edit ### !edit_openai Edit images using OpenAI's GPT-4o multimodal model. **Usage**: `!edit_openai [editing instructions]` **Example**: `!edit_openai remove the person from this image` **Note**: Requires an image earlier in the thread to edit. **Cost**: ~$0.30 per edit ### !edit_flux Edit images using Flux Kontext Pro - state-of-the-art image editing with excellent prompt following. **Usage**: `!edit_flux [editing instructions]` **Example**: `!edit_flux change the lighting to golden hour` **Note**: Requires an image earlier in the thread to edit. **Cost**: ~$0.09 per edit ### !edit_qwen Edit images using Qwen with img2img pipeline. **Usage**: `!edit_qwen [editing instructions]` **Example**: `!edit_qwen enhance the colors` **Note**: Requires an image earlier in the thread to edit. **Cost**: ~$0.05 per edit ### !animate (Minimax) Generate videos using an earlier image as the first frame with Minimax/Hailuo. **Usage**: `!animate [animation description]` **Example**: `!animate make this image come to life with gentle movement` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: 5-second video **Cost**: ~$0.99 per video ### !animate_kling Generate videos using an earlier image as the first frame with Kling v2.1. **Usage**: `!animate_kling [animation description]` **Example**: `!animate_kling add realistic motion to this scene` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: 5-second video **Cost**: ~$1.99 per video ### !animate_luma Generate videos using an earlier image as the first frame with Luma Dream Machine. **Usage**: `!animate_luma [animation description]` **Example**: `!animate_luma animate this with smooth camera movement` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: 5-second video **Cost**: ~$0.99 per video ### !animate_veo Generate videos using an earlier image as the first frame with Google Veo 2. **Usage**: `!animate_veo [animation description]` **Example**: `!animate_veo bring this scene to life` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: 5-second video **Cost**: ~$2.99 per video ### !animate_veo3 Generate videos using an earlier image as the first frame with Google Veo 3 - **best quality image-to-video available**. **Usage**: `!animate_veo3 [animation description]` **Example**: `!animate_veo3 bring this scene to life with cinematic motion` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: High-quality video **Cost**: ~$7.99 per video ### !animate_seedance Generate videos using an earlier image as the first frame with ByteDance SeedAnce-1-Pro. **Usage**: `!animate_seedance [animation description]` **Example**: `!animate_seedance add dynamic movement` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: 5 seconds at 720p, 24fps **Cost**: ~$0.99 per video ### !animate_sora2 Generate videos using an earlier image as the first frame with OpenAI Sora 2. **Usage**: `!animate_sora2 [animation description]` **Example**: `!animate_sora2 animate this with cinematic camera movement` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: High-quality video **Cost**: ~$0.99 per video ### !animate_wan Generate videos using an earlier image as the first frame with Alibaba WAN 2.5. **Usage**: `!animate_wan [animation description]` **Example**: `!animate_wan add gentle motion to this scene` **Note**: Requires an image earlier in the thread as the starting frame. **Output**: 5 seconds at 480p **Cost**: ~$0.99 per video ## AI Assistants In addition to action tags for generating media, Treechat also supports conversational AI assistants using `@@` mentions. These let you chat with language models like Claude Sonnet 5.5 (default), Claude Opus 5.5, and GPT-6 for questions, analysis, and discussions. **[Learn more about AI Assistants →](https://docs.treechat.com/guides/ai-assistants/)** ## Costs and Billing Action tags that use AI models have costs associated with them: - Costs are deducted from your BSV wallet - Prices vary by model (typically $0.03 - $1.40 per generation) - Public posts may have different pricing than private posts - Check your wallet balance before using expensive models **Make sure you have funded your wallet** - See [Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/) for details. ## Tips for Best Results ### For Image Generation - **Be specific**: Describe colors, style, mood, and composition - **Use style keywords**: "photorealistic", "watercolor", "cyberpunk", "minimalist" - **Mention lighting**: "golden hour", "dramatic lighting", "soft shadows" - **Try different models**: Each AI has different strengths ### For Video Generation - **Keep it simple**: Complex scenes may not generate well - **Describe motion**: "slow zoom", "camera panning", "rotating" - **Set the scene**: Describe environment and atmosphere - **Be patient**: Video generation can take several minutes ### For Image Editing (Remix Actions) - **Be specific**: Describe exactly what you want to change - **Reference the original**: Mention specific elements from the source image - **Use clear instructions**: "add", "remove", "change", "enhance" - **Try different models**: Each has different editing strengths ### For Image-to-Video (Animate Actions) - **Start with good images**: Better source images produce better videos - **Describe the motion**: Be specific about how things should move - **Keep it realistic**: Natural motions work better than complex changes - **Consider the model**: Different models excel at different types of animation ### For AI Conversations (@@ Mentions) - **Ask clear questions**: Be specific about what you need - **Provide context**: Give background information when needed - **Continue the conversation**: Follow up with additional questions - **Reference chat history**: The AI remembers your previous messages ## Combining Action Tags You can chain action tags together in conversation threads to create complex workflows: **Example workflow**: 1. Generate an image: `!nb a beautiful mountain landscape` 2. Edit the result: `!edit_nb add a sunset in the background` 3. Animate it: `!animate_veo3 gentle camera pan across the scene` 4. Discuss it: Reply with `@@sonnet-5.5 what are some ways to improve landscape photography?` This allows you to iteratively refine and transform content through multiple AI models. **Note**: Currently, AI assistants invoked with `@@` mentions cannot see images or videos in the thread - they only read text. Use them for questions, analysis, and discussions based on text content. ## Troubleshooting ### Action tag didn't work? - Check that you started with `!` (exclamation mark) - Make sure you spelled the tag name correctly - Verify you have sufficient BSV balance for paid models ### Generation failed? - Some prompts may be filtered for content policy - Check if the model is temporarily unavailable - Try rephrasing your prompt ### No result appearing? - Large videos/images may take several minutes to generate - Check your notifications for completion status - Refresh the page to see the latest results ## Next Steps - **[Funding Your Wallet](https://docs.treechat.com/guides/funding-your-wallet/)** - Add BSV to use action tags - **[Understanding Upvalue](https://docs.treechat.com/guides/understanding-upvalue/)** - Earn BSV from your AI-generated content - **[Searching Treechat](https://docs.treechat.com/guides/searching-treechat/)** - Find others using action tags --- # Searching Treechat > Learn how to find exactly what you're looking for using Treechat's powerful search Source: https://docs.treechat.com/guides/searching-treechat/ Treechat has a powerful Google-style search that lets you find conversations, filter by user, content type, date, and more. This guide will show you how to search like a pro. ## Common Search Tasks ### Finding Posts by a User To find all posts by a specific user, use `from:username`: ``` from:alice bitcoin ``` This finds all posts by alice mentioning bitcoin. You can OR multiple users together by comma-separating them: ``` from:alice,bob ethereum ``` This returns posts where either alice **or** bob is the root author. > ℹ️ `from:` always matches the quest's **parent author**. Replies/comments from a user do not make a quest show up unless they created the root post. ### Finding Recent Conversations Use date filters to find recent content: ``` after:2025-09-01 AI ``` Or find older content: ``` before:2024-01-01 cryptocurrency ``` Combine them for date ranges: ``` after:2025-09-01 before:2025-10-01 blockchain ``` ### Finding Content by Type Search for posts with specific media types: - **Videos**: `has:video machine learning` - **Images**: `has:image infographic` - **Links**: `has:url bitcoin` - **Tweets**: `has:tweet elon musk` - **Any media**: `has:media` ### Finding Popular Content Use upvalue (Bitcoin SV tips) to find valuable content: ``` upvalue:>=1000 technology ``` Or by upvote count: ``` upvote:>50 cryptocurrency ``` ### Searching Within Teams/Streams Filter by specific teams or streams: ``` stream:bitcoin market analysis ``` Search multiple streams: ``` stream:bitcoin,ethereum DeFi ``` Search teams with spaces in names: ``` stream:"Bitcoin Discussion" market analysis ``` Search multiple teams with mixed quoting: ``` stream:"Team A","Team B",unquoted DeFi ``` Special pseudostreams: - `stream:public` - Public feed - `stream:private` - Your private posts - `stream:clips` - Clips ### Exact Phrases and Exclusions Require an exact phrase: ``` +"nakamoto consensus" bitcoin ``` Exclude content: ``` cryptocurrency -scam -fraud ``` Combine them: ``` stream:bitcoin +"proof of work" -BCH ``` ### Sorting Results Change how results are ranked: - **Newest first**: `sort:new` - **Most relevant**: `sort:relevance` - **Trending**: `sort:hot` - **Most upvalued**: `sort:top` Example: ``` stream:technology AI sort:hot ``` --- ## Complete Operator Reference ### User Filters #### `from:username` Filter posts by a specific user (case-insensitive username lookup). **Quote support:** Use quotes for usernames with spaces: `from:"User Name"` **Compound values:** Comma-separate usernames to OR them together: - `from:alice,bob` – posts where **alice OR bob** is the parent author - `from:"Jane Doe","John Smith"` – parent author matching either quoted name **Examples:** - `from:alice` - All posts by alice - `from:"John Doe"` - User with spaces in name (requires quotes) - `from:bob bitcoin` - Bob's bitcoin posts --- ### Stream/Team Filters #### `stream:team_name` Filter by teams/streams. Supports comma-separated values. **Quote support for names with spaces:** - `stream:"Team With Spaces"` - Single team with spaces - `stream:"Team A","Team B",unquoted` - Mixed quoted and unquoted - Works with `from:` and other operators **Compound search logic:** - Multiple streams use OR logic: `stream:A,B` returns posts from stream A OR stream B - Multiple operators use AND logic: `stream:A from:user` returns posts in A AND by user **Standard streams:** - `stream:bitcoin` - `stream:bitcoin,ethereum` - Multiple streams (OR logic) **Pseudostreams:** - `stream:public` or `stream:home` - Public feed - `stream:private` - Your private posts - `stream:clips` or `stream:clip` - Clips **Examples:** - `stream:bitcoin,ethereum AI` - `stream:"Bitcoin Discussion",ethereum,"DeFi Projects"` - `stream:public has:video` - `stream:clips from:alice` --- ### Date Filters #### `before:YYYY-MM-DD` Find posts created before a date. **Example:** `before:2025-10-01` #### `after:YYYY-MM-DD` Find posts created after a date. **Example:** `after:2025-09-01` #### Date Ranges Combine both for date ranges. **Example:** `after:2025-09-01 before:2025-10-01` --- ### Content Type Filters #### `has:video` Find posts with video attachments. **Example:** `has:video machine learning` #### `has:image` Find posts with images. **Example:** `has:image infographic` #### `has:url` or `has:link` Find posts containing URLs (including embedded tweets). **Example:** `has:url bitcoin` #### `has:tweet` Find posts with embedded tweets. **Example:** `has:tweet elon musk` #### `has:media` Find posts with any media (video, image, url, or tweet). **Example:** `has:media` --- ### Visibility Filters #### `is:public` Show only public posts. **Example:** `is:public has:video` #### `is:private` Show only your private posts. **Example:** `is:private has:image` #### `is:clip` Show only clips. **Example:** `is:clip from:alice` --- ### Value Filters #### `upvote:[operator]value` Filter by upvote count. **Operators:** `=`, `>`, `>=`, `<`, `<=` **Examples:** - `upvote:10` or `upvote:=10` - Exactly 10 upvotes - `upvote:>10` - More than 10 upvotes - `upvote:>=10` - 10 or more upvotes - `upvote:<10` - Less than 10 upvotes - `upvote:<=10` - 10 or fewer upvotes **Example:** `upvote:>=10 has:url` #### `upvalue:[operator]value` Filter by Bitcoin SV upvalue (in satoshis). Uses same operators as `upvote`. **Examples:** - `upvalue:>=1000` - 1000+ satoshis - `upvalue:>5000 technology` - High-value tech posts --- ### Sort Operators #### `sort:new` Sort by newest first (chronological). **Aliases:** `sort:time`, `sort:recency` **Example:** `sort:new bitcoin` #### `sort:relevance` Sort by text relevance with engagement signals. **Aliases:** `sort:relev` **Example:** `sort:relevance AI` #### `sort:hot` Sort by trending (time-decayed engagement). **Aliases:** `sort:trending` **Example:** `sort:hot cryptocurrency` #### `sort:top` Sort by most upvoted/upvalued. **Aliases:** `sort:upvote`, `sort:upvalue` **Example:** `sort:top has:video` **Note:** If multiple sort operators are present, the last one wins. --- ### Required/Excluded Content #### `+"exact phrase"` Require an exact phrase. **Example:** `+"nakamoto consensus"` #### `-"unwanted phrase"` Exclude posts with this phrase. **Example:** `bitcoin -"price prediction"` #### `+requiredword` Require a specific word (unquoted). **Example:** `+bitcoin +blockchain technology` #### `-excludedword` Exclude posts with a word. **Example:** `cryptocurrency -scam -fraud` **Combine multiple:** ``` stream:bitcoin +"nakamoto consensus" -scam +decentralization ``` --- ## Complex Quote and Compound Usage ### Mixed quoted and unquoted streams: ``` stream:"Bitcoin Discussion",ethereum,"DeFi Projects" ``` Searches three teams: "Bitcoin Discussion" (quoted), "ethereum" (unquoted), and "DeFi Projects" (quoted). ### Complex multi-operator search: ``` stream:"Team A","Team B",unquoted from:"User Name" has:video sort:hot ``` Finds videos from user "User Name" in any of the three teams, sorted by trending. ### Quote handling rules: - Use quotes when names contain spaces - Mix quoted and unquoted values in comma-separated lists - Quotes are optional for single-word names ### Operator Logic **Within an operator (OR logic):** - `stream:A,B,C` - Returns posts from A OR B OR C - `from:alice,bob` - Returns posts where alice OR bob is the parent author - Multiple values are combined with OR **Between operators (AND logic):** - `stream:A from:user` - Returns posts in A AND by user - Different operators are combined with AND **Example:** - `stream:bitcoin,ethereum from:alice` - Returns: Posts by alice in (bitcoin OR ethereum) - Logic: (stream=bitcoin OR stream=ethereum) AND from=alice --- ## Real-World Examples ### Find User Content with Filters ``` from:alice has:video before:2025-10-01 ``` All video posts by alice before October 1, 2025. ### Multi-Stream Search ``` stream:bitcoin,ethereum +"nakamoto consensus" -scam ``` Bitcoin or Ethereum streams with exact phrase, excluding scams. ### Public Video Content ``` is:public has:video sort:hot ``` Trending public video posts. ### Popular Posts with Links ``` upvote:>=10 has:url after:2025-09-01 sort:top AI ``` Highly upvoted AI posts with URLs from September 2025 onwards, sorted by upvotes. ### Private Images from User ``` is:private has:image from:bob ``` Bob's private image posts. ### Complex Multi-Filter Search ``` stream:technology upvote:>50 has:video +"machine learning" -hype after:2025-01-01 sort:relevance ``` Technology stream, highly upvoted videos with exact phrase "machine learning", excluding "hype", from 2025 onwards, sorted by relevance. --- ## How Search Works ### Filter Extraction All operators are extracted from your query. The remaining text becomes a free-form search. **Example:** `from:alice bitcoin mining` - User filter: alice - Free-form query: "bitcoin mining" ### Case Sensitivity - User lookups: Case-insensitive - Team/stream lookups: Case-insensitive - Filter keywords: Case-insensitive - Free-form search text: Original case preserved (analyzed by search engine) ### Caching User and team lookups are cached per request for performance. ### Error Handling The search returns errors for: - **User not found:** `from:nonexistent_user` - **Stream not found:** `stream:invalid_name` - **Ambiguous stream:** `stream:name` (when multiple matches exist) - **Invalid date format:** `before:2025-13-45` - **Invalid numeric value:** `upvote:notanumber` - **Negative numeric values:** `upvote:-5` All errors include descriptive messages to help you fix your query. --- # Build on Treechat > Let people connect your app to their Treechat account so it can post, reply, branch, upload and read for them. Source: https://docs.treechat.com/developers/overview/ Treechat **App Connect** lets your app act for a Treechat member after they approve it. Your app sends people to Treechat to sign in, they choose to allow it, and your app gets an access token. With that token it can post, reply, start branches, upload media and read threads through a JSON REST API. Nobody shares a password with you. Examples: a video tool that posts each new episode, a scheduler, a bot that answers in a channel, a reader app. ## How Treechat content is shaped Treechat is a tree of conversations, not a flat feed. | Term | Meaning | | ----------- | --------------------------------------------------------------------------------------------------------------- | | **Post** | One message: text, images, audio or video. | | **Thread** | A conversation: a first post and the replies under it. | | **Branch** | A thread that grows out of one post. Any post can start a branch, so a conversation can split into side topics. | | **Upvalue** | A paid upvote in Bitcoin SV, sent from reader to creator. | Read endpoints return Treechat's existing JSON, which uses older names: a thread is a `quest` and a post is an `answer`. ## What an app can and can't do An app can: - start a thread, reply in a thread, or reply in a post's branch (`treechat:write`) - upload images, audio and video to attach to posts (`uploads:write`) - read threads and posts the member can see (`treechat:read`) - read the member's ID and username (`account:read`) An app **can't** spend the member's money, send upvalue, or change their account. Posts it makes show "via _your app name_". Members can disconnect your app at any time. ## Addresses | What | URL | | ----------------------------- | ----------------------------------------------------------------- | | Register an app | `https://api.treechat.com/developers/apps` | | Authorization server (issuer) | `https://api.treechat.com` | | OAuth discovery | `https://api.treechat.com/.well-known/oauth-authorization-server` | | REST API base | `https://api.treechat.com/api/apps/v1` | | OpenAPI 3.1 description | `https://api.treechat.com/api/apps/v1/openapi.json` | | MCP server (same tokens) | `https://api.treechat.com/mcp` | ## Next steps 1. [Quickstart](https://docs.treechat.com/developers/quickstart/): register, connect and post in a few minutes. 2. [Authentication](https://docs.treechat.com/developers/authentication/): OAuth details, permissions and tokens. 3. [API reference](https://docs.treechat.com/developers/api-reference/): every endpoint, field and response. 4. [Limits and errors](https://docs.treechat.com/developers/limits-and-errors/): rate limits, error codes and retries. ## For AI agents and tools These docs are published in forms an agent can read directly: - [`/llms.txt`](https://docs.treechat.com/llms.txt): an index of every page, with a one-line summary each. - [`/llms-full.txt`](https://docs.treechat.com/llms-full.txt): every page in one plain Markdown file. - Any page as Markdown: add `.md` to its path, for example [`/developers/api-reference.md`](https://docs.treechat.com/developers/api-reference.md). - `https://api.treechat.com/api/apps/v1/openapi.json`: the REST API as OpenAPI 3.1, for code generators and tool definitions. If your agent speaks MCP, it can skip the REST API and connect to `https://api.treechat.com/mcp` instead. See [treechat.com/mcp](https://treechat.com/mcp). --- # Quickstart > Register an app, connect a Treechat account with OAuth and PKCE, then post and read with curl. Source: https://docs.treechat.com/developers/quickstart/ This walks through the whole flow with `curl`. Replace the capitalized placeholders with your own values. ## 1. Register your app 1. Sign in to Treechat and open `https://api.treechat.com/developers/apps`. 2. Choose **Register an app** and fill in: - **App name**: shown to people when they connect, and on every post as "via _App name_". - **Homepage**: your site. - **Redirect URIs**: 1 to 5 exact URLs Treechat may send people back to. Use `https`, or `http://localhost` while you build. - **Permissions**: only the ones you need: `treechat:write`, `uploads:write`, `treechat:read`, `account:read`. 3. Save. Treechat shows a **client ID** and a **client secret**. The secret is shown once; store it on your server only. You can rotate it later from the app page. Your app works for anyone as soon as it's registered. There is no review queue. ## 2. Send the member to Treechat Create a PKCE verifier and challenge for each sign-in: ```bash VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64) CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n') ``` Redirect the browser to: ```text https://api.treechat.com/mcp/oauth/authorize ?response_type=code &client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.com/auth/treechat/callback &scope=treechat:write%20uploads:write%20treechat:read%20account:read &state=RANDOM_STATE &code_challenge=CHALLENGE &code_challenge_method=S256 &resource=https://api.treechat.com/mcp ``` The member signs in, sees your app's name, homepage and developer, and chooses **Allow**. Treechat redirects to your `redirect_uri` with `?code=...&state=...`. Check that `state` matches what you sent. ## 3. Trade the code for tokens ```bash curl -X POST https://api.treechat.com/mcp/oauth/token \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d grant_type=authorization_code \ -d code=CODE_FROM_REDIRECT \ -d redirect_uri=https://yourapp.com/auth/treechat/callback \ -d code_verifier="$VERIFIER" \ -d resource=https://api.treechat.com/mcp ``` ```json { "access_token": "…", "token_type": "Bearer", "expires_in": 900, "refresh_token": "…", "scope": "treechat:write uploads:write treechat:read account:read" } ``` ## 4. Check who connected ```bash curl https://api.treechat.com/api/apps/v1/me \ -H "Authorization: Bearer ACCESS_TOKEN" ``` ```json { "id": "af899143-…", "username": "clip_fan", "space_id": "…" } ``` ## 5. Post ```bash curl -X POST https://api.treechat.com/api/apps/v1/posts \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: episode-1" \ -d '{"content":"Episode 1 is live","public":true}' ``` ```json { "operation_id": "…", "state": "completed", "thread_id": "72db5fc4-…", "post_id": "…" } ``` New threads are private unless you send `"public": true`. Reply in the thread: ```bash curl -X POST https://api.treechat.com/api/apps/v1/posts \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: episode-1-notes" \ -d '{"content":"Shot on a phone in one afternoon.","thread_id":"THREAD_ID"}' ``` ## 6. Read the thread ```bash curl https://api.treechat.com/api/apps/v1/threads/THREAD_ID \ -H "Authorization: Bearer ACCESS_TOKEN" ``` ## Next - Attach images or video: [Uploads](https://docs.treechat.com/developers/api-reference/#post-uploads). - Keep the connection alive: [Refreshing tokens](https://docs.treechat.com/developers/authentication/#refreshing-tokens). - Handle retries safely: [Idempotency](https://docs.treechat.com/developers/limits-and-errors/#retries-and-idempotency). --- # Authentication > OAuth 2.0 authorization code flow with PKCE, permissions, token lifetimes, refresh, revocation and disconnects. Source: https://docs.treechat.com/developers/authentication/ Treechat is a standard OAuth 2.0 authorization server. Apps use the **authorization code flow with PKCE** and authenticate to the token endpoint with their client ID and secret. ## Endpoints | Purpose | URL | | --------- | ----------------------------------------------------------------- | | Discovery | `https://api.treechat.com/.well-known/oauth-authorization-server` | | Authorize | `https://api.treechat.com/mcp/oauth/authorize` | | Token | `https://api.treechat.com/mcp/oauth/token` | | Revoke | `https://api.treechat.com/mcp/oauth/revoke` | Read the discovery document at startup rather than hard-coding the others. ## Permissions (scopes) Ask only for what your app uses. The member sees each one on the approval page. | Scope | Lets your app | Needed for | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------ | | `treechat:write` | Post and reply as the member | `POST /posts`, `GET /operations/{id}` | | `uploads:write` | Upload images, audio and video to the member's account | `POST /uploads` | | `treechat:read` | See the member's threads, including private ones | `GET /threads`, `GET /threads/{id}`, `GET /posts/{id}` | | `account:read` | See the member's ID and username | `GET /me` | Apps registered through App Connect can't request generation or billing scopes, and they can't spend the member's money. ## Authorization request Send the browser to the authorize endpoint with: | Parameter | Value | | ----------------------- | ---------------------------------------------- | | `response_type` | `code` | | `client_id` | Your client ID | | `redirect_uri` | One of your registered redirect URIs, exactly | | `scope` | Space-separated scopes | | `state` | A random value you check on return | | `code_challenge` | Base64url SHA-256 of your verifier, no padding | | `code_challenge_method` | `S256` (required; `plain` is refused) | | `resource` | `https://api.treechat.com/mcp` | On success Treechat redirects to `redirect_uri?code=…&state=…`. If the member declines, it redirects with `error=access_denied`. ## Token request `POST` form-encoded to the token endpoint. Authenticate with HTTP Basic (`client_id:client_secret`), or send `client_id` and `client_secret` in the body. ```bash curl -X POST https://api.treechat.com/mcp/oauth/token \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d grant_type=authorization_code \ -d code=CODE \ -d redirect_uri=https://yourapp.com/auth/treechat/callback \ -d code_verifier=VERIFIER \ -d resource=https://api.treechat.com/mcp ``` The response has `access_token`, `refresh_token`, `expires_in` (seconds) and `scope`. ## Using the token Send it on every API call: ```http Authorization: Bearer ACCESS_TOKEN ``` Cookies never authenticate API calls. ## Refreshing tokens Access tokens last **15 minutes**. Before or after one expires, trade the refresh token for a new pair: ```bash curl -X POST https://api.treechat.com/mcp/oauth/token \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d grant_type=refresh_token \ -d refresh_token=REFRESH_TOKEN ``` - Each refresh token works **once**. Store the new one from every response. - If two requests refresh at the same time, only one succeeds. Refresh from one place per member. - A connection that isn't used for **30 days** expires. The refresh then fails with `invalid_grant`, and the member has to connect again. ## Revoking and disconnects To sign a member out of your app, revoke the refresh token: ```bash curl -X POST https://api.treechat.com/mcp/oauth/revoke \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d token=REFRESH_TOKEN ``` Members can also disconnect your app from **Connected apps** in Treechat. That revokes every token and pending code for your app at once. Your next call gets `401`; send the member through the authorization flow again. ## Client secrets - The secret is shown once when you register or rotate it. Treechat stores only a hash. - Rotate it from your app's page if it leaks. The old secret stops working immediately. - Never put the secret in a browser or mobile app. ## Suspension Treechat can suspend an app that misbehaves. While suspended, every call made for anyone other than the app's developer returns `403` with code `app_suspended`. --- # API reference > Every App Connect REST endpoint with its permission, fields, responses and a curl example. Source: https://docs.treechat.com/developers/api-reference/ Base URL: `https://api.treechat.com/api/apps/v1` - Send `Authorization: Bearer ACCESS_TOKEN` on every request. - Request bodies are JSON (`Content-Type: application/json`). Responses are JSON with `Cache-Control: no-store`. - IDs are UUID strings. - Errors follow [the shared error format](https://docs.treechat.com/developers/limits-and-errors/#error-format). - A machine-readable copy of this page is at `https://api.treechat.com/api/apps/v1/openapi.json` (OpenAPI 3.1). | Method | Path | Scope | Does | | ------ | ------------------ | ---------------- | ------------------------------------------- | | `GET` | `/me` | `account:read` | The connected member | | `POST` | `/posts` | `treechat:write` | Start a thread, reply, or reply in a branch | | `GET` | `/operations/{id}` | `treechat:write` | Status of a post that returned `202` | | `POST` | `/uploads` | `uploads:write` | Get an upload URL for a file to attach | | `GET` | `/threads` | `treechat:read` | List threads | | `GET` | `/threads/{id}` | `treechat:read` | One thread with its posts | | `GET` | `/posts/{id}` | `treechat:read` | One post | ## GET /me ```bash curl https://api.treechat.com/api/apps/v1/me -H "Authorization: Bearer ACCESS_TOKEN" ``` `200`: ```json { "id": "af899143-90bc-4793-ba06-7f4655a0ef39", "username": "clip_fan", "space_id": "…" } ``` ## POST /posts Makes one post. Which kind depends on the fields you send. **Headers:** `Idempotency-Key` (required; see [retries](https://docs.treechat.com/developers/limits-and-errors/#retries-and-idempotency)). **Body fields:** | Field | Type | Use | | --------------------- | -------- | ------------------------------------------------------------------------------------ | | `content` | string | The text. Plain text; links are detected. | | `delta_json` | object | Rich text as a [Quill Delta](https://quilljs.com/docs/delta/), instead of `content`. | | `files` | string[] | `signed_id` values from [`POST /uploads`](#post-uploads). | | `thread_id` | string | Reply in this thread. | | `reply_to_post_id` | string | With `thread_id`: reply to this post in it. | | `branch_from_post_id` | string | Reply in this post's branch, starting the branch if it has none. | | `public` | boolean | New threads only. `true` makes the thread public. Default: private. | | `private` | boolean | New threads only. The opposite of `public`; send one or the other. | | `space_id` | string | New threads only. The community to post in; defaults to the member's. | At least one of `content`, `delta_json` or `files` is required. Unknown fields are refused with `422`. | You send | Result | | --------------------------------------- | ----------------------------- | | No `thread_id` or `branch_from_post_id` | A new thread | | `thread_id` | A reply in that thread | | `thread_id` + `reply_to_post_id` | A reply to that post | | `branch_from_post_id` | A reply in that post's branch | `branch_from_post_id` can't be combined with `thread_id` or `reply_to_post_id`. `public`, `private` and `space_id` are only for new threads. **Start a public thread with an image:** ```bash curl -X POST https://api.treechat.com/api/apps/v1/posts \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: episode-1" \ -d '{"content":"Episode 1 is live","files":["SIGNED_ID"],"public":true}' ``` **Start a branch off a post:** ```bash curl -X POST https://api.treechat.com/api/apps/v1/posts \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: episode-1-bts" \ -d '{"content":"Behind the scenes","branch_from_post_id":"POST_ID"}' ``` **Response** (`201` posted, `202` not confirmed yet): ```json { "operation_id": "5f0c…", "state": "completed", "thread_id": "72db5fc4-36bb-5c1e-b13e-9e68ec760d35", "post_id": "1b9e…" } ``` For a new thread, `thread_id` is the new thread and `post_id` its first post. For a reply or branch reply, `thread_id` is the thread (or branch) it landed in. ## GET /operations/{id} Checks a post that came back `202`. Only your app's operations for this member are visible. ```bash curl https://api.treechat.com/api/apps/v1/operations/OPERATION_ID -H "Authorization: Bearer ACCESS_TOKEN" ``` Returns the same shape as `POST /posts`: `200` when `completed`, `202` while pending, or the rejection error. ## POST /uploads Uploading a file takes three steps: 1. `POST /uploads` with the file's details. 2. `PUT` the raw bytes to the returned `upload.url`, sending exactly the returned `upload.headers`. Don't send your access token there. 3. Put the returned `signed_id` in a post's `files`. | Field | Type | Value | | -------------- | ------- | ------------------------------------------------------------- | | `filename` | string | For example `episode-1.png` | | `content_type` | string | MIME type, for example `image/png`, `video/mp4`, `audio/mpeg` | | `byte_size` | integer | Exact size in bytes | | `checksum` | string | Base64 of the file's MD5 digest | ```bash FILE=episode-1.png CHECKSUM=$(openssl dgst -md5 -binary "$FILE" | openssl base64) SIZE=$(wc -c < "$FILE" | tr -d ' ') curl -X POST https://api.treechat.com/api/apps/v1/uploads \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"filename\":\"$FILE\",\"content_type\":\"image/png\",\"byte_size\":$SIZE,\"checksum\":\"$CHECKSUM\"}" ``` `201`: ```json { "signed_id": "eyJfcmFpbHMiOnsi…", "upload": { "url": "https://storage.example/…", "headers": { "Content-Type": "image/png", "Content-MD5": "…" } } } ``` ```bash curl -X PUT "UPLOAD_URL" -H "Content-Type: image/png" -H "Content-MD5: CHECKSUM" --data-binary @episode-1.png ``` ## GET /threads Lists threads. Without parameters: threads the connected member started, newest first. | Parameter | Use | | ---------- | ---------------------------------------------------------------------------------------------------------- | | `user` | A username (with or without `@`), a user ID, or `me`: threads that person started that the member can see. | | `public` | `true`: the public feed instead. | | `order` | With `public=true`: `time` (default), `upvalue` or `upvalueTrending`. | | `before` | With `public=true` and `order=time`: the `next_cursor` from the previous page. | | `limit` | 1–100 for the public `time` feed (default 20); also used for member listings. | | `page` | Page number for member listings and ranked public orders. | | `space_id` | Limit to one community. | ```bash curl "https://api.treechat.com/api/apps/v1/threads?public=true&limit=10" -H "Authorization: Bearer ACCESS_TOKEN" ``` Every listing returns `{"threads": [...], "pagination": {...}}`. What's in `pagination` depends on how you page: | Listing | `pagination` | Next page | | ---------------------------------------- | ---------------------------------------- | -------------------- | | Member threads (`user` or no parameters) | `page`, `has_more` | `page` + 1 | | Public, `order=time` | `limit`, `next_cursor`, `has_more` | `before=next_cursor` | | Public, ranked orders | `page`, `limit`, `next_page`, `has_more` | `page=next_page` | Each thread object uses Treechat's existing thread JSON (see below). ## GET /threads/{id} ```bash curl https://api.treechat.com/api/apps/v1/threads/THREAD_ID -H "Authorization: Bearer ACCESS_TOKEN" ``` `200` returns `{"quest": {...}}`: the thread, with its posts under `answers`. A thread the member can't see returns `404`. ## GET /posts/{id} ```bash curl https://api.treechat.com/api/apps/v1/posts/POST_ID -H "Authorization: Bearer ACCESS_TOKEN" ``` `200` returns `{"answer": {...}}`: the post, with `quest_id` (its thread) and `child_quests` (branches growing from it). ## Thread and post JSON Read responses reuse the JSON Treechat's own apps use, so they're larger than the write responses and use older names: | In the JSON | Means | | -------------- | ----------------------------------- | | `quest` | A thread | | `answer` | A post | | `child_quests` | Branches that grow out of a post | | `delta_json` | A post's rich text as a Quill Delta | Treat unknown fields as optional; new ones may be added. --- # Limits and errors > Rate limits, the error format, every error code, and how to retry posts without duplicates. Source: https://docs.treechat.com/developers/limits-and-errors/ ## Limits | Limit | Value | | ----------------------------------- | ------------- | | Posts per connected member, per app | 30 a minute | | Posts per member, across all apps | 60 an hour | | API requests per access token | 300 a minute | | Upload size | 2 GB per file | | Uploads per member | 10 GB a day | | Apps per developer account | 5 | | Redirect URIs per app | 5 | ## Error format Every API error has the same JSON shape: ```json { "error": { "code": "invalid_arguments", "message": "content, delta_json or files is required" } } ``` Branch on `code`; `message` is for people and may change. | HTTP | `code` | Meaning | What to do | | ------- | -------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ | | 401 | `invalid_token` | Token missing, expired or revoked | Refresh the token; if that fails, reconnect the member | | 403 | `insufficient_scope` | The member didn't grant the scope this call needs | Ask for the scope in a new authorization | | 403 | `app_suspended` | Treechat suspended your app | Contact Treechat | | 404 | `not_found` | Doesn't exist, or the member can't see it | Don't retry | | 422 | `invalid_arguments` | A field is missing, unknown or invalid | Fix the request | | 409 | `idempotency_conflict` | The `Idempotency-Key` was already used for a different request | Use a new key for a new post | | 409 | `quote_expired`, `quote_consumed` | An internal step went stale | Retry with the same key | | 429 | `rate_limit_exceeded`, `daily_limit_reached` | A posting limit was hit | Wait, then retry with the same key | | 4xx | `rejected` | Treechat refused the post (for example, no access to that thread) | Read `message`; don't retry unchanged | | 4xx/5xx | `request_failed` | A read or upload failed | Retry reads; check upload fields | `401` and `403` responses also carry a `WWW-Authenticate: Bearer error="…"` header, with the needed `scope` on `insufficient_scope`. When the per-token request limit (300 a minute) is hit, the response is `429` with plain text `Retry later` and a `Retry-After` header in seconds, not the JSON shape above. ## Retries and idempotency Every `POST /posts` needs an `Idempotency-Key` header: 1 to 64 letters, digits, `.`, `_`, `:` or `-`. Pick one key per post you mean to make, for example `episode-42`. - **Same key, same body:** you get the original result back, never a second post. Retrying after a timeout is safe. - **Same key, different body:** `409 idempotency_conflict`. - Keys are per app and per member, so two members can use the same key. Post responses: | Status | `state` | Meaning | | ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `201` | `completed` | Posted. `thread_id` and `post_id` are final. | | `202` | `dispatching` or `uncertain` | Treechat hasn't confirmed it yet. Poll `GET /operations/{operation_id}` until `completed` or `rejected`. **Don't** retry with a new key; that could post twice. | | `4xx` | `rejected` | Not posted. See `error.message`. | `GET /operations/{id}` returns the same shape with `200` once completed. --- # Search Operators > Complete reference for Treechat search query syntax and operators Source: https://docs.treechat.com/reference/search-operators/ Treechat supports Google-style search syntax with powerful operators to filter and refine your search results. ## Quick Reference (TLDR) **Most commonly used operators:** - `from:username` - Filter by user - `stream:team_name` - Filter by channel/team - `has:video` / `has:image` / `has:url` - Filter by content type - `is:public` / `is:private` - Filter by visibility - `before:2025-10-01` / `after:2025-09-01` - Date ranges - `+"exact phrase"` / `-"unwanted"` - Required/excluded phrases - `upvote:>10` - Filter by upvote count - `sort:new` / `sort:hot` / `sort:top` - Sort results **Example:** `from:alice has:video sort:hot before:2025-10-01 +blockchain` --- ## User Filters ### from:username Filter quests by a specific user (case-insensitive username lookup). **Quote support:** Use quotes for usernames with spaces: `from:"User Name"` **Compound values:** Comma-separate usernames to OR them together. The operator always matches the parent author (the quest creator), not participants. **Examples:** - `from:alice` - All quests by user "alice" - `from:alice,bob` - Quests where alice OR bob is the parent author - `from:"John Doe","Jane Smith"` - Quests created by either quoted name - `from:bob bitcoin` - Quests by "bob" containing "bitcoin" --- ## Channel/Team Filters ### stream:team_name Filter by one or more teams/channels. Supports comma-separated values and special pseudostreams. **Quote support for names with spaces:** - `stream:"Team With Spaces"` - Single team with spaces - `stream:"Team A","Team B",unquoted` - Mixed quoted and unquoted channels **Standard channels:** - `stream:bitcoin` - Filter by "bitcoin" channel - `stream:bitcoin,ethereum` - Filter by multiple channels (OR logic) **Pseudostreams:** - `stream:public` or `stream:home` - Public feed pseudostream - `stream:private` - Private feed pseudostream - `stream:clips` or `stream:clip` - Clips pseudostream **Examples:** - `stream:bitcoin,ethereum artificial intelligence` - `stream:"Bitcoin Discussion",ethereum,"DeFi Projects"` - `stream:public has:video` - `stream:clips from:alice` **Error handling:** Returns error if channel name is not found or is ambiguous (multiple channels with same name in different spaces). --- ## Date Filters ### before:YYYY-MM-DD Filter quests created before the specified date. **Example:** `before:2025-10-01` - Quests before October 1, 2025 ### after:YYYY-MM-DD Filter quests created after the specified date. **Example:** `after:2025-09-01` - Quests after September 1, 2025 ### Date Ranges Combine both operators for date ranges. **Example:** `after:2025-09-01 before:2025-10-01` - Quests in September 2025 **Error handling:** Returns error for invalid date formats (e.g., `before:2025-13-45`). --- ## Content Type Filters ### has:video Filter quests that have video attachments. **Example:** `has:video machine learning` ### has:image Filter quests that have image attachments. **Example:** `has:image infographic` ### has:url or has:link Filter quests that contain URLs. This includes embedded tweets (tweets always have URLs). **Aliases:** `has:url` and `has:link` are equivalent **Example:** `has:url bitcoin` - Quests with links about bitcoin ### has:tweet Filter quests that have embedded tweets. **Example:** `has:tweet elon musk` ### has:media Filter quests with any media type (video OR image OR url OR tweet). This is a shorthand for combining all media filters. **Example:** `has:media` - Any quest with media content --- ## Visibility Filters ### is:public Filter to show only public quests. **Example:** `is:public has:video` ### is:private Filter to show only private quests. **Example:** `is:private has:image` ### is:clip Filter to show only clip quests. **Example:** `is:clip from:alice` --- ## Numeric Comparison Filters ### upvote:[operator]value Filter by upvote count with comparison operators. **Supported operators:** - `upvote:10` or `upvote:=10` - Exactly 10 upvotes - `upvote:>10` - More than 10 upvotes - `upvote:>=10` - 10 or more upvotes - `upvote:<10` - Less than 10 upvotes - `upvote:<=10` - 10 or fewer upvotes **Examples:** - `upvote:>=10 has:url` - Highly upvoted quests with URLs - `upvote:>100 bitcoin` - Popular bitcoin-related quests **Error handling:** Returns error for negative values or invalid numeric formats. ### upvalue:[operator]value Filter by BSV upvalue amount in satoshis. Uses the same comparison operators as upvote. **Supported operators:** Same as upvote (=, >, >=, <, <=) **Examples:** - `upvalue:>=1000` - Quests with 1000+ satoshis in upvalue - `upvalue:>5000 technology` - High-value technology quests **Error handling:** Returns error for negative values or invalid numeric formats. --- ## Sort Operators ### sort:new Sort results chronologically (newest first). **Aliases:** `sort:time`, `sort:recency` **Example:** `sort:new bitcoin` ### sort:relevance Sort by text relevance with engagement signals. **Aliases:** `sort:relev` **Example:** `sort:relevance artificial intelligence` ### sort:hot Sort using trending algorithm (time-decayed engagement). **Aliases:** `sort:trending` **Example:** `sort:hot cryptocurrency` ### sort:top Sort by most upvoted (uses BSV value if channel supports it). **Aliases:** `sort:upvote`, `sort:upvalue` **Example:** `sort:top has:video` **Note:** If multiple sort operators are present, the last one wins. --- ## Operator Logic ### Compound Search Logic **Within an operator (OR logic):** - `stream:A,B,C` - Returns quests from A OR B OR C - `from:alice,bob` - Returns quests where alice OR bob is the parent author - Multiple channels use OR logic: `stream:A,B` returns quests from channel A OR channel B **Between operators (AND logic):** - `stream:A from:user` - Returns quests in A AND by user - Multiple operators use AND logic: `stream:A from:user` returns quests in A AND by user **Example:** - `stream:bitcoin,ethereum from:alice` - Returns: Quests by alice in (bitcoin OR ethereum) - Logic: (channel=bitcoin OR channel=ethereum) AND from=alice --- ## Required/Excluded Content ### +"exact phrase" Require an exact phrase to be present in the quest. **Google behavior:** Quoted phrases are always MUST requirements unless prefixed with `-`. **Examples:** - `+"nakamoto consensus"` - Must contain this exact phrase - `+"climate change" policy` - Must have exact phrase, plus "policy" in any form ### -"unwanted phrase" Exclude quests containing this exact phrase. **Example:** `bitcoin -"price prediction"` - Bitcoin content without price predictions ### +requiredword Require a specific word to be present (unquoted). **Example:** `+bitcoin +blockchain technology` ### -excludedword Exclude quests containing a specific word (unquoted). **Example:** `cryptocurrency -scam -fraud` **Note:** You can combine multiple required and excluded terms: **Example:** `stream:bitcoin,ethereum +"nakamoto consensus" -scam +decentralization` --- ## Complex Quote and Compound Usage ### Mixed quoted and unquoted channels: ``` stream:"Bitcoin Discussion",ethereum,"DeFi Projects" ``` Searches three teams: "Bitcoin Discussion" (quoted), "ethereum" (unquoted), and "DeFi Projects" (quoted). ### Complex multi-operator search: ``` stream:"Team A","Team B",unquoted from:"User Name" has:video sort:hot ``` Finds videos from user "User Name" in any of the three teams, sorted by trending. ### Quote handling rules: - Use quotes when names contain spaces - Mix quoted and unquoted values in comma-separated lists - Quotes are optional for single-word names --- ## Complete Examples ### Example 1: User content with filters ``` from:alice has:video before:2025-10-01 ``` Finds all video quests by alice created before October 1, 2025. ### Example 2: Multi-channel search with requirements ``` stream:bitcoin,ethereum +"nakamoto consensus" -scam ``` Searches Bitcoin or Ethereum channels for content with exact phrase "nakamoto consensus", excluding anything with "scam". ### Example 3: Public video content ``` is:public has:video sort:hot ``` Shows trending public quests with videos. ### Example 4: Date range with popularity filter ``` upvote:>=10 has:url after:2025-09-01 sort:top artificial intelligence ``` Shows highly upvoted quests with URLs about AI from September 2025 onwards, sorted by upvotes. ### Example 5: Private images ``` is:private has:image from:bob ``` Shows private image quests from user bob. ### Example 6: Complex search with multiple operators ``` stream:technology upvote:>50 has:video +"machine learning" -hype after:2025-01-01 sort:relevance ``` Searches the technology channel for highly upvoted video quests with exact phrase "machine learning", excluding "hype", from 2025 onwards, sorted by relevance. --- ## Parsing Behavior ### Filter Extraction All operators are extracted from the query string. The remaining text becomes a free-form search query. **Example:** `from:alice bitcoin mining` → User filter: alice, Free-form query: "bitcoin mining" ### Case Sensitivity - User lookups: Case-insensitive - Team/channel lookups: Case-insensitive - Filter keywords: Case-insensitive - Free-form search text: Preserves original case (analyzed by Elasticsearch) ### Caching User and team lookups are cached per request for performance. ### Ambiguity Resolution Channel names require space_id for disambiguation since multiple spaces may have channels with the same name. Ambiguous channel names return an error. --- ## Error Handling The parser returns HTTP 400 errors for: - **User not found:** `from:nonexistent_user` - **Channel not found:** `stream:invalid_name` - **Ambiguous channel:** `stream:name` (when multiple matches exist) - **Invalid date format:** `before:2025-13-45` - **Invalid numeric value:** `upvote:notanumber` - **Negative numeric values:** `upvote:-5` All errors are returned to the client with descriptive error messages.