# Felo API Platform Full LLM Context Build search, agent, document, and model-powered applications with Felo API Platform. ## Canonical URLs - Website: https://openapi.felo.ai - Models: https://openapi.felo.ai/models - Harness: https://openapi.felo.ai/harness - APIs: https://openapi.felo.ai/apis - API categories: https://openapi.felo.ai/apis/office, https://openapi.felo.ai/apis/marketing, https://openapi.felo.ai/apis/search, https://openapi.felo.ai/apis/social, https://openapi.felo.ai/apis/seo, https://openapi.felo.ai/apis/finance - Documentation: https://openapi.felo.ai/docs - Seedance video: https://openapi.felo.ai/seedance - Pricing: https://openapi.felo.ai/pricing ## Model APIs ### Claude Haiku 5.5 - URL: https://openapi.felo.ai/models/anthropic/claude-haiku-5.5 - Model ID: claude-haiku-5-5 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 1M - Max output: 128K - Pricing: $0.1/1M input tokens, $0.5/1M output tokens - Long context (over 100000 tokens): $0.5/1M input tokens, $2.5/1M output tokens - Best for: High-throughput chat, Classification, Extraction, Fast agent loops - Description: Anthropic's Haiku-class route, succeeding Claude Haiku 4.5 as the fast tier of the Claude 5.5 family. It is built for high-volume and latency-sensitive workloads such as support bots, classification, extraction, and search-backed answers, and pairs a 1M-token context window with cache read and cache-write rates that keep high-throughput loops affordable. ### GPT-6.1 Sol - URL: https://openapi.felo.ai/models/openai/gpt-6.1-sol - Model ID: gpt-6.1-sol - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $2/1M input tokens, $10/1M output tokens - Best for: Agentic coding, Computer use, Workflow automation, Document-heavy work - Description: An upgrade to GPT-6 Sol, still positioned below the flagship GPT-6 Astra. It handles agentic coding, computer use, document-heavy professional work, and multi-step workflow automation, approaching Astra-level results on those tasks at a much lower cost, with fewer factual errors and closer adherence to explicit restrictions than GPT-6 Sol. Cache reads are billed at half of GPT-6 Sol's rate. ### GPT-6.1 Sol Pro - URL: https://openapi.felo.ai/models/openai/gpt-6.1-sol-pro - Model ID: gpt-6.1-sol-pro - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $2/1M input tokens, $10/1M output tokens - Best for: Deep reasoning, Complex coding, High-stakes analysis, Agent planning - Description: The same underlying model as GPT-6.1 Sol, served with reasoning mode set to pro for higher-quality responses on complex tasks. Choose it when accuracy matters more than latency. ### Claude Sonnet 5.5 - URL: https://openapi.felo.ai/models/anthropic/claude-sonnet-5.5 - Model ID: claude-sonnet-5-5 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 1M - Max output: 128K - Pricing: $2/1M input tokens, $10/1M output tokens - Best for: Feature development, Bug fixing, Everyday coding, High-volume agent loops - Description: Anthropic's Sonnet-class route for well-scoped everyday work, succeeding Claude Sonnet 5 as a direct upgrade. It is strongest at building features and fixing bugs, and pairs a 1M-token context window with cache read and cache-write rates that keep high-volume agent loops affordable. ### Claude Opus 5.5 - URL: https://openapi.felo.ai/models/anthropic/claude-opus-5.5 - Model ID: claude-opus-5-5 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 1M - Max output: 128K - Pricing: $4/1M input tokens, $20/1M output tokens - Best for: Long-horizon agents, Complex coding, Deep reasoning, Large codebases - Description: Anthropic's flagship route for multi-step changes in large codebases, long-horizon agentic work, and demanding reasoning. It pairs a 1M-token context window with cached input and cache-write rates for production agent loops. ### GPT-6 Luna - URL: https://openapi.felo.ai/models/openai/gpt-6-luna - Model ID: gpt-6-luna - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $0.1/1M input tokens, $0.5/1M output tokens - Best for: High-volume chat, Classification, Fast agent loops, Cost-sensitive apps - Description: The fast, cost-efficient tier of the GPT-6 series, positioned below GPT-6 Sol. It is suited for high-volume and latency-sensitive workloads such as chat, classification, and lightweight agentic loops. ### GPT-6 Luna Pro - URL: https://openapi.felo.ai/models/openai/gpt-6-luna-pro - Model ID: gpt-6-luna-pro - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $0.1/1M input tokens, $0.5/1M output tokens - Best for: Reasoning on a budget, Batch analysis, Extraction, Agent subtasks - Description: The same underlying model as GPT-6 Luna, served with reasoning mode set to pro for higher-quality responses on complex tasks. It keeps Luna's low token pricing while trading latency for accuracy. ### GPT-6 Sol - URL: https://openapi.felo.ai/models/openai/gpt-6-sol - Model ID: gpt-6-sol - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $2/1M input tokens, $10/1M output tokens - Best for: Professional work, Coding agents, Reasoning tasks, Long-context analysis - Description: The cost-efficient high-end tier of the GPT-6 series, positioned below the flagship GPT-6 Astra and above the fast GPT-6 Luna route. It is built for demanding professional workloads that need strong reasoning without flagship pricing. ### GPT-6 Sol Pro - URL: https://openapi.felo.ai/models/openai/gpt-6-sol-pro - Model ID: gpt-6-sol-pro - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $2/1M input tokens, $10/1M output tokens - Best for: Deep reasoning, Complex coding, High-stakes analysis, Agent planning - Description: The same underlying model as GPT-6 Sol, served with reasoning mode set to pro for higher-quality responses on complex tasks. Choose it when accuracy matters more than latency. ### Grok 4.7 - URL: https://openapi.felo.ai/models/x-ai/grok-4.7 - Model ID: grok-4-7 - Provider: xAI - Category: LLM - Protocol: chat-completions - Context: 500K - Max output: 450K - Pricing: $1.6/1M input tokens, $4.8/1M output tokens - Best for: Long-running coding, Self-verifying agents, Knowledge work, Research - Description: The flagship Grok route for coding, agentic tasks, and knowledge work. It is particularly strong at long-running software engineering tasks, verifying its own work, and large-context analysis, with text, image, and file input. ### MiMo V2.6 Pro - URL: https://openapi.felo.ai/models/xiaomi/mimo-v2.6-pro - Model ID: mimo-v2.6-pro - Provider: Xiaomi - Category: LLM - Protocol: chat-completions - Context: 1M - Max output: 128K - Pricing: $0.435/1M input tokens, $0.87/1M output tokens - Best for: Multimodal reasoning, Agentic tasks, Long-context analysis, Video understanding - Description: Xiaomi's flagship foundation model, built at a scale of over 1T parameters to push the ceiling of capability on the most demanding tasks. It accepts text, image, audio, and video input with a 1M-token context window. ### DeepSeek V4.1 Flash - URL: https://openapi.felo.ai/models/deepseek/deepseek-v4.1-flash - Model ID: deepseek-v4.1-flash - Provider: DeepSeek - Category: LLM - Protocol: responses - Context: 1M - Max output: 384K - Pricing: $0.15/1M input tokens, $0.6/1M output tokens - Best for: Long-context reasoning, Fast agent loops, Cost-sensitive coding, Structured output - Description: A sparse mixture-of-experts model from DeepSeek and the first built on the company's Causal Encoder-Decoder architecture. It activates a small fraction of parameters per token, keeping long-context reasoning fast and inexpensive. ### GPT-6 Astra - URL: https://openapi.felo.ai/models/openai/gpt-6-astra - Model ID: gpt-6-astra - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $10/1M input tokens, $50/1M output tokens - Best for: Complex reasoning, Agentic coding, Computer use, Professional work - Description: OpenAI's most capable model, built for the hardest end-to-end work: complex reasoning, agentic coding, computer use, web research, and professional document creation. 1.05M context window with cached input and cache-write rates. ### GLM 5.3 Flash - URL: https://openapi.felo.ai/models/z-ai/glm-5.3-flash - Model ID: glm-5.3-flash - Provider: Z.AI - Category: LLM - Protocol: chat-completions - Context: 1M - Max output: 48K - Pricing: $0.15/1M input tokens, $0.5/1M output tokens - Best for: Long-context coding, Agent workflows, Multimodal tasks, Cost-efficient chat - Description: Z.AI's open-weight Flash route with a 1M-token context, native text, image, and video input, and hybrid sparse attention that keeps long-context accuracy while cutting compute cost. ### OX Alpha - URL: https://openapi.felo.ai/models/stealth/ox-alpha - Model ID: ox-alpha - Provider: Stealth - Category: LLM - Protocol: chat-completions - Context: 1M - Max output: 128K - Pricing: $0/1M input tokens, $0/1M output tokens - Best for: Long-horizon coding, Complex reasoning, Agent workflows, Multimodal tasks - Description: A stealth frontier reasoning route with a 1M-token context and text, image, and video input, built for long-horizon coding, complex reasoning, and production agent workflows. ### Seedance 2.0 Mini - URL: https://openapi.felo.ai/models/bytedance/seedance-2.0-mini - Model ID: seedance-2.0-mini - Provider: ByteDance - Category: Video generation - Resolutions: 480p, 720p - Duration: 4-15 seconds - Aspect ratios: 1:1, 3:4, 9:16, 4:3, 16:9, 21:9, 9:21 - Input modes: text, first-last-frame, omni-reference - Audio: included - Pricing: 480p $0.03363/s, 720p $0.0756/s - Best for: Low-cost video, High-volume generation, Reference-to-video, Social clips - Description: The most affordable Seedance route, supporting text-to-video, first and last frame control, and multimodal reference-to-video with image, video, and audio inputs. It renders 480p and 720p clips between 4 and 15 seconds. ### Seedance 2.5 - URL: https://openapi.felo.ai/models/bytedance/seedance-2.5 - Model ID: seedance-2.5 - Provider: ByteDance - Category: Video generation - Resolutions: 480p, 720p - Duration: 4-30 seconds - Aspect ratios: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 - Input modes: text, first-last-frame, omni-reference - Audio: included - Pricing: 480p $0.1028/s, 720p $0.2311/s - Best for: Long-form video, Video editing, Video extension, Multilingual audio - Description: ByteDance's newest Seedance route, built for long-form storytelling, multimodal reference-based generation, video editing, and video extension. It accepts up to 50 image, video, and audio reference assets, renders clips up to 30 seconds, and supports multilingual audiovisual generation. ### GPT-5.6 Luna - URL: https://openapi.felo.ai/models/openai/gpt-5.6-luna - Model ID: gpt-5.6-luna - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 400K - Max output: 128K - Pricing: $1/1M input tokens, $6/1M output tokens - Best for: Fast agent loops, High-volume chat, Extraction, Cost-sensitive coding - Description: The efficient GPT-5.6 tier for fast coding loops, chat, extraction, search synthesis, and high-volume agent workflows. ### GPT-5.6 Sol - URL: https://openapi.felo.ai/models/openai/gpt-5.6-sol - Model ID: gpt-5.6-sol - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $5/1M input tokens, $30/1M output tokens - Best for: Flagship reasoning, Advanced coding, Long-context analysis, Agent orchestration - Description: The flagship GPT-5.6 tier for complex reasoning, advanced coding, long-context analysis, and high-capability agent workflows. ### GPT-5.6 Terra - URL: https://openapi.felo.ai/models/openai/gpt-5.6-terra - Model ID: gpt-5.6-terra - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $2.5/1M input tokens, $15/1M output tokens - Best for: Coding, Agent workflows, Balanced reasoning, Tool use - Description: The balanced GPT-5.6 tier for production coding agents, reasoning tasks, tool use, and multi-step app workflows. ### Grok 4.5 - URL: https://openapi.felo.ai/models/x-ai/grok-4.5 - Model ID: grok-4.5 - Provider: xAI - Category: LLM - Protocol: chat-completions - Context: 500K - Max output: - - Pricing: $2/1M input tokens, $6/1M output tokens - Best for: Research, Analysis, Coding assistance, Agent workflows - Description: A high-capability model route for research, analysis, coding assistance, and agent workflows that benefit from a large context window. ### Claude Sonnet 5 - URL: https://openapi.felo.ai/models/anthropic/claude-sonnet-5 - Model ID: claude-sonnet-5 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 1M - Max output: 128K - Pricing: $2/1M input tokens, $10/1M output tokens - Best for: Default model route, Assistant apps, Coding, Knowledge workflows - Description: A strong default for modern applications that need long context, tool use, structured output, and reliable streaming responses. ### Claude Opus 4.8 - URL: https://openapi.felo.ai/models/anthropic/claude-opus-4-8 - Model ID: claude-opus-4-8 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 1M - Max output: 128K - Pricing: $5/1M input tokens, $25/1M output tokens - Best for: Deep analysis, Complex coding, Strategy work, Long-horizon agents - Description: A premium route for complex planning, multi-step analysis, high-stakes content generation, and advanced software engineering assistance. ### DeepSeek V4 Flash - URL: https://openapi.felo.ai/models/deepseek/deepseek-v4-flash - Model ID: deepseek-v4-flash - Provider: DeepSeek - Category: LLM - Protocol: responses - Context: 1M - Max output: 384K - Pricing: $0.09/1M input tokens, $0.18/1M output tokens - Best for: Fast agent loops, Long-context tasks, Structured output, Tool workflows - Description: A cost-efficient DeepSeek route for agent loops, coding, structured output, and tool use with a 1M-token context window and selectable thinking modes. ### GPT-5.5 - URL: https://openapi.felo.ai/models/openai/gpt-5.5 - Model ID: gpt-5.5 - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $5/1M input tokens, $30/1M output tokens - Best for: Coding agents, Reasoning tasks, Research workflows, App assistants - Description: A strong general-purpose model route for coding, reasoning, research, and production agent workloads through Responses and Chat Completions compatible APIs. ### GPT-5.5 Pro - URL: https://openapi.felo.ai/models/openai/gpt-5.5-pro - Model ID: gpt-5.5-pro - Provider: OpenAI - Category: LLM - Protocol: responses - Context: 1.05M - Max output: 128K - Pricing: $30/1M input tokens, $180/1M output tokens - Best for: Deep reasoning, Complex coding, Planning, High-value analysis - Description: A premium model route for deep reasoning, complex software engineering, long-horizon planning, and high-value agent workflows. ### MiMo V2.5 Pro - URL: https://openapi.felo.ai/models/xiaomi/mimo-v2.5-pro - Model ID: mimo-v2.5-pro - Provider: Xiaomi - Category: LLM - Protocol: chat-completions - Context: 1.05M - Max output: 128K - Pricing: $0.435/1M input tokens, $0.87/1M output tokens - Best for: Software engineering, Long-horizon agents, Reasoning, Cost-sensitive workloads - Description: Xiaomi's flagship text route, delivering strong performance in general agentic capabilities, complex software engineering, and long-horizon tasks, with top rankings on benchmarks such as ClawEval, GDPVal, and SWE-bench Pro. ### Seedance 2.0 - URL: https://openapi.felo.ai/models/bytedance/seedance-2.0 - Model ID: seedance-2.0 - Provider: ByteDance - Category: Video generation - Resolutions: 480p, 720p, 1080p, 4K - Duration: 4-15 seconds - Aspect ratios: 1:1, 3:4, 9:16, 4:3, 16:9, 21:9, 9:21 - Input modes: text, first-last-frame, omni-reference - Audio: included - Pricing: 480p $0.06725/s, 720p $0.1512/s, 1080p $0.3742/s, 4K $0.7776/s - Best for: Text to video, Character consistency, Style transfer, 4K output - Description: ByteDance's flagship Seedance route for text-to-video, first and last frame control, and multimodal reference-to-video. It is particularly strong at preserving character consistency, visual style, and camera movement from reference material, and it is the only Seedance route here that renders up to 4K. ### Seedance 2.0 Fast - URL: https://openapi.felo.ai/models/bytedance/seedance-2.0-fast - Model ID: seedance-2.0-fast - Provider: ByteDance - Category: Video generation - Resolutions: 480p, 720p - Duration: 4-15 seconds - Aspect ratios: 1:1, 3:4, 9:16, 4:3, 16:9, 21:9, 9:21 - Input modes: text, first-last-frame, omni-reference - Audio: included - Pricing: 480p $0.04035/s, 720p $0.09072/s - Best for: Fast iteration, Cost-sensitive video, Reference-to-video, Draft renders - Description: A faster, lower-cost Seedance route for text-to-video, first and last frame control, and multimodal reference-to-video. It prioritizes generation speed and cost over maximum output quality, and renders up to 720p. ### Claude Sonnet 4.6 - URL: https://openapi.felo.ai/models/anthropic/claude-sonnet-4-6 - Model ID: claude-sonnet-4-6 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 1M - Max output: 128K - Pricing: $3/1M input tokens, $15/1M output tokens - Best for: Agent tasks, Code generation, Long documents, Research workflows - Description: A general-purpose flagship route for agent workflows, long document understanding, coding assistance, and production-grade reasoning. ### Claude Haiku 4.5 - URL: https://openapi.felo.ai/models/anthropic/claude-haiku-4-5 - Model ID: claude-haiku-4-5 - Provider: Anthropic - Category: LLM - Protocol: messages - Context: 200K - Max output: 64K - Pricing: $1/1M input tokens, $5/1M output tokens - Best for: High-throughput chat, Classification, Extraction, Search summaries - Description: A compact, responsive model route for support bots, extraction, classification, and search-backed answers where latency matters. ## Seedance Video ### Seedance video generator - URL: https://openapi.felo.ai/seedance - Resolutions: 480p–4K - Clip length: 4–30 seconds - Seedance 2.5 (seedance-2.5): 480p, 720p; 4-30 seconds; text, first-last-frame, omni-reference; from $0.1028/s - Seedance 2.0 (seedance-2.0): 480p, 720p, 1080p, 4K; 4-15 seconds; text, first-last-frame, omni-reference; from $0.06725/s - Seedance 2.0 Fast (seedance-2.0-fast): 480p, 720p; 4-15 seconds; text, first-last-frame, omni-reference; from $0.04035/s - Seedance 2.0 Mini (seedance-2.0-mini): 480p, 720p; 4-15 seconds; text, first-last-frame, omni-reference; from $0.03363/s - Submit: POST https://openapi.felo.ai/api/v1/videos/generations (returns a task id) - Poll: GET https://openapi.felo.ai/api/v1/videos/generations/{task_id} ## Harness APIs ### Search API - URL: https://openapi.felo.ai/harness#search-api - Docs: https://openapi.felo.ai/docs/api-reference/chat - Tags: API, Search, Agent - Description: Real-time web search and answer generation for agents, research tools, support bots, and content workflows. - Billing: Credit note: Pro Search starts from 15 credits per request. ### PPT Task API - URL: https://openapi.felo.ai/harness#ppt-task-api - Docs: https://openapi.felo.ai/docs/api-reference/ppt-tasks - Tags: API, Office, Async Task - Description: Generate slide decks asynchronously from prompts, themes, and optional LiveDoc context, then poll task status and retrieve results. - Billing: Credit note: AI Slide generation starts from 30 credits per page during promotion. Theme listing does not create a generation task. ### SuperAgent API - URL: https://openapi.felo.ai/harness#superagent-api - Docs: https://openapi.felo.ai/docs/api-reference/superagent - Tags: API, SSE, LiveDoc - Description: Create streaming agent conversations, consume SSE output, follow up inside the same thread, and attach LiveDoc context. - Billing: Credit note: Conversation cost depends on selected skill, output length, model usage, and attached tools. ### Web Fetch API - URL: https://openapi.felo.ai/harness#web-fetch-api - Docs: https://openapi.felo.ai/docs/api-reference/web-fetch - Tags: API, Extraction, Markdown - Description: Extract webpage content as HTML, text, or Markdown with crawl mode, readability, selector, and timeout options. - Billing: Credit note: Usage depends on crawl mode, target page, and extraction options. ### X Search API - URL: https://openapi.felo.ai/harness#x-search-api - Docs: https://openapi.felo.ai/docs/api-reference/x-search - Tags: API, X, Social Data - Description: Search X users, tweets, timelines, and replies with pagination metadata for research, monitoring, and content agents. - Billing: Credit note: X post search is currently available with limited-time free usage where supported. ### Mindmap API - URL: https://openapi.felo.ai/harness#mindmap-api - Docs: https://openapi.felo.ai/docs/api-reference/mindmap - Tags: API, Creation, LiveDoc - Description: Create structured mindmaps from a topic, question, or optional LiveDoc context for planning and research workflows. - Billing: Credit note: AI Mindmap generation starts from 15 credits per request. LiveDoc AI Mindmap may have limited-time free usage. ### Landing Page Task API - URL: https://openapi.felo.ai/harness#landing-page-api - Docs: https://openapi.felo.ai/docs/api-reference/landing-page - Tags: API, Page, Async Task - Description: Generate landing page content asynchronously, query task history, and retrieve generated HTML results for campaign workflows. - Billing: Credit note: AI Page generation starts from 375 credits per request. Regeneration may consume additional credits. ### LiveDoc API - URL: https://openapi.felo.ai/harness#livedoc-api - Docs: https://openapi.felo.ai/docs/api-reference/livedocs - Tags: API, Knowledge Base, Retrieval - Description: Create knowledge bases, upload resources, import URLs, and run semantic retrieval for context-aware agents. - Billing: Credit note: Knowledge Base Search starts from 15 credits per request. File and retrieval usage depends on resource size. ### YouTube Subtitling API - URL: https://openapi.felo.ai/harness#youtube-subtitling-api - Docs: https://openapi.felo.ai/docs/api-reference/youtube-subtitling - Tags: API, Video, Transcript - Description: Fetch YouTube subtitles by video code with optional language and timestamp parameters for media research agents. - Billing: Credit note: Usage depends on transcript availability, language selection, and request volume. ## Aggregated APIs ### Felo API - URL: https://openapi.felo.ai/apis/felo - Category: Office, Marketing - Endpoints: 17 - Description: Search-grounded chat, model access, asynchronous document generation and LiveDoc knowledge bases. - Groups: Core AI (4), Generation Tasks (5), Agents and Knowledge (4), Search and Extraction (4) ### Similarweb API - URL: https://openapi.felo.ai/apis/similarweb - Category: SEO - Endpoints: 23 - Description: Traffic estimates, audience composition, rankings and referral sources. - Groups: website (15), search (5), website-top-geographies (1), website-traffic-snapshot (1), website-traffic-trend (1) ### Semrush API - URL: https://openapi.felo.ai/apis/semrush - Category: SEO - Endpoints: 19 - Description: Domain analytics, keyword rankings, traffic estimates and competitor research. - Groups: backlink-anchors (1), backlink-competitors (1), backlinks (1), backlinks-overview (1), broad-match-keywords (1), domain-organic-competitors (1), domain-organic-keywords (1), domain-overview (1), domain-paid-keywords (1), domain-rank-history (1), domain-vs-domain (1), indexed-pages (1), keyword-difficulty (1), keyword-organic-results (1), keyword-overview (1), keyword-paid-results (1), question-keywords (1), referring-domains (1), url-organic-keywords (1) ### Ahrefs API - URL: https://openapi.felo.ai/apis/ahrefs - Category: SEO - Endpoints: 2 - Description: Backlink indexes, referring domains, organic keywords and site health. - Groups: site-explorer (2) ### DataForSEO API - URL: https://openapi.felo.ai/apis/dataforseo - Category: SEO - Endpoints: 445 - Description: SEO, search-engine results, keyword research, backlinks and AI visibility data. - Groups: serp (154), keywords_data (48), business_data (42), ai_optimization (37), dataforseo_labs (37), merchant (30), app_data (29), on_page (25), backlinks (21), domain_analytics (12), content_analysis (10) ### Apollo API - URL: https://openapi.felo.ai/apis/apollo - Category: Marketing - Endpoints: 8 - Description: Company and contact records for go-to-market and prospecting. - Groups: organizations (4), people (2), mixed_people (1), news_articles (1) ### Creator Discovery API - URL: https://openapi.felo.ai/apis/creator-discovery - Category: Social - Endpoints: 2 - Description: Creator contact emails from a profile URL, and similar-creator discovery. - Groups: email-lookup (1), similar (1) ### Tavily API - URL: https://openapi.felo.ai/apis/tavily - Category: Search - Endpoints: 4 - Description: Web search, page extraction and site crawling for agents. - Groups: crawl (1), extract (1), map (1), search (1) ### Firecrawl API - URL: https://openapi.felo.ai/apis/firecrawl - Category: Search - Endpoints: 8 - Description: Turn sites into clean markdown, structured data or screenshots. - Groups: batch-scrape (2), crawl (2), map (1), parse (1), scrape (1), search (1) ### Oxylabs API - URL: https://openapi.felo.ai/apis/oxylabs - Category: Search - Endpoints: 1 - Description: Query an AI answer engine to see how a page shows up in AI-generated answers. - Groups: ai-search (1) ### X API - URL: https://openapi.felo.ai/apis/x - Category: Social - Endpoints: 29 - Description: Query public users, posts, communities and trends. - Groups: user (10), tweet (6), community (5), list (3), article (1), spaces (1), trends (1), tweets (1), user_about (1) ### Reddit API - URL: https://openapi.felo.ai/apis/reddit - Category: Social - Endpoints: 5 - Description: Subreddit posts, comment threads, user profiles and search. - Groups: subreddit (3), post (1), search (1) ### Instagram API - URL: https://openapi.felo.ai/apis/instagram - Category: Social - Endpoints: 15 - Description: Public profiles, posts, reels, comments and hashtag activity. - Groups: user (5), post (2), reels (2), search (2), basic-profile (1), media (1), profile (1), song (1) ### Pinterest API - URL: https://openapi.felo.ai/apis/pinterest - Category: Social - Endpoints: 4 - Description: Public pins, boards, profiles and visual search results. - Groups: board (1), pin (1), search (1), user (1) ### Exa API - URL: https://openapi.felo.ai/apis/exa - Category: Search - Endpoints: 5 - Description: Neural and keyword web search with page contents returned. - Groups: agent (2), answer (1), contents (1), search (1) ### BytePlus API - URL: https://openapi.felo.ai/apis/byteplus - Category: Search - Endpoints: 2 - Description: Real-time web search and clean, structured page content. - Groups: fetch (1), web-search (1) ### Anthropic Web Search API - URL: https://openapi.felo.ai/apis/anthropic-web-search - Category: Search - Endpoints: 1 - Description: Web search with citations, using Anthropic's own search tool. - Groups: search (1) ### OpenAI Web Search API - URL: https://openapi.felo.ai/apis/openai-web-search - Category: Search - Endpoints: 1 - Description: Web search grounded by OpenAI's own search tool. - Groups: search (1) ### Financial Data API - URL: https://openapi.felo.ai/apis/financial - Category: Finance & markets - Endpoints: 19 - Description: Company fundamentals, financial statements, market prices and economic data. - Groups: financials (6), filings (2), financial-metrics (2), macro (2), prices (2), analyst-estimates (1), company (1), earnings (1), insider-trades (1), news (1) ### EDINET API - URL: https://openapi.felo.ai/apis/edinet - Category: Finance & markets - Endpoints: 2 - Description: Japanese statutory filings: list disclosure documents or download one by ID. - Groups: documents (1), documents.json (1) ### YouTube API - URL: https://openapi.felo.ai/apis/youtube - Category: Social - Endpoints: 1 - Description: Video search, channel and playlist data, comments and transcripts. - Groups: search (1) ### Scholar Search API - URL: https://openapi.felo.ai/apis/scholar-search - Category: Search - Endpoints: 4 - Description: Academic paper search, web-and-scholar combined results, and result explanations. - Groups: search (4) ### Kalshi API - URL: https://openapi.felo.ai/apis/kalshi - Category: Finance & markets - Endpoints: 2 - Description: Event contract markets: prices, order books and settlement outcomes. - Groups: markets (1), trades (1) ### Perplexity API - URL: https://openapi.felo.ai/apis/perplexity - Category: Search - Endpoints: 4 - Description: Answer-engine results with sources and related questions. - Groups: sonar (1), sonar-deep-research (1), sonar-pro (1), sonar-reasoning-pro (1) ### Polymarket API - URL: https://openapi.felo.ai/apis/polymarket - Category: Finance & markets - Endpoints: 3 - Description: Prediction market prices, order books and resolved outcomes. - Groups: activity (1), events (1), markets (1) ### CoinGecko API - URL: https://openapi.felo.ai/apis/coingecko - Category: Finance & markets - Endpoints: 22 - Description: Cryptocurrency prices, market capitalization, exchanges and token data. - Groups: coins (13), exchanges (4), simple (3), news (1), search (1) ## Documentation Content # Getting Started URL: https://openapi.felo.ai/docs/getting-started Description: Get one API key, choose an AI tool, open its setup guide, and run your first workflow API call. # Getting Started Felo API Platform gives you one key for agent tools, model protocols, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. Start here, pick the tool you use, then follow that tool's dedicated setup guide. ## Quick Start Flow 1. Get one Felo API Platform key, or buy a plan if you need more quota. 2. Choose your AI tool or platform from the table below. 3. Open the matching setup guide and paste in the Felo base URL and API key. 4. Run a small task in that tool to confirm the connection. 5. Add workflow APIs when your agent needs search, office output, web extraction, image workflows, LiveDocs, or SuperAgent. ## Step 1: Get Your API Key Felo API Platform uses one API key across direct API calls and supported AI tools. 1. Open the [Felo API Platform API Keys page](/settings/api-keys). 2. Sign in with your Felo account if prompted. 3. Enter a key name and click **Create Key**. 4. Copy the full key when it appears. It is only shown once. 5. Store the key securely and use it as `FELO_API_KEY`. You can start with a free-to-try key. If your workflow needs higher usage, more model access, or team usage, choose a paid plan from your Felo account. ::: warning Keep your API key secret Do not commit your API key to Git, expose it in frontend code, paste it into public logs, or share it with other users. Treat it like a password. ::: Set the key as an environment variable: ```bash export FELO_API_KEY="YOUR_API_KEY" ``` Windows PowerShell: ```powershell $env:FELO_API_KEY="YOUR_API_KEY" ``` ## Step 2: Choose Your AI Tool Click the tool you want to use. Each link opens a dedicated setup guide with the right base URL, environment variables, and verification step. | Tool | Best for | Setup guide | |------|----------|-------------| | Codex | CLI coding workflows, code review, repo changes, and automation | [Set up Codex](/docs/agent-clients/codex) | | Claude Code | Agent coding, repo editing, research-assisted development, and long-context work | [Set up Claude Code](/docs/agent-clients/claude-code) | | OpenCode | Terminal coding sessions and OpenAI-compatible provider routing | [Set up OpenCode](/docs/agent-clients/opencode) | | OpenClaw | Personal AI assistant workflows and local agents | [Set up OpenClaw](/docs/agent-clients/openclaw) | | Hermes Agent | Agent experiments and multi-tool orchestration | [Set up Hermes Agent](/docs/agent-clients/hermes-agent) | | TRAE | AI IDE workflows and assisted editing | [Set up TRAE](/docs/agent-clients/trae) | | OpenViking | Agent experiments and provider switching | [Set up OpenViking](/docs/agent-clients/openviking) | | Cursor | AI coding inside an editor | [Set up Cursor](/docs/agent-clients/cursor) | | Cline | VS Code agent workflows and terminal-assisted coding | [Set up Cline](/docs/agent-clients/cline) | | Roo Code | VS Code coding agents and task planning | [Set up Roo Code](/docs/agent-clients/roo-code) | | Kilo Code | Local coding agents and model-provider testing | [Set up Kilo Code](/docs/agent-clients/kilo-code) | | Other AI tools | Any client that accepts a custom API key, base URL, and model name | [Set up other tools](/docs/agent-clients/other-tools) | ## Step 3: Use the Right Base URL Most tools ask for three values: API key, base URL, and model name. Choose the base URL based on the protocol that the tool supports. | Tool asks for | Use this value | |---------------|----------------| | API key | Your `FELO_API_KEY` | | OpenAI-compatible base URL | `https://openapi.felo.ai/api/v1` | | Anthropic-compatible base URL | `https://openapi.felo.ai/api` | | Default coding model | `claude-sonnet-4-6` | | Optional newer model | `claude-sonnet-5` if it is available in your account | If you are not sure which mode your client supports, start with the OpenAI-compatible base URL. Use the Anthropic-compatible base URL for Claude Code or clients that explicitly ask for an Anthropic Messages endpoint. ## Step 4: Verify with a Direct API Call If you only want to confirm that your key works, call the Chat API directly. ```bash curl -X POST https://openapi.felo.ai/v2/chat \ -H "Authorization: Bearer $FELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Research the latest AI agent product trends" }' ``` A successful response includes an answer, query analysis, and web resources. ```json { "status": "ok", "data": { "id": "HabCj883yHLSXc8mWqu4Eq", "message_id": "18ea8517-5559-4f48-a355-1f8a79e73b71", "answer": "...", "query_analysis": { "queries": ["AI agent product trends"] }, "resources": [ { "link": "https://example.com/report", "title": "AI Agent Market Report", "snippet": "..." } ] } } ``` ::: tip Setup complete If you receive a response with `status: "ok"`, your API key and network setup are working. ::: ## Step 5: Add Workflow APIs After your first tool or API call works, connect the APIs that match your scenario. | Scenario | Recommended APIs | Docs | |----------|------------------|------| | Search and research agent | Chat, Web Fetch, X Search, YouTube Subtitling, LiveDocs | [Chat API](/docs/api-reference/chat) | | Office productivity agent | PPT Task, Mindmap, LiveDocs, SuperAgent | [PPT Task API](/docs/api-reference/ppt-tasks) | | Creative operations agent | Landing Page, Image workflows, Web Fetch, Search, SuperAgent | [Landing Page API](/docs/api-reference/landing-page) | | Full-stack AI app | LLM API, Chat, LiveDocs, Web Fetch, SuperAgent | [LLM API](/docs/api-reference/llm) | | Knowledge workflow | LiveDocs, Web Fetch, Chat, SuperAgent | [LiveDoc API](/docs/api-reference/livedocs) | ## Direct API Examples If you are building directly against the API instead of configuring an AI tool, start with one of these minimal calls. ### Create a PPT Task Use the PPT Task API when you want to generate a slide deck asynchronously. The response returns a `task_id` that you can poll. ```bash curl -X POST https://openapi.felo.ai/v2/ppts \ -H "Authorization: Bearer $FELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Create a 5-slide strategy deck about AI agents for office productivity" }' ``` Example response: ```json { "status": "ok", "message": null, "data": { "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9", "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3", "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr" } } ``` Poll the task status: ```bash curl -X GET https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status \ -H "Authorization: Bearer $FELO_API_KEY" ``` ### Create a Landing Page Task Use the Landing Page Task API when you want Felo to generate a landing page from a prompt. ```bash curl -X POST https://openapi.felo.ai/v2/landing_page \ -H "Authorization: Bearer $FELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Generate a launch landing page for an AI research assistant" }' ``` Example response: ```json { "status": "ok", "message": null, "data": { "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9", "thread_short_id": "9qiLTmT77fA3aVurrMHvRJ" } } ``` Poll the same task status endpoint used by PPT tasks: ```bash curl -X GET https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status \ -H "Authorization: Bearer $FELO_API_KEY" ``` ### Python ```python import os import requests api_key = os.environ["FELO_API_KEY"] response = requests.post( "https://openapi.felo.ai/v2/chat", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={"query": "What are the latest AI agent product trends?"}, timeout=60, ) response.raise_for_status() print(response.json()["data"]["answer"]) ``` ### JavaScript (Node.js) ```javascript const response = await fetch("https://openapi.felo.ai/v2/chat", { method: "POST", headers: { Authorization: `Bearer ${process.env.FELO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "What are the latest AI agent product trends?", }), }); if (!response.ok) { throw new Error(`Felo API request failed: ${response.status}`); } const result = await response.json(); console.log(result.data.answer); ``` ::: warning Keep browser calls behind your server Do not call Felo API Platform directly from public frontend code with a secret API key. For browser apps, route requests through your backend and keep `FELO_API_KEY` on the server. ::: ## Common Setup Issues | Issue | What to check | |-------|---------------| | `INVALID_API_KEY` | Confirm the key is copied correctly and not revoked | | `MISSING_AUTHORIZATION` | Add `Authorization: Bearer $FELO_API_KEY` to the request | | Tool calls the wrong provider | Check that the Felo provider is selected in the current workspace or session | | OpenAI-compatible client fails | Use `https://openapi.felo.ai/api/v1` as the base URL | | Anthropic-compatible client fails | Use `https://openapi.felo.ai/api` as the base URL | | Async task has no result yet | Poll the task status endpoint until the task is complete | ## Next Steps - [Set up Codex](/docs/agent-clients/codex) - [Set up Claude Code](/docs/agent-clients/claude-code) - [Authentication Guide](/docs/authentication) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Authentication URL: https://openapi.felo.ai/docs/authentication Description: Authenticate requests with API keys, follow security practices, and handle auth errors. # Authentication All requests to Felo API Platform APIs require authentication using an API Key. This guide explains how to authenticate your requests and handle common authentication issues. ## API Key Authentication Felo uses API Key authentication for all v2 endpoints. Your API Key identifies your application and provides access to the platform's capabilities. ### How It Works 1. You obtain an API Key from the [Felo API Platform API Keys page](/settings/api-keys) 2. You include the API Key in the `Authorization` header of every API request 3. The platform validates your API Key and processes your request ### Header Format Include your API Key in the `Authorization` header using the Bearer authentication scheme: ``` Authorization: Bearer YOUR_API_KEY ``` ### Example Request ```bash curl -X POST https://openapi.felo.ai/v2/chat \ -H "Authorization: Bearer sk_live_abc123xyz789" \ -H "Content-Type: application/json" \ -d '{"query": "What is machine learning?"}' ``` ## Obtaining Your API Key To get your API Key: 1. Open the [Felo API Platform API Keys page](/settings/api-keys) 2. Sign in with your Felo account if prompted 3. Enter a key name and click **Create Key** 4. Copy the full key when it appears. It is only shown once 5. Store the key securely and use it as `FELO_API_KEY` ::: warning Keep Your API Key Secret Your API Key provides access to your Felo account and should be kept confidential. Never share it publicly, commit it to version control, or expose it in client-side code. ::: ## Security Best Practices ### 1. Store API Keys Securely **Don't** hardcode API Keys in your source code: ```python # ❌ Bad - API Key exposed in code api_key = "sk_live_abc123xyz789" ``` **Do** use environment variables or secure configuration: ```python # ✅ Good - API Key from environment import os api_key = os.environ.get('FELO_API_KEY') ``` ### 2. Use Environment Variables Store your API Key in environment variables: **Linux/macOS:** ```bash export FELO_API_KEY="sk_live_abc123xyz789" ``` **Windows (Command Prompt):** ```cmd set FELO_API_KEY=sk_live_abc123xyz789 ``` **Windows (PowerShell):** ```powershell $env:FELO_API_KEY="sk_live_abc123xyz789" ``` ### 3. Rotate Keys Regularly Periodically generate new API Keys and revoke old ones to minimize security risks. ### 4. Use Different Keys for Different Environments Create separate API Keys for development, staging, and production environments. ### 5. Never Expose Keys in Client-Side Code API Keys should only be used in server-side code. Never include them in: - Frontend JavaScript code - Mobile app source code - Public repositories - Client-side configuration files ## Authentication Errors ### Common Error Codes | Error Code | Description | Solution | |------------|-------------|----------| | `INVALID_API_KEY` | The API Key is invalid, malformed, or has been revoked | Verify your API Key is correct and hasn't been revoked | | `MISSING_AUTHORIZATION` | The Authorization header is missing | Include the Authorization header in your request | | `MALFORMED_AUTHORIZATION` | The Authorization header format is incorrect | Use the format: `Authorization: Bearer YOUR_API_KEY` | | `EXPIRED_API_KEY` | The API Key has expired | Generate a new API Key from the [API Keys page](/settings/api-keys) | | `RATE_LIMITED` | Too many requests in a short time | Slow down your request rate or contact support for higher limits | ### Error Response Format When authentication fails, you'll receive an error response: ```json { "status": "error", "code": "INVALID_API_KEY", "message": "The provided API Key is invalid or has been revoked", "request_id": "req_abc123" } ``` ## Troubleshooting ### Issue: "INVALID_API_KEY" Error **Possible causes:** - The API Key is incorrect or has typos - The API Key has been revoked - You're using a test key in production (or vice versa) **Solutions:** 1. Double-check your API Key for typos 2. Verify the key has not been revoked on the [API Keys page](/settings/api-keys) 3. Ensure you're using the correct key for your environment 4. Generate a new API Key if needed ### Issue: "MISSING_AUTHORIZATION" Error **Possible causes:** - The Authorization header is not included in the request - The header name is misspelled **Solutions:** 1. Ensure you're including the Authorization header 2. Check the header name is exactly `Authorization` (case-sensitive) 3. Verify your HTTP client is sending the header correctly ### Issue: "MALFORMED_AUTHORIZATION" Error **Possible causes:** - The Authorization header format is incorrect - Missing "Bearer" prefix - Extra spaces or characters **Solutions:** 1. Use the exact format: `Authorization: Bearer YOUR_API_KEY` 2. Ensure there's exactly one space after "Bearer" 3. Don't include quotes around the API Key ### Example: Debugging Authentication ```python import requests url = "https://openapi.felo.ai/v2/chat" api_key = "YOUR_API_KEY" # Correct format headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } response = requests.post(url, headers=headers, json={"query": "test"}) if response.status_code == 401: error = response.json() print(f"Authentication failed: {error['code']}") print(f"Message: {error['message']}") print(f"Request ID: {error['request_id']}") else: print("Authentication successful!") ``` ## Rate Limiting Rate limits are enforced **per endpoint**, not globally per API Key. See each endpoint's documentation for whether limits apply. Currently rate-limited: - [`/v2/chat`](./api-reference/v2/chat.md#rate-limiting) - limited on per-API-Key, per-user (minute window) and per-user (hourly window) dimensions. Exact numeric thresholds are read from response headers (see below) so they can be tuned without doc updates. Other `/v2/**` endpoints currently have no enforced rate limits. When a limit is exceeded, the API returns `429 Too Many Requests` with `X-RateLimit-*` headers and `Retry-After`. **Always read effective limits from the response headers**, not from this document. ## Need Help? If you're experiencing authentication issues: 1. Review this guide carefully 2. Check the [Getting Started](/docs/getting-started.html) guide 3. Verify your API Key on the [API Keys page](/settings/api-keys) 4. Contact support at support@felo.ai with your request ID ## Next Steps - [Getting Started Guide](/docs/getting-started.html) - Learn how to make your first API call - [Chat API Reference](/docs/api-reference/chat) - Explore the Chat API documentation --- # Felo Skills for AI Agents URL: https://openapi.felo.ai/docs/felo-skills Description: Install every Felo AI Skill into Codex, Claude Code, OpenClaw, or Hermes Agent. # Felo Skills for AI Agents Install the official `felo-ai` package to give an AI Agent the complete Felo Skill set. The package can change over time, so do not maintain a fixed list of Skills: discover every immediate package directory that contains `SKILL.md` and install all of them. Every tool page links here because the complete package includes the Skill for that tool alongside the rest of the available Felo capabilities. ## Before you start You need Node.js 18 or newer, npm, the target Agent CLI, and a Felo API key. Install or update the official package first: ```bash npm install -g felo-ai@latest felo config set FELO_API_KEY YOUR_API_KEY ``` Resolve the package directory with `npm root -g`. Enumerate every immediate child directory that contains `SKILL.md`; each one is a Felo Skill to install. Never replace an existing real target directory or a link that points outside the installed `felo-ai` package. Report those conflicts instead. ## Codex Install every discovered package Skill at `~/.codex/skills/`. On Unix-like systems, create safe symbolic links; on Windows, use directory junctions or guarded copies. Start a new Codex session afterward so it discovers the complete set. ## Claude Code Install every discovered package Skill at `~/.claude/skills/`. Merge `FELO_API_KEY` into the `env` object in `~/.claude/settings.json` without removing unrelated settings. Start a new Claude Code session after installation. ## OpenClaw Install every discovered package Skill at `~/.agents/skills/`, OpenClaw's personal Skills directory. In `~/.openclaw/openclaw.json`, merge `FELO_API_KEY` into `skills.entries..env` for every discovered Felo Skill. Run `openclaw skills list`; when the Gateway is running, restart it safely and verify `openclaw gateway status`. ## Hermes Agent Install every discovered package Skill at `~/.hermes/skills/`. Store the key with `hermes config set FELO_API_KEY YOUR_API_KEY`, then run `hermes skills list` to verify the discovered Skills. Restart an active Hermes Gateway or begin a new CLI session. ## Verify the installation Run the following checks without printing your API key: ```bash felo --version felo config path felo search "test query" ``` If a Skill does not appear, compare the package directories containing `SKILL.md` with the target Agent Skill directory. Leave conflicting user-owned directories untouched and resolve them manually. --- # Claude Code and Codex Configuration URL: https://openapi.felo.ai/docs/api-reference/v2/llm-agent-clients Description: Configure Claude Code and Codex to route model calls through Felo API Platform. # Claude Code and Codex Configuration This guide shows how to configure agent clients to use the Felo API Platform LLM API. Use this page when you want Claude Code or Codex to route model calls through Felo API Platform instead of calling a model vendor directly. Set `FELO_API_KEY` to your Felo API Platform key before using either client. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Supported Client Paths | Client or API surface | Recommended Felo endpoint | Model example | Notes | |-----------------------|---------------------------|---------------|-------| | Claude Code | `POST /api/v1/messages` | `claude-sonnet-4-6` | Claude Code uses the Anthropic Messages wire format. | | Codex | `POST /api/v1/responses` | `gpt-5.6-sol` | Codex custom providers should use the Responses API. | | Chat Completions | `POST /api/v1/chat/completions` | `gpt-5.6-sol` | Use from SDKs or server-side integrations. Codex Chat Completions support is deprecated in Codex documentation. | ## Claude Code Claude Code should use the Anthropic-compatible Messages endpoint. Claude Code can use any published model listed in [Models and Pricing](/docs/api-reference/llm#models-and-pricing), including the newly available `claude-sonnet-5`: ```bash claude --model claude-sonnet-5 ``` ### Shell Configuration ```bash export ANTHROPIC_API_KEY="$FELO_API_KEY" export ANTHROPIC_BASE_URL="https://openapi.felo.ai/api" export ANTHROPIC_MODEL="claude-sonnet-4-6" claude ``` The Anthropic base URL intentionally omits `/v1`, because Claude Code and the Anthropic SDK append `/v1/messages` to the configured API host. ### Settings File Configuration Use a Claude Code settings file when you want the endpoint and model to apply every time `claude` starts. Keep API keys in your shell or secret manager instead of committing them into project settings. ```json { "env": { "ANTHROPIC_BASE_URL": "https://openapi.felo.ai/api", "ANTHROPIC_MODEL": "claude-sonnet-4-6" } } ``` You can also choose the model for one session: ```bash claude --model claude-sonnet-4-6 ``` ## Codex Codex should use the OpenAI-compatible Responses endpoint. `gpt-5.6-sol` is the flagship GPT-5.6 tier for complex reasoning, coding, and agentic workflows. ### User Config Add a Felo provider to your user-level Codex configuration at `~/.codex/config.toml`. ```toml model_provider = "felo" model = "gpt-5.6-sol" [model_providers.felo] name = "Felo API Platform LLM API" base_url = "https://openapi.felo.ai/api/v1" env_key = "FELO_API_KEY" wire_api = "responses" ``` Codex endpoint authentication and endpoint selection must live in user-level Codex config. Codex ignores `model_provider`, `model_providers`, and `openai_base_url` from project-scoped `.codex/config.toml` files. ### One-Off Model Selection After the Felo provider is configured, you can choose the model for a single CLI run: ```bash codex --model gpt-5.6-sol ``` For non-interactive runs: ```bash codex exec --model gpt-5.6-sol "Review this change" ``` ## Official Documentation - [Claude Code environment variables](https://code.claude.com/docs/en/env-vars) - [Claude Code model configuration](https://code.claude.com/docs/en/model-config) - [Claude Code settings](https://code.claude.com/docs/en/settings) - [Codex config basics](https://developers.openai.com/codex/config-basic) - [Codex advanced configuration](https://developers.openai.com/codex/config-advanced#custom-model-providers) - [Codex models](https://developers.openai.com/codex/models) --- # Codex URL: https://openapi.felo.ai/docs/agent-clients/codex Description: Configure Codex CLI with a Felo custom model provider. # Codex Use this guide when you want Codex CLI to use Felo API Platform for model calls while keeping the normal Codex terminal workflow. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | CLI coding workflows, code review, repo changes, and non-interactive automation | | Protocol | OpenAI-compatible Responses API | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `gpt-5.6-sol` | | API key | Your `FELO_API_KEY` | ## Configure Codex Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ### User-level Codex config Add a Felo provider to your user-level Codex configuration at `~/.codex/config.toml`. ```toml model_provider = "felo" model = "gpt-5.6-sol" [model_providers.felo] name = "Felo API Platform" base_url = "https://openapi.felo.ai/api/v1" env_key = "FELO_API_KEY" wire_api = "responses" ``` Codex provider settings should live in the user-level config. Do not put API keys in project files. For a non-interactive check, run: ```bash codex exec --model gpt-5.6-sol "Review this repository and list the main files" ``` ## Verify the Setup Run a small task after saving the configuration: ```bash codex --model gpt-5.6-sol ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Claude Code URL: https://openapi.felo.ai/docs/agent-clients/claude-code Description: Configure Claude Code to route Anthropic-compatible model calls through Felo API Platform. # Claude Code Use this guide when you want Claude Code to use Felo API Platform instead of calling the model vendor directly. Claude Code uses an Anthropic-compatible Messages endpoint. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | repo editing, coding agents, long-context research, and terminal-first development | | Protocol | Anthropic-compatible Messages API | | Base URL | `https://openapi.felo.ai/api` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Claude Code Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export ANTHROPIC_API_KEY="$FELO_API_KEY" export ANTHROPIC_BASE_URL="https://openapi.felo.ai/api" export ANTHROPIC_MODEL="claude-sonnet-4-6" ``` ### Optional settings file Use a settings file when you want the base URL and model to apply every time Claude Code starts. Keep the API key in your shell or secret manager. ```json { "env": { "ANTHROPIC_BASE_URL": "https://openapi.felo.ai/api", "ANTHROPIC_MODEL": "claude-sonnet-4-6" } } ``` You can also choose a model for one session: ```bash claude --model claude-sonnet-5 ``` ## Verify the Setup Run a small task after saving the configuration: ```bash claude ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # OpenCode URL: https://openapi.felo.ai/docs/agent-clients/opencode Description: Connect OpenCode to Felo through the OpenAI-compatible endpoint. # OpenCode Use this guide when OpenCode asks for an OpenAI-compatible provider, API key, base URL, and model name. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | terminal coding sessions, local agents, and OpenAI-compatible model routing | | Protocol | OpenAI-compatible Chat Completions | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure OpenCode Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields If OpenCode shows provider fields, use these values: | Field | Value | |-------|-------| | Provider | OpenAI-compatible | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` or another model from the Felo model list | If the client supports a Responses API mode, prefer it for agent-style tasks. If it only supports Chat Completions, use the same base URL and model name. ## Verify the Setup Run a small task after saving the configuration: ```bash opencode ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # OpenClaw URL: https://openapi.felo.ai/docs/agent-clients/openclaw Description: Connect OpenClaw to Felo API Platform for assistant and agent workflows. # OpenClaw Use this guide when you want OpenClaw to call Felo models and workflow APIs from a personal AI assistant setup. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | personal assistants, tool-using agents, search-backed workflows, and local automation | | Protocol | OpenAI-compatible or Anthropic-compatible endpoint | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure OpenClaw Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Recommended OpenClaw settings | Field | Value | |-------|-------| | Provider type | OpenAI-compatible | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | Use SuperAgent, Search, Web Fetch, PPT, Mindmap, and LiveDocs APIs when your OpenClaw workflow needs ready-made tools beyond model chat. ## Verify the Setup Run a small task after saving the configuration: ```bash Start OpenClaw and select the Felo provider you configured. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Hermes Agent URL: https://openapi.felo.ai/docs/agent-clients/hermes-agent Description: Configure Hermes Agent with Felo API Platform model access. # Hermes Agent Use this guide when Hermes Agent lets you add an OpenAI-compatible provider. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | agent experiments, local workflows, and multi-tool orchestration | | Protocol | OpenAI-compatible Chat Completions | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Hermes Agent Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider | OpenAI-compatible | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | If Hermes Agent supports custom request headers, no extra header is required beyond bearer authentication. ## Verify the Setup Run a small task after saving the configuration: ```bash Start Hermes Agent and select your Felo provider. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # TRAE URL: https://openapi.felo.ai/docs/agent-clients/trae Description: Use Felo API Platform from TRAE through compatible model provider settings. # TRAE Use this guide when TRAE lets you configure a custom OpenAI-compatible or Anthropic-compatible model provider. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | AI IDE workflows, code generation, repo Q&A, and assisted editing | | Protocol | OpenAI-compatible endpoint by default | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure TRAE Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider type | OpenAI-compatible | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | If TRAE provides an Anthropic-compatible mode, use `https://openapi.felo.ai/api` as the base URL and keep the same API key. ## Verify the Setup Run a small task after saving the configuration: ```bash Open TRAE, choose the custom provider, and start a chat or coding task. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # OpenViking URL: https://openapi.felo.ai/docs/agent-clients/openviking Description: Connect OpenViking to Felo API Platform using a compatible provider profile. # OpenViking Use this guide when OpenViking asks for an API key, base URL, and model name. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | agent experiments, assistant workflows, and model-provider switching | | Protocol | OpenAI-compatible endpoint | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure OpenViking Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider | OpenAI-compatible | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | For workflows that need research or files, combine the model route with Chat, Web Fetch, LiveDocs, and SuperAgent APIs. ## Verify the Setup Run a small task after saving the configuration: ```bash Start OpenViking and select the Felo provider profile. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # DeepSeek Harness URL: https://openapi.felo.ai/docs/agent-clients/deepseek-harness Description: Connect DeepSeek Harness to Felo through its native DeepSeek adapter or a custom OpenAI-compatible provider. # DeepSeek Harness Use this guide to run the open-source [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) with models served by Felo API Platform. The recommended path reuses the harness's built-in `deepseek-official` adapter. You can also add Felo as a separate custom OpenAI-compatible provider in the Web UI. DeepSeek Harness is currently a developer preview and may introduce compatibility-breaking changes. Check its upstream release notes when an option or screen differs from this guide. ## Before You Start You need Node.js and one Felo API Platform key. Keep the key out of source control. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` The examples use `deepseek-v4-flash`. Check [Models and Pricing](/docs/api-reference/llm#models-and-pricing) before selecting a different model ID. ## Recommended Setup: Built-in DeepSeek Adapter DeepSeek Harness reads the built-in adapter credential from `DEEPSEEK_API_KEY` and its endpoint from `DEEPSEEK_BASE_URL`. ```bash export DEEPSEEK_API_KEY="$FELO_API_KEY" export DEEPSEEK_BASE_URL="https://openapi.felo.ai/api/v1" npx @deepseek-ai/dsh web ``` Open `http://127.0.0.1:3080`, then: 1. Add or select your project workspace. 2. Open **Settings → Models**. 3. Select the `deepseek-official` provider and `deepseek-v4-flash` model. 4. Start a new session and send a small repository task. Do not append `/chat/completions` to the base URL. The built-in adapter sends requests to `{DEEPSEEK_BASE_URL}/chat/completions` itself. ### Persist the environment values DeepSeek Harness can read a `.env` file from the directory where you start it. Add the following values to an untracked `.env` file if you do not want to export them for every session: ```dotenv DEEPSEEK_API_KEY=YOUR_API_KEY DEEPSEEK_BASE_URL=https://openapi.felo.ai/api/v1 ``` Do not commit this file. You can also use the harness credential and settings files under `$DSH_HOME` when you need user-level configuration. ## Alternative Setup: Custom OpenAI-compatible Provider Use this path when you want Felo to appear as a separate provider instead of overriding the built-in DeepSeek connection. 1. Start the Web UI with `npx @deepseek-ai/dsh web`. 2. Open **Settings → Models**. 3. Choose **Add custom provider**. 4. Enter the following values and save the provider. | Field | Value | |-------|-------| | Provider ID | `felo` | | Display name | `Felo API Platform` | | Base URL | `https://openapi.felo.ai/api/v1` | | API protocol | OpenAI-compatible Chat Completions (`openai-completions`) | | API key | Your Felo API key | | Model ID | `deepseek-v4-flash` | If model discovery fails, add the model ID manually. A provider's **Get available models** action depends on an OpenAI-compatible `GET /models` route and is not required for manual configuration. ## Verify the Setup Start a fresh session and ask: ```text Summarize this repository and identify its main packages. ``` The setup is ready when the session completes with `deepseek-v4-flash` selected and no authentication or unknown-model error appears. For a non-interactive smoke test with the recommended adapter, run from the target workspace: ```bash npx @deepseek-ai/dsh --profile headless "List the top-level files in this workspace." ``` ## Web Search Note This setup routes model requests through Felo. DeepSeek Harness's built-in `web_search` provider has separate endpoint requirements even though its default credential variable is also `DEEPSEEK_API_KEY`. Do not point `DEEPSEEK_SEARCH_BASE_URL` at Felo unless you are using an explicitly compatible search endpoint. Use Felo's [Chat API](/docs/api-reference/chat) or other Felo Skills separately when your workflow needs Felo search. ## Troubleshooting | Issue | What to check | |-------|---------------| | `MISSING_CREDENTIAL` or 401 | Confirm `DEEPSEEK_API_KEY` contains the Felo key in the process that starts `dsh` | | Request URL contains the path twice | Use `https://openapi.felo.ai/api/v1`, not a URL ending in `/chat/completions` | | `UNKNOWN_MODEL` | Select or manually add `deepseek-v4-flash`, or use another published Felo model ID | | Felo is not listed separately | Use the custom-provider setup; the recommended path keeps the provider ID `deepseek-official` | | Settings changed but an old session behaves differently | Start a new session so it uses the newly selected provider and model route | | Web search authentication fails | Configure the harness search provider separately; model endpoint settings do not configure web search | ## Next Steps - [DeepSeek Harness repository](https://github.com/deepseek-ai/deepseek-harness) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [Felo Skills for AI Agents](/docs/felo-skills) --- # Cursor URL: https://openapi.felo.ai/docs/agent-clients/cursor Description: Use Felo API Platform in Cursor through custom OpenAI-compatible settings where available. # Cursor Use this guide when your Cursor setup supports custom OpenAI-compatible endpoints or external provider overrides. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | AI coding inside an editor, repo questions, and code generation | | Protocol | OpenAI-compatible Chat Completions | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Cursor Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider type | OpenAI-compatible custom provider | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | If your Cursor version does not expose custom base URL settings, use Claude Code, Codex, OpenCode, or another client that supports custom providers. ## Verify the Setup Run a small task after saving the configuration: ```bash Open Cursor and run a small chat or code edit after saving the provider settings. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Cline URL: https://openapi.felo.ai/docs/agent-clients/cline Description: Configure Cline with Felo API Platform model access. # Cline Use this guide when Cline asks for a provider type, API key, base URL, and model ID. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | VS Code agent workflows, file edits, browser tasks, and terminal-assisted coding | | Protocol | OpenAI-compatible or Anthropic-compatible endpoint | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Cline Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider type | OpenAI-compatible custom provider | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | If you choose an Anthropic-compatible provider mode, use `https://openapi.felo.ai/api` as the base URL. ## Verify the Setup Run a small task after saving the configuration: ```bash Open Cline, select the Felo provider, and run a simple file-inspection task. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Roo Code URL: https://openapi.felo.ai/docs/agent-clients/roo-code Description: Configure Roo Code with a Felo-compatible model provider. # Roo Code Use this guide when Roo Code asks for custom provider settings. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | VS Code coding agents, repo editing, command execution, and task planning | | Protocol | OpenAI-compatible or Anthropic-compatible endpoint | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Roo Code Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider type | OpenAI-compatible custom provider | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | Use the Anthropic-compatible base URL `https://openapi.felo.ai/api` only if Roo Code is configured in Anthropic mode. ## Verify the Setup Run a small task after saving the configuration: ```bash Open Roo Code and ask it to inspect the current repository. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Kilo Code URL: https://openapi.felo.ai/docs/agent-clients/kilo-code Description: Configure Kilo Code with Felo API Platform model access. # Kilo Code Use this guide when Kilo Code supports custom OpenAI-compatible provider settings. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | local coding agents, repo editing, task execution, and model-provider testing | | Protocol | OpenAI-compatible Chat Completions | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Kilo Code Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" ``` ### Client fields | Field | Value | |-------|-------| | Provider type | OpenAI-compatible custom provider | | API key | Your `FELO_API_KEY` | | Base URL | `https://openapi.felo.ai/api/v1` | | Model | `claude-sonnet-4-6` | If Kilo Code supports separate chat and reasoning models, start with the same Felo model for both, then tune per workflow. ## Verify the Setup Run a small task after saving the configuration: ```bash Open Kilo Code and run a small code explanation task. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Other AI Tools URL: https://openapi.felo.ai/docs/agent-clients/other-tools Description: Connect any client that supports OpenAI-compatible or Anthropic-compatible endpoints. # Other AI Tools Use this guide when your tool is not listed, but it lets you enter an API key, base URL, and model name. ## Before You Start You need one Felo API Platform key. The same key works across model protocols, agent clients, Search, Web Fetch, PPT, Mindmap, LiveDocs, X Search, YouTube Subtitling, Landing Page, and SuperAgent APIs. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ## Recommended Setup | Item | Value | |------|-------| | Best for | custom clients, API testing tools, internal agents, and low-code automation | | Protocol | OpenAI-compatible or Anthropic-compatible endpoint | | Base URL | `https://openapi.felo.ai/api/v1` | | Model example | `claude-sonnet-4-6` | | API key | Your `FELO_API_KEY` | ## Configure Other AI Tools Set the environment variables first: ```bash export FELO_API_KEY="YOUR_API_KEY" export OPENAI_API_KEY="$FELO_API_KEY" export OPENAI_BASE_URL="https://openapi.felo.ai/api/v1" export ANTHROPIC_API_KEY="$FELO_API_KEY" export ANTHROPIC_BASE_URL="https://openapi.felo.ai/api" ``` ### Which base URL should I choose? | Tool asks for | Use this base URL | |---------------|-------------------| | OpenAI-compatible endpoint | `https://openapi.felo.ai/api/v1` | | Anthropic-compatible endpoint | `https://openapi.felo.ai/api` | | Chat Completions URL | `https://openapi.felo.ai/api/v1` | | Messages API host | `https://openapi.felo.ai/api` | Start with `claude-sonnet-4-6` unless your workflow requires another published model. ## Verify the Setup Run a small task after saving the configuration: ```bash Save the provider settings in your tool and send a short test message. ``` If the tool starts and answers with the selected model, the provider setup is ready. ## Troubleshooting | Issue | What to check | |-------|---------------| | Authentication fails | Confirm the key is copied correctly and exported as `FELO_API_KEY` | | Tool calls the wrong provider | Check that the Felo provider is selected for the current workspace or session | | Base URL error | Use `https://openapi.felo.ai/api/v1` for OpenAI-compatible clients and `https://openapi.felo.ai/api` for Anthropic-compatible clients | | Model not found | Choose a model that appears in your Felo model list | | The tool ignores local config | Move provider settings to the user-level config if the client requires it | ## Next Steps - [Getting Started](/docs/getting-started) - [LLM API Reference](/docs/api-reference/llm) - [Chat API Reference](/docs/api-reference/chat) - [SuperAgent API Reference](/docs/api-reference/superagent) --- # Chat API URL: https://openapi.felo.ai/docs/api-reference/chat Description: Integrate AI-powered conversational search with query analysis, web resources, and citations. # Chat API The Chat API enables you to integrate AI-powered conversational search into your applications. Send a natural language query and receive an intelligent answer generated from real-time web search results. ## Overview The Chat API performs the following operations: 1. Analyzes and optimizes your query 2. Searches the web for relevant information 3. Ranks and filters search results 4. Generates a comprehensive AI answer based on the sources 5. Returns the answer along with source citations **Use Cases:** - Conversational AI assistants - Research and information retrieval tools - Customer support chatbots with web knowledge - Educational applications - Content creation tools ## Authentication All requests to the Chat API require authentication using an API Key. Include your API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` See the [Authentication Guide](/docs/authentication) for details on obtaining and using your API Key. ## Use with AI Agents Install the complete `felo-ai` package when you want an Agent to use Search and every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, so it includes future Skills rather than a fixed subset. Install them in the native directory for your Agent: Codex uses `~/.codex/skills`, Claude Code uses `~/.claude/skills`, OpenClaw uses `~/.agents/skills`, and Hermes Agent uses `~/.hermes/skills`. See the [manual AI Agent setup guide](/docs/felo-skills) for the safe link, API key, and verification steps for each platform. ## Endpoint ``` POST https://openapi.felo.ai/v2/chat ``` ## Request ### Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | Your API Key in the format: `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | Must be `application/json` | ### Body Parameters | Parameter | Type | Required | Description | Constraints | |-----------|------|----------|-------------|-------------| | `query` | string | Yes | The user's question or search query | 1-2000 characters | ### Example Request ```json { "query": "What are the latest developments in quantum computing?" } ``` ## Response ### Success Response (200 OK) When the request is successful, the API returns a JSON response with the following structure: ```json { "status": "ok", "message": null, "data": { "id": "HabCj883yHLSXc8mWqu4Eq", "message_id": "18ea8517-5559-4f48-a355-1f8a79e73b71", "answer": "Recent developments in quantum computing include...", "query_analysis": { "queries": [ "quantum computing latest developments 2025", "quantum computing breakthroughs" ] }, "resources": [ { "link": "https://example.com/quantum-news", "title": "Latest Quantum Computing Breakthroughs", "snippet": "Scientists have achieved a major milestone..." }, { "link": "https://example.com/quantum-research", "title": "Quantum Computing Research 2025", "snippet": "New quantum algorithms show promise..." } ] } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `status` | string | Response status: `"ok"` for success, `"error"` for failure | | `message` | string \| null | Additional message (null for successful requests) | | `data` | object | Response data (only present when status is "ok") | | `data.id` | string | Unique identifier for this chat session | | `data.message_id` | string | Unique identifier for this specific message | | `data.answer` | string | AI-generated answer to the query | | `data.query_analysis` | object | Analysis of the user's query | | `data.query_analysis.queries` | string[] | Optimized search queries derived from the user's input | | `data.resources` | array | List of web sources used to generate the answer | | `data.resources[].link` | string | URL of the source | | `data.resources[].title` | string | Title of the source page | | `data.resources[].snippet` | string | Relevant excerpt from the source | ### Error Response When an error occurs, the API returns a JSON response with error details: ```json { "status": "error", "code": "INVALID_API_KEY", "message": "The provided API Key is invalid or has been revoked", "request_id": "req_abc123xyz789" } ``` ### Error Response Fields | Field | Type | Description | |-------|------|-------------| | `status` | string | Always `"error"` for error responses | | `code` | string | Error code identifying the type of error | | `message` | string | Human-readable error description | | `request_id` | string | Unique identifier for this request (useful for support) | ## Error Codes | Code | HTTP Status | Description | Solution | |------|-------------|-------------|----------| | `INVALID_API_KEY` | 401 | API Key is invalid, malformed, or revoked | Verify your API Key is correct and active | | `MISSING_AUTHORIZATION` | 401 | Authorization header is missing | Include the Authorization header in your request | | `MALFORMED_AUTHORIZATION` | 401 | Authorization header format is incorrect | Use format: `Authorization: Bearer YOUR_API_KEY` | | `MISSING_PARAMETER` | 400 | Required parameter is missing | Ensure `query` parameter is included in request body | | `INVALID_PARAMETER` | 400 | Parameter value is invalid | Check that `query` is a non-empty string (1-2000 characters) | | `QUERY_TOO_LONG` | 400 | Query exceeds maximum length | Shorten your query to 2000 characters or less | | `RATE_LIMITED` | 429 | Too many requests in a short time | Slow down your request rate or contact support | | `CHAT_FAILED` | 502 | Internal service error | Retry the request; contact support if the issue persists | | `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable | Wait and retry; check status page for updates | ## Examples ### cURL ```bash curl -X POST https://openapi.felo.ai/v2/chat \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "What are the benefits of renewable energy?" }' ``` **Response:** ```json { "status": "ok", "message": null, "data": { "id": "HabCj883yHLSXc8mWqu4Eq", "message_id": "18ea8517-5559-4f48-a355-1f8a79e73b71", "answer": "Renewable energy offers numerous benefits including reduced greenhouse gas emissions, decreased air pollution, energy independence, job creation, and long-term cost savings. Solar, wind, and hydroelectric power are sustainable alternatives to fossil fuels that help combat climate change while providing reliable electricity.", "query_analysis": { "queries": [ "renewable energy benefits", "advantages of renewable energy sources" ] }, "resources": [ { "link": "https://example.com/renewable-benefits", "title": "Top Benefits of Renewable Energy", "snippet": "Renewable energy sources provide clean, sustainable power..." } ] } } ``` ### Python ```python import requests import os # Get API key from environment variable api_key = os.environ.get('FELO_API_KEY') url = 'https://openapi.felo.ai/v2/chat' headers = { 'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json' } data = { 'query': 'What are the benefits of renewable energy?' } try: response = requests.post(url, headers=headers, json=data) response.raise_for_status() # Raise exception for HTTP errors result = response.json() if result['status'] == 'ok': print('Answer:', result['data']['answer']) print('\nSources:') for resource in result['data']['resources']: print(f"- {resource['title']}: {resource['link']}") else: print(f"Error: {result['code']} - {result['message']}") except requests.exceptions.RequestException as e: print(f'Request failed: {e}') ``` ### JavaScript (Node.js) ```javascript const fetch = require('node-fetch'); const apiKey = process.env.FELO_API_KEY; const url = 'https://openapi.felo.ai/v2/chat'; const headers = { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' }; const body = JSON.stringify({ query: 'What are the benefits of renewable energy?' }); fetch(url, { method: 'POST', headers, body }) .then(response => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.json(); }) .then(data => { if (data.status === 'ok') { console.log('Answer:', data.data.answer); console.log('\nSources:'); data.data.resources.forEach(resource => { console.log(`- ${resource.title}: ${resource.link}`); }); } else { console.error(`Error: ${data.code} - ${data.message}`); } }) .catch(error => { console.error('Request failed:', error); }); ``` ### JavaScript (Browser/Fetch API) ```javascript const apiKey = 'YOUR_API_KEY'; // In production, get this from your backend fetch('https://openapi.felo.ai/v2/chat', { method: 'POST', headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'What are the benefits of renewable energy?' }) }) .then(response => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.json(); }) .then(data => { if (data.status === 'ok') { console.log('Answer:', data.data.answer); // Display sources const sourcesList = data.data.resources.map(resource => `
  • ${resource.title}
    • ` ).join(''); document.getElementById('answer').innerHTML = data.data.answer; document.getElementById('sources').innerHTML = sourcesList; } else { console.error(`Error: ${data.code} - ${data.message}`); } }) .catch(error => { console.error('Request failed:', error); }); ``` ### Go ```go package main import ( "bytes" "encoding/json" "fmt" "io" "net/http" "os" ) type ChatRequest struct { Query string `json:"query"` } type ChatResponse struct { Status string `json:"status"` Message string `json:"message,omitempty"` Data struct { ID string `json:"id"` MessageID string `json:"message_id"` Answer string `json:"answer"` QueryAnalysis struct { Queries []string `json:"queries"` } `json:"query_analysis"` Resources []struct { Link string `json:"link"` Title string `json:"title"` Snippet string `json:"snippet"` } `json:"resources"` } `json:"data,omitempty"` Code string `json:"code,omitempty"` RequestID string `json:"request_id,omitempty"` } func main() { apiKey := os.Getenv("FELO_API_KEY") url := "https://openapi.felo.ai/v2/chat" requestBody := ChatRequest{ Query: "What are the benefits of renewable energy?", } jsonData, err := json.Marshal(requestBody) if err != nil { fmt.Printf("Error marshaling request: %v\n", err) return } req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) if err != nil { fmt.Printf("Error creating request: %v\n", err) return } req.Header.Set("Authorization", "Bearer "+apiKey) req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { fmt.Printf("Error making request: %v\n", err) return } defer resp.Body.Close() body, err := io.ReadAll(resp.Body) if err != nil { fmt.Printf("Error reading response: %v\n", err) return } var chatResp ChatResponse err = json.Unmarshal(body, &chatResp) if err != nil { fmt.Printf("Error unmarshaling response: %v\n", err) return } if chatResp.Status == "ok" { fmt.Println("Answer:", chatResp.Data.Answer) fmt.Println("\nSources:") for _, resource := range chatResp.Data.Resources { fmt.Printf("- %s: %s\n", resource.Title, resource.Link) } } else { fmt.Printf("Error: %s - %s\n", chatResp.Code, chatResp.Message) } } ``` ## Rate Limiting The `/v2/chat` endpoint enforces rate limits on three dimensions: - **Per API Key** - limits requests made with a single API Key within a 1-minute window. - **Per User (minute)** - limits the aggregate requests across all API Keys owned by a user within a 1-minute window. - **Per User (hour)** - limits the aggregate requests across all API Keys owned by a user within a 1-hour window. Any dimension being exceeded triggers a `429 Too Many Requests` response. > The exact numeric limits may change over time. **Always read them from the response headers below**, not from documentation snapshots. **Response headers (every response, including 429):** | Header | Meaning | |---|---| | `X-RateLimit-Limit` | Tighter of the two dimension limits currently in effect | | `X-RateLimit-Remaining` | Minimum remaining quota across both dimensions | | `X-RateLimit-Reset` | Unix timestamp (seconds) when the current window resets | **On 429, additionally:** | Header | Meaning | |---|---| | `Retry-After` | Recommended retry delay (seconds) | **Example 429 body** (the `message` reflects the current configured limits at request time): ```json { "status": 429, "code": "RATE_LIMITED", "message": "Too many requests. Limit: /min per API key, /min per user, /hour per user.", "request_id": "..." } ``` **Recommended client behavior:** 1. Read `X-RateLimit-Remaining` on every success response; back off proactively as it approaches `0`. 2. On 429, wait at least `Retry-After` seconds (or until `X-RateLimit-Reset`) before retrying. 3. Do not hardcode limit values - they may be tuned without API contract changes. If you need higher rate limits, contact support@felo.ai. ## Best Practices ### 1. Handle Errors Gracefully Always check the response status and handle errors appropriately: ```python if result['status'] == 'ok': # Process successful response answer = result['data']['answer'] else: # Handle error error_code = result['code'] error_message = result['message'] # Log error, show user-friendly message, etc. ``` ### 2. Implement Retry Logic For transient errors (5xx status codes), implement exponential backoff: ```python import time max_retries = 3 retry_delay = 1 # seconds for attempt in range(max_retries): response = requests.post(url, headers=headers, json=data) if response.status_code < 500: break # Success or client error, don't retry if attempt < max_retries - 1: time.sleep(retry_delay * (2 ** attempt)) # Exponential backoff ``` ### 3. Cache Responses Consider caching responses for identical queries to reduce API calls and improve response times. ### 4. Validate Input Validate user input before sending to the API: - Ensure query is not empty - Check query length (1-2000 characters) - Sanitize input to prevent injection attacks ### 5. Monitor Usage Track your API usage to stay within rate limits and optimize costs: - Log request counts and response times - Monitor error rates - Set up alerts for unusual patterns ## Support Need help with the Chat API? - Review the [Getting Started Guide](/docs/getting-started.html) - Check [Authentication Documentation](/docs/authentication) - Contact support at support@felo.ai with your request ID ## Changelog ### v2.0.0 (Current) - Initial release of Chat API - Support for natural language queries - Real-time web search integration - AI-generated answers with source citations --- # LLM API URL: https://openapi.felo.ai/docs/api-reference/llm Description: Call Felo model endpoints through OpenAI-compatible and Anthropic-compatible protocols. # LLM API The LLM API exposes direct model calling endpoints through Felo API Platform. Use it when you want to call general-purpose language models, reuse OpenAI-compatible or Anthropic-compatible clients, or connect agent frameworks to Felo API Platform. The LLM API currently includes three model calling surfaces: - `POST /api/v1/responses`: OpenAI Responses compatible - `POST /api/v1/chat/completions`: OpenAI Chat Completions compatible - `POST /api/v1/messages`: Anthropic Messages compatible ## Planned: Decisions API > Planned; not yet available on the public API. Confirm availability before using this example. ```http POST https://openapi.felo.ai/api/v1/decisions ``` Send state and narrow typed questions to `jev-1.13` (also accepted: `typesafe/jev-1.13`). Use `/api/v1/decisions`, not the Chat Completions, Messages, or Responses endpoints. Streaming is not supported. ### Request fields - `model`: `jev-1.13` - `state`: Context to evaluate; a string or JSON value. - `questions`: Named questions using `type`, `instructions`, and `criteria`. ```python import os import requests response = requests.post( "https://openapi.felo.ai/api/v1/decisions", headers={"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}, json={ "model": "jev-1.13", "state": "Help! My payouts have been failing for 3 days.", "questions": { "is_urgent": { "type": "noul", "instructions": "Does this message convey urgency?", "criteria": {"true": "Time-sensitive", "false": "No urgency"}, }, "department": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations", "sales": "Pricing, upgrades, new accounts", }, }, "frustration": { "type": "score", "instructions": "How frustrated is the customer?", "criteria": ["Calm", "Frustrated", "Very angry"], }, }, }, timeout=60, ) response.raise_for_status() answers = response.json()["answers"] print(answers["is_urgent"]["noul"]) print(answers["department"]["choice"], answers["department"]["probabilities"]) print(answers["frustration"]["score"]) ``` ### Answer types `noul`: a probability from 0 to 1. `choice`: the selected option and its probability distribution. `score`: a numeric score for ordered criteria, with its distribution. Errors use `error.code` (numeric HTTP status) and `error.message`. Handle non-2xx responses before reading `answers`. ### Usage and pricing The response includes `usage.input_tokens`, `usage.output_tokens`, and may include `usage.cost`. Reference rates checked on 2026-09-22: input USD 0.042 per million tokens; output USD 0. An output rate of zero does not make input usage free. Rates may change; use the published model price and applicable account discounts for estimates. ## Authentication LLM API requests require a Felo API Platform key. Use either `Authorization: Bearer ...` or `X-API-Key`. ```http Authorization: Bearer YOUR_API_KEY ``` ```http X-API-Key: YOUR_API_KEY ``` See the [Authentication Guide](/docs/authentication) for details on creating and managing API keys. ## Base URL Use the public Felo API Platform host: ```text https://openapi.felo.ai ``` For SDK clients, configure the protocol-specific base URL shown in [Basic Usage](#basic-usage). ## Common Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes, unless `X-API-Key` is used | API key in the format `Bearer YOUR_API_KEY` | | `X-API-Key` | Yes, unless `Authorization` is used | API key alternative to the Bearer header | | `Content-Type` | Yes | Must be `application/json` | | `X-Request-Id` | No | Optional request ID for troubleshooting | ## Model Discovery The general catalog includes all model categories. Use the dedicated lists to discover video or decision models: | Endpoint | Model categories | | --- | --- | | `GET /api/v1/models` | All categories (unchanged) | | `GET /api/v1/videos/models` | Video generation (`video_generation`) | | `GET /api/v1/decisions/models` | Decisions, including Jev (`decisions`) | All three endpoints accept the optional `provider` query parameter (for example, `openrouter`) and return `{"object":"list","data":[...]}`. Each item contains `id`, `object`, `created`, `owned_by`, and `model_kind`. Dedicated lists use the effective category after enabled provider mapping overrides. Only enabled, listed, non-deleted models with current pricing matching the provider conditions are returned; a zero price is valid. Newly synchronized models are hidden until an administrator lists them. All lists share the configured ordering, with model name and ID as tie-breakers. No matches returns HTTP 200 with an empty `data` array. Discovery reads the local catalog and does not invoke or charge for a model call. Only `GET /api/v1/models` accepts `exclude_video_and_decisions` (boolean, default `false`). Set it to `true` to exclude effective types `video_generation` and `decisions`; image models remain eligible. It can be combined with `provider`. Omitting it or setting `false` preserves the full catalog. Invalid boolean values return HTTP 422. ```bash curl "https://openapi.felo.ai/api/v1/models?exclude_video_and_decisions=true&provider=openrouter" \ -H "Authorization: Bearer ${FELO_API_KEY}" curl "https://openapi.felo.ai/api/v1/videos/models?provider=openrouter" \ -H "Authorization: Bearer ${FELO_API_KEY}" curl "https://openapi.felo.ai/api/v1/decisions/models?provider=openrouter" \ -H "Authorization: Bearer ${FELO_API_KEY}" ``` Choose a calling endpoint by `model_kind`: `chat` for Responses, Chat Completions, or Messages as supported by the model; `video_generation` for `POST /api/v1/videos/generations`; `decisions` for `POST /api/v1/decisions`; `image_generation` for `POST /api/v1/images/generations`. Details remain at `GET /api/v1/models/{model_id}`. A listed model is not necessarily compatible with every calling endpoint. ## Models and Pricing Requests use Felo API Platform's default model route. Do not send routing parameters in application requests. Prices are listed in USD. Token rates are shown per 1 million tokens for readability; billing uses the per-token precision from the current price snapshot. Cache rates apply only when the protocol response includes cache usage. A dash means no separate published rate or published limit. Web search usage, when reported by the model service, is charged at `$0.01` per search. | Model ID | Context | Max output | Input / 1M tokens | Output / 1M tokens | Cache read / 1M tokens | Cache write / 1M tokens | |----------|---------|------------|-------------------|--------------------|------------------------|-------------------------| | `claude-haiku-4-5` | 200K | 64K | `$1.00` | `$5.00` | `$0.10` | `$1.25` | | `claude-sonnet-4-6` | 1M | 128K | `$3.00` | `$15.00` | `$0.30` | `$3.75` | | `claude-opus-4-8` | 1M | 128K | `$5.00` | `$25.00` | `$0.50` | `$6.25` | | `claude-sonnet-5` | 1M | 128K | `$2.00` | `$10.00` | `$0.20` | `$2.50` | | `claude-haiku-5-5` | 1M | 128K | `$0.10` | `$0.50` | `$0.01` | `$0.0125` | | `gpt-5.5` | 1.05M | 128K | `$5.00` | `$30.00` | `$0.50` | - | | `gpt-5.5-pro` | 1.05M | 128K | `$30.00` | `$180.00` | - | - | | `gpt-5.6-luna` | 1.05M | 128K | `$1.00` | `$6.00` | `$0.10` | `$1.25` | | `gpt-5.6-terra` | 1.05M | 128K | `$2.50` | `$15.00` | `$0.25` | `$3.125` | | `gpt-5.6-sol` | 1.05M | 128K | `$5.00` | `$30.00` | `$0.50` | `$6.25` | | `grok-4.5` | 500K | - | `$2.00` | `$6.00` | `$0.50` | - | | `deepseek-v4-flash` | 1M | 384K | `$0.09` | `$0.18` | `$0.018` | - | Claude Haiku 5.5 uses tiered pricing: prompts up to 100K tokens are billed at the standard rates above, and requests whose prompt exceeds 100K tokens are billed at `$0.50` input, `$2.50` output, `$0.05` cache read, and `$0.0625` cache write per 1M tokens for the whole request. GPT-5.6 is available in three tiers: Luna for fast, cost-efficient workloads; Terra for balanced coding, reasoning, and agentic tasks; and Sol for flagship complex reasoning and coding. Each tier also exposes a `-pro` model ID (`gpt-5.6-luna-pro`, `gpt-5.6-terra-pro`, and `gpt-5.6-sol-pro`) that uses the same underlying model with pro reasoning mode. Pricing, context length, and maximum output are unchanged for the `-pro` IDs. DeepSeek V4 Flash supports reasoning and non-reasoning modes, JSON output, tool calls, Responses API, and Anthropic API compatibility. It is available through Felo's Responses, Chat Completions, and Messages surfaces. Cache write pricing is not yet published. ## Basic Usage These examples use the official OpenAI and Anthropic SDKs. Set `FELO_API_KEY` to your Felo API Platform key before running the examples. ```bash export FELO_API_KEY="YOUR_API_KEY" ``` ### Install SDKs #### OpenAI SDK Use the OpenAI SDK for the Responses API and Chat Completions API. ##### JavaScript ```bash npm install openai ``` ##### Python ```bash pip install openai ``` #### Anthropic SDK Use the Anthropic SDK for the Messages API. ##### JavaScript ```bash npm install @anthropic-ai/sdk ``` ##### Python ```bash pip install anthropic ``` ### Configure Clients OpenAI-compatible endpoints use the OpenAI SDK base URL with `/api/v1`, because the SDK appends resource paths such as `/responses` and `/chat/completions`. #### JavaScript ```js import OpenAI from "openai"; const openai = new OpenAI({ apiKey: process.env.FELO_API_KEY, baseURL: "https://openapi.felo.ai/api/v1", }); ``` #### Python ```python import os from openai import OpenAI openai = OpenAI( api_key=os.environ.get("FELO_API_KEY"), base_url="https://openapi.felo.ai/api/v1", ) ``` Anthropic-compatible endpoints use the Anthropic SDK base URL without `/v1`, because the SDK appends `/v1/messages`. #### JavaScript ```js import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.FELO_API_KEY, baseURL: "https://openapi.felo.ai/api", }); ``` #### Python ```python import os from anthropic import Anthropic anthropic = Anthropic( api_key=os.environ.get("FELO_API_KEY"), base_url="https://openapi.felo.ai/api", ) ``` ### Using the Responses API Use the Responses API for new OpenAI-compatible integrations and agent-style response objects. #### JavaScript ```js import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.FELO_API_KEY, baseURL: "https://openapi.felo.ai/api/v1", }); const response = await client.responses.create({ model: "gpt-5.6-sol", input: "Write a one-sentence bedtime story about a unicorn.", }); console.log(response.output_text); ``` #### Python ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("FELO_API_KEY"), base_url="https://openapi.felo.ai/api/v1", ) response = client.responses.create( model="gpt-5.6-sol", input="Write a one-sentence bedtime story about a unicorn.", ) print(response.output_text) ``` ### Using Chat Completions Use Chat Completions when your application already sends OpenAI-style `messages`. #### JavaScript ```js import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.FELO_API_KEY, baseURL: "https://openapi.felo.ai/api/v1", }); const completion = await client.chat.completions.create({ model: "gpt-5.6-sol", messages: [ { role: "user", content: "Give me one sentence about why API compatibility matters.", }, ], }); console.log(completion.choices[0].message.content); ``` #### Python ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("FELO_API_KEY"), base_url="https://openapi.felo.ai/api/v1", ) completion = client.chat.completions.create( model="gpt-5.6-sol", messages=[ { "role": "user", "content": "Give me one sentence about why API compatibility matters.", } ], ) print(completion.choices[0].message.content) ``` ### Using Messages Use Messages when your client or agent framework expects Anthropic-compatible request and response shapes. #### JavaScript ```js import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ apiKey: process.env.FELO_API_KEY, baseURL: "https://openapi.felo.ai/api", }); const message = await client.messages.create({ model: "claude-sonnet-4-6", max_tokens: 128, messages: [ { role: "user", content: "Summarize the value of direct model APIs in one sentence.", }, ], }); const text = message.content .filter((block) => block.type === "text") .map((block) => block.text) .join(""); console.log(text); ``` #### Python ```python import os from anthropic import Anthropic client = Anthropic( api_key=os.environ.get("FELO_API_KEY"), base_url="https://openapi.felo.ai/api", ) message = client.messages.create( model="claude-sonnet-4-6", max_tokens=128, messages=[ { "role": "user", "content": "Summarize the value of direct model APIs in one sentence.", } ], ) text = "".join(block.text for block in message.content if block.type == "text") print(text) ``` ## Official Documentation - [OpenAI API Quickstart](https://developers.openai.com/api/docs/quickstart) - [OpenAI Create response](https://developers.openai.com/api/reference/resources/responses/methods/create) - [OpenAI Create chat completion](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create) - [Claude Messages API](https://platform.claude.com/docs/en/api/messages) - [Anthropic TypeScript SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript) - [Anthropic Python SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python) For agent client setup, see [Claude Code and Codex Configuration](/docs/api-reference/v2/llm-agent-clients). ## Protocol Reference ### Responses Use this endpoint for OpenAI Responses API compatible clients and integrations. #### Endpoint ```http POST https://openapi.felo.ai/api/v1/responses ``` #### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `model` | string | Yes | Public Felo model ID | | `input` | string or array | Yes | User input, multi-turn input, or multimodal input | | `instructions` | string | No | System or developer instructions | | `stream` | boolean | No | Whether to use Server-Sent Events streaming | | `temperature` | number | No | Sampling temperature | | `max_output_tokens` | integer | No | Maximum output tokens | #### SDK Request ```js const response = await client.responses.create({ model: "gpt-5.6-sol", input: "Reply with exactly: responses ok", }); console.log(response.output_text); ``` #### Response Text Path ```text output_text ``` ### Chat Completions Use this endpoint for OpenAI Chat Completions compatible clients and SDKs. #### Endpoint ```http POST https://openapi.felo.ai/api/v1/chat/completions ``` #### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `model` | string | Yes | Public Felo model ID | | `messages` | array | Yes | Conversation messages | | `messages[].role` | string | Yes | `system`, `user`, or `assistant` | | `messages[].content` | string | Yes | Message content | | `stream` | boolean | No | Whether to use Server-Sent Events streaming | | `temperature` | number | No | Sampling temperature | | `max_tokens` | integer | No | Maximum output tokens | #### SDK Request ```js const completion = await client.chat.completions.create({ model: "gpt-5.6-sol", messages: [ { role: "user", content: "Reply with exactly: chat completions ok", }, ], }); console.log(completion.choices[0].message.content); ``` #### Response Text Path ```text choices[0].message.content ``` ### Messages Use this endpoint for Anthropic Messages compatible clients and SDKs. #### Endpoint ```http POST https://openapi.felo.ai/api/v1/messages ``` #### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `model` | string | Yes | Public Felo model ID | | `max_tokens` | integer | Yes | Maximum output tokens | | `messages` | array | Yes | Conversation messages | | `messages[].role` | string | Yes | `user` or `assistant` | | `messages[].content` | string or array | Yes | Plain text or Anthropic content blocks | | `system` | string | No | System prompt | | `stream` | boolean | No | Whether to use Server-Sent Events streaming | | `temperature` | number | No | Sampling temperature | #### SDK Request ```js const message = await client.messages.create({ model: "claude-sonnet-4-6", max_tokens: 64, messages: [ { role: "user", content: "Reply with exactly: messages ok", }, ], }); const text = message.content .filter((block) => block.type === "text") .map((block) => block.text) .join(""); console.log(text); ``` #### Content Block Request ```js const message = await client.messages.create({ model: "claude-sonnet-4-6", max_tokens: 64, messages: [ { role: "user", content: [ { type: "text", text: "Reply with exactly: messages ok", }, ], }, ], }); ``` #### Response Text Path ```text content[].text ``` ## Streaming Set `stream` to `true` to receive Server-Sent Events. The event payload format follows the selected protocol: - Responses streams return Responses-compatible response events. - Chat Completions streams return OpenAI-compatible chat completion chunks. - Messages streams return Anthropic-compatible message events. ```js const stream = await client.responses.create({ model: "gpt-5.6-sol", input: "Write one sentence.", stream: true, }); ``` Clients should parse the stream according to the protocol they are using rather than expecting one shared event schema across all three endpoints. ## Errors The LLM API returns the error shape of the selected protocol whenever possible. Common causes include: | HTTP Status | Cause | Suggested Action | |-------------|-------|------------------| | `400` | Invalid JSON body or missing required protocol fields | Check `model`, `messages`, `input`, `max_tokens`, and content block fields | | `401` | Missing or invalid API key | Verify `Authorization: Bearer ...` or `X-API-Key` | | `402` | Insufficient account credits | Check your Felo account balance | | `429` | Rate limit exceeded | Slow down requests and retry later | | `502` | Model service request failed | Retry and provide `X-Request-Id` when contacting support | | `503` | Model service temporarily unavailable | Retry with backoff or choose another published model | --- # PPT Task API URL: https://openapi.felo.ai/docs/api-reference/ppt-tasks Description: Create PPT generation tasks, list themes, and poll shared task endpoints. # PPT Task API The PPT Task API provides asynchronous PPT generation capabilities. You can create a task and then poll task status by `task_id`. You can also browse available PPT themes and apply them when creating tasks. ## Authentication All requests require an API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Use with AI Agents To create slides from an Agent, install the complete `felo-ai` package rather than a fixed subset of Skills. Its installer dynamically discovers every package directory containing `SKILL.md`, including the PPT Skill and future additions. Install all discovered Skills in the native directory for your Agent: Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. Follow the [manual AI Agent setup guide](/docs/felo-skills) for platform-specific API key configuration and verification. ## 1. List PPT Themes Query available PPT themes with pagination, keyword search, language and type filtering. ### Endpoint ``` GET https://openapi.felo.ai/v2/ppt-themes ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string | No | Language code for localized content (e.g. `en`, `zh-Hans`). Default: `en` | | `type` | string | No | Filter by theme type (e.g. `default`, `custom`) | | `keyword` | string | No | Search keyword, matches theme titles | | `page` | integer | No | Page number, starting from 1. Default: `1` | | `size` | integer | No | Page size, max 100. Default: `20` | ### Example ```bash curl -X GET 'https://openapi.felo.ai/v2/ppt-themes?lang=en&page=1&size=10' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 8, "page": 1, "size": 10, "items": [ { "id": "43122897-0d3c-4c9e-ae19-20527ad36c04", "title": "Inspiration Themes", "subtitle": "AI-tailored visual solutions", "description": "Style and layout, both crafted by AI from your content in real time" } ] } } ``` ### Theme Response Fields | Field | Type | Description | |-------|------|-------------| | `total` | integer | Total number of themes matching the filter | | `page` | integer | Current page number | | `size` | integer | Page size | | `items` | array | List of theme objects | | `items[].id` | string | Theme ID, use this as `ai_theme_id` when creating PPT | | `items[].title` | string | Theme title (localized) | | `items[].subtitle` | string | Theme subtitle (localized) | | `items[].description` | string | Theme description (localized) | ## 2. Create PPT Task ### Endpoint ``` POST https://openapi.felo.ai/v2/ppts ``` ### Request Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | Your API Key in the format `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | `application/json` or `multipart/form-data` | ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | PPT generation request prompt | | `livedoc_short_id` | string | No | Existing LiveDoc short ID to associate with the PPT session. If omitted, a new LiveDoc is created automatically. | | `resource_ids` | array of strings | No | List of LiveDoc resource IDs to use as context for PPT generation | | `ppt_config` | object | No | PPT configuration options | | `ppt_config.ai_theme_id` | string | No | Theme ID from the [List PPT Themes](#1-list-ppt-themes) endpoint | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/ppts' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "Felo, 2 pages", "ppt_config": { "ai_theme_id": "02968979-a69f-42c4-b136-de02c40ab2d7" } }' ``` ### Create from an Uploaded File Use `multipart/form-data` to upload one file and create a PPT task in a single request. The platform uploads the file as a LiveDoc resource first, then passes its resource ID to the PPT task. | Part | Type | Required | Description | |------|------|----------|-------------| | `query` | string | Yes | PPT generation request prompt | | `file` | file | Yes | Source file used as PPT context | | `stream_protocol` | string | No | Streaming protocol; defaults to `message_center_v1` | | `livedoc_short_id` | string | No | Existing LiveDoc to receive the file. A new LiveDoc is created when omitted. | | `ppt_config` | JSON | No | PPT configuration with the same structure as the JSON request body. Send this part as `application/json`. | ```bash curl -X POST 'https://openapi.felo.ai/v2/ppts' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'query=Create a 10-page presentation based on this report' \ -F 'ppt_config={"ai_theme_id":"02968979-a69f-42c4-b136-de02c40ab2d7"};type=application/json' \ -F 'file=@report.pdf' ``` The response uses the same schema as the JSON request. The returned `livedoc_short_id` identifies the LiveDoc containing the uploaded resource. ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3", "ppt_business_id": "BfLPuQKmChk9SPmyQawxgr", "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9" } } ``` ## 3. Query Task Status ### Endpoint ``` GET https://openapi.felo.ai/v2/tasks/{task_id}/status ``` ### Example ```bash curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "status": "RUNNING" } } ``` ## 4. Query Task Historical Info ### Endpoint ``` GET https://openapi.felo.ai/v2/tasks/{task_id}/historical ``` ### Example ```bash curl -X GET 'https://openapi.felo.ai/v2/tasks/019cb17e-9e23-3d40-4447-48a651249460/historical' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### RUNNING Response ```json { "status": "ok", "message": null, "data": { "task_id": "019cb17e-9e23-3d40-4447-48a651249460", "task_status": "RUNNING", "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx", "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx" } } ``` ### COMPLETED Response ```json { "status": "ok", "message": null, "data": { "task_id": "019cb17e-9e23-3d40-4447-48a651249460", "task_status": "COMPLETED", "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx", "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx", "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx", "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx" } } ``` ### COMPLETED Response (AI_PAGE) ```json { "status": "ok", "message": null, "data": { "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621", "task_status": "COMPLETED", "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ", "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ", "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ" } } ``` ### FAILED / PENDING / EXPIRED / CANCELED Response ```json { "status": "ok", "message": null, "data": { "task_id": "019cb17e-9e23-3d40-4447-48a651249460", "task_status": "FAILED", "ppt_biz_id": "oM8A9iJHg8dT4ZKgHThQTx", "ppt_url": "https://felo.ai/slides/oM8A9iJHg8dT4ZKgHThQTx", "error_message": "PPT generation failed", "live_doc_short_id": "oM8A9iJHg8dT4ZKgHThQTx", "live_doc_url": "https://felo.ai/livedoc/oM8A9iJHg8dT4ZKgHThQTx" } } ``` ### Historical Response Fields | Field | Type | Description | |------|------|-------------| | `task_id` | string | Task ID | | `task_status` | string | Current task status | | `ppt_biz_id` | string | PPT business ID (mapped from backend `thread_short_id`) | | `ppt_url` | string | PPT URL, format: `https://felo.ai/slides/{ppt_biz_id}` | | `error_message` | string | Present for `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`; empty string `""` when downstream does not provide error details | | `ai_page_html` | string | Present when the task runs in AI_PAGE mode and downstream historical returns an HTML result URL | | `live_doc_short_id` | string | LiveDoc short ID. For `COMPLETED` it comes from downstream `live_doc_short_id`; for terminal failure statuses it is returned when available | | `live_doc_url` | string | LiveDoc URL corresponding to `live_doc_short_id` | ## Export PPTX After the PPT generation task reaches `COMPLETED`, submit an asynchronous export using `ppt_business_id` from the create response (or `ppt_biz_id` from the historical response): ```bash curl -X POST 'https://openapi.felo.ai/v2/ppts/YOUR_PPT_BUSINESS_ID/export' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{}' ``` Poll `GET https://openapi.felo.ai/v2/ppts/{ppt_business_id}/export` with the same Bearer API Key every 2–5 seconds. The API Key owner must own the PPT. Both endpoints return `data.status`: `NOT_STARTED`, `PROCESSING`, `COMPLETED`, or `FAILED`. Only `COMPLETED` includes `download_url` and `expires_at`. The signed download URL expires **30 minutes after issuance**. Call the GET endpoint again for a fresh URL; this does not regenerate the PPTX. POST uses `application/json` and accepts `{}`. Repeating POST while an export is processing does not start another job; calling it after completion regenerates the PPTX and incurs the existing PPT export credit charge. Insufficient credits return HTTP 402. Endpoint-specific rate limits may apply; retry later on HTTP 429. A failed export can be submitted again. ```json { "status": "ok", "message": null, "data": { "status": "COMPLETED", "download_url": "https://example.com/presentation.pptx?signature=...", "expires_at": "2026-09-29T10:30:00Z" } } ``` ## Polling Recommendation Use `task_id` from create response and poll status every 2-5 seconds until the status becomes a terminal state. Common status examples: - `RUNNING`: task is still processing - `COMPLETED`: task completed successfully - `FAILED` / `PENDING` / `EXPIRED` / `CANCELED`: task reached terminal status with `error_message`; `live_doc_url` is also returned when available Unknown status values may appear as backend evolves; treat them as non-terminal unless documented otherwise. ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `PPT_TASK_CREATE_FAILED` | 502 | Create task downstream call failed | | `PPT_TASK_QUERY_FAILED` | 502 | Query task status downstream call failed | --- # Landing Page Task API URL: https://openapi.felo.ai/docs/api-reference/landing-page Description: Generate landing pages asynchronously and query task history. # Landing Page Task API The Landing Page Task API provides asynchronous landing page generation capabilities. You create a task first, then reuse the existing task polling APIs to query progress and results. ## Authentication All requests require an API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Use with AI Agents Install the complete `felo-ai` package to let an Agent generate landing pages and use every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, rather than relying on a fixed list. Install all discovered Skills in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. Read the [manual AI Agent setup guide](/docs/felo-skills) for the platform-specific API key and verification steps. ## Create Landing Page Task ### Endpoint ``` POST https://openapi.felo.ai/v2/landing_page ``` ### Request Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | Your API Key in the format `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | `application/json` or `multipart/form-data` | ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Landing page generation request prompt | | `stream_protocol` | string | No | Stream protocol. Default: `message_center_v1` | | `livedoc_short_id` | string | No | Existing LiveDoc short ID to use as context | | `resource_ids` | array of strings | No | LiveDoc resource IDs to use as context | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/landing_page' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "Generate a landing page for Felo Search" }' ``` ### Create With File Use `multipart/form-data` to upload one file with the Landing Page task request. The file is uploaded as a LiveDoc resource first, then its resource ID is passed to the Landing Page task. ```bash curl -X POST 'https://openapi.felo.ai/v2/landing_page' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'query=Generate a landing page from this product brief' \ -F 'file=@brief.pdf' ``` Optional multipart parts: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `stream_protocol` | string | No | Stream protocol. Default: `message_center_v1` | | `livedoc_short_id` | string | No | Existing LiveDoc short ID. If omitted, a new LiveDoc is created | ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9" } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `task_id` | string | Async task identifier for subsequent polling | ## Poll Task Status Landing Page tasks reuse the same task polling APIs as PPT tasks. ### Endpoint ``` GET https://openapi.felo.ai/v2/tasks/{task_id}/status ``` ### Example ```bash curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ## Query Task Historical Info ### Endpoint ``` GET https://openapi.felo.ai/v2/tasks/{task_id}/historical ``` ### Example ```bash curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/historical' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### AI_PAGE Completed Response Example ```json { "status": "ok", "message": null, "data": { "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621", "task_status": "COMPLETED", "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ", "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ", "ai_page_html": "https://felo.ai/ai-page/9qiLTmT77fA3aVurrMHvRJ" } } ``` Refer to the [PPT Task API](/docs/api-reference/ppt-tasks) for the shared polling response examples and status semantics. ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `LANDING_PAGE_TASK_CREATE_FAILED` | 502 | Landing page task creation failed | | `INSUFFICIENT_CREDITS` | 402 | Insufficient credits available | --- # SuperAgent API URL: https://openapi.felo.ai/docs/api-reference/superagent Description: Create conversations, consume SSE streams, follow up, and query conversation metadata. # SuperAgent API The SuperAgent API provides AI-powered conversation capabilities with real-time streaming output and LiveDoc integration. The typical workflow is: 1. **Create a conversation** - get `stream_key`, `thread_short_id`, and `live_doc_short_id` 2. **Consume the SSE stream** - connect to the stream endpoint using `stream_key` 3. **Follow up** - ask follow-up questions in the same conversation, get a new `stream_key` 4. **Query conversation detail** - use `thread_short_id` to fetch conversation metadata 5. **Manage LiveDocs** - see [LiveDoc API](./livedocs.md) for full CRUD and resource management ## Authentication All requests require an API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Use with AI Agents Install the complete `felo-ai` package to give an Agent SuperAgent workflows and every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, including future package additions. Install all discovered Skills in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. The [manual AI Agent setup guide](/docs/felo-skills) explains the safe installation process and per-platform configuration. --- ## 1. Create Conversation ### Endpoint ``` POST https://openapi.felo.ai/v2/conversations ``` ### Request Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | `application/json` | ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | User query, 1-2000 characters | | `live_doc_short_id` | string | No | Reuse an existing LiveDoc; omit to create a new one | | `selected_resource_ids` | array of strings | No | Resource IDs to include in context | | `skill_id` | string | No | Skill ID to use for this conversation | | `accept_language` | string | No | Language preference, e.g. `en` | | `device_id` | string | No | Device identifier | | `extra` | object | No | Extra parameters passed through to SuperAgent | | `ext` | object | No | Extension parameters (e.g. `style_id`, `theme`) | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/conversations' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "What is the latest news about AI?", "accept_language": "en", "skill_id": "your-skill-id", "device_id": "device-001", "ext": {"style_id": "xxx", "theme": "dark"} }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "stream_key": "sk_abc123xyz", "thread_short_id": "TvyKouzJirXjFdst4uKRK3", "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3" } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `stream_key` | string | Key used to consume the SSE stream (see section 2) | | `thread_short_id` | string | Conversation ID, used to query conversation detail | | `live_doc_short_id` | string | Associated LiveDoc ID | --- ## 2. Consume SSE Stream After creating a conversation, connect to the stream endpoint using the `stream_key` to receive real-time output. ### Endpoint ``` GET https://openapi.felo.ai/v2/conversations/stream/{stream_key} ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `offset` | integer | No | Resume streaming from this position. Use for reconnection after a disconnect. | ### Example ```bash curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: text/event-stream' ``` Reconnect with offset: ```bash curl -N 'https://openapi.felo.ai/v2/conversations/stream/sk_abc123xyz?offset=42' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: text/event-stream' ``` ### Response The response is a standard [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream with `Content-Type: text/event-stream`. Each event follows the SSE format: ``` event: data: ``` Example events: ``` event: message data: {"content": "The latest AI news includes..."} event: done data: {} ``` On upstream error: ``` event: error data: {"message": "upstream error: 502"} ``` ### Notes - Connect immediately after creating the conversation - `stream_key` has a limited validity window. - Use an SSE-capable client (e.g. `EventSource` in browsers, or `curl -N` in terminal). - The stream ends when a `done` event is received or the connection is closed by the server. --- ## 3. Follow Up Conversation Ask a follow-up question in an existing conversation. Returns a new `stream_key` to consume the response stream. ### Endpoint ``` POST https://openapi.felo.ai/v2/conversations/{thread_short_id}/follow_up ``` ### Request Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | `application/json` | ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Follow-up question, 1-2000 characters | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/conversations/TvyKouzJirXjFdst4uKRK3/follow_up' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "Can you elaborate on that?" }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "stream_key": "sk_def456uvw", "thread_short_id": "TvyKouzJirXjFdst4uKRK3", "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3" } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `stream_key` | string | Key used to consume the SSE stream for this follow-up | | `thread_short_id` | string | Same conversation ID as the request | | `live_doc_short_id` | string | Associated LiveDoc ID | --- ## 4. Query Conversation Detail ### Endpoint ``` GET https://openapi.felo.ai/v2/conversations/{thread_short_id} ``` ### Example ```bash curl 'https://openapi.felo.ai/v2/conversations/TvyKouzJirXjFdst4uKRK3' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "thread_short_id": "TvyKouzJirXjFdst4uKRK3", "title": "What is the latest news about AI?", "created_at": "2026-03-09T10:00:00Z", "updated_at": "2026-03-09T10:00:30Z", "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3" } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `thread_short_id` | string | Conversation ID | | `title` | string | Conversation title (derived from the query) | | `created_at` | string | Creation timestamp (ISO 8601) | | `updated_at` | string | Last update timestamp (ISO 8601) | | `live_doc_short_id` | string | Associated LiveDoc ID | --- ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `SUPER_AGENT_CONVERSATION_CREATE_FAILED` | 502 | Failed to create conversation (downstream error) | | `SUPER_AGENT_CONVERSATION_FOLLOW_UP_FAILED` | 502 | Failed to follow up conversation (downstream error) | | `SUPER_AGENT_CONVERSATION_QUERY_FAILED` | 502 | Failed to query conversation detail (downstream error) | --- ## Typical Integration Flow ``` 1. POST /v2/conversations → get stream_key + thread_short_id + live_doc_short_id 2. GET /v2/conversations/stream/{stream_key} → consume SSE until "done" 3. POST /v2/conversations/{thread_short_id}/follow_up → ask follow-up, get new stream_key 4. GET /v2/conversations/stream/{new_stream_key} → consume follow-up SSE until "done" 5. GET /v2/conversations/{thread_short_id} → fetch conversation metadata ``` For LiveDoc management (CRUD, resource upload, URL import, retrieval), see the [LiveDoc API](./livedocs.md). --- # LiveDoc API URL: https://openapi.felo.ai/docs/api-reference/livedocs Description: Create knowledge bases, manage resources, and run semantic retrieval and routing. # LiveDoc API The LiveDoc API provides full CRUD operations for LiveDocs and their resources, including document creation, file upload, URL import, and semantic retrieval. ## Authentication All requests require an API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Use with AI Agents Install the complete `felo-ai` package to give an Agent LiveDoc support and all other available Felo Skills. The installer dynamically discovers every package directory containing `SKILL.md`, including future package additions. Install all discovered Skills in the Agent's native directory: Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. The [manual AI Agent setup guide](/docs/felo-skills) covers the distinct API key and verification steps for each platform. --- ## 1. Create LiveDoc ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | Yes | LiveDoc name | | `description` | string | No | LiveDoc description | | `icon` | string | No | LiveDoc icon | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "AI Research Notes", "description": "Collection of AI research materials" }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "short_id": "PvyKouzJirXjFdst4uKRK3", "name": "AI Research Notes", "description": "Collection of AI research materials", "icon": null, "created_at": "2026-03-09T10:00:00Z", "modified_at": "2026-03-09T10:00:00Z" } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `short_id` | string | LiveDoc ID | | `name` | string | LiveDoc name | | `description` | string | LiveDoc description | | `icon` | string | LiveDoc icon | | `created_at` | string | Creation timestamp (ISO 8601) | | `modified_at` | string | Last modification timestamp (ISO 8601) | | `is_shared` | boolean | Whether this LiveDoc is shared with the current user (not owned by them) | --- ## 2. List LiveDocs ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `keyword` | string | No | Filter by keyword | | `page` | integer | No | Page number (1-based) | | `size` | integer | No | Page size | ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs?keyword=AI&page=1&size=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 2, "page": 1, "size": 20, "items": [ { "short_id": "PvyKouzJirXjFdst4uKRK3", "name": "AI Research Notes", "description": "Collection of AI research materials", "icon": null, "created_at": "2026-03-09T10:00:00Z", "modified_at": "2026-03-09T10:05:00Z", "is_shared": false, "readme": { "summary": "AI research notes and papers collection", "content": "# AI Research Notes\n\nThis LiveDoc contains..." } } ] } } ``` ### Response Fields Each item in `items` contains the same fields as the [Create LiveDoc response](#response-fields), plus: | Field | Type | Description | |-------|------|-------------| | `readme` | object \| null | README information. `null` if no README exists. | | `readme.summary` | string \| null | One-line project description | | `readme.content` | string \| null | README content (Markdown) | --- ### Endpoint ``` PUT https://openapi.felo.ai/v2/livedocs/{short_id} ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | New LiveDoc name | | `description` | string | No | New LiveDoc description | ### Example ```bash curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "Updated Research Notes" }' ``` ### Success Response (200) Returns the updated LiveDoc object (same structure as Create). --- ## 4. Delete LiveDoc ### Endpoint ``` DELETE https://openapi.felo.ai/v2/livedocs/{short_id} ``` ### Example ```bash curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": null } ``` --- ## 5. List Resources ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `resource_types` | string[] | No | Filter by resource types | | `page` | integer | No | Page number (1-based) | | `size` | integer | No | Page size | ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources?page=1&size=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 2, "page": 1, "size": 20, "items": [ { "id": "res_001", "title": "OpenAI Blog Post", "link": "https://openai.com/blog/...", "snippet": "Summary of the article...", "thumbnail": null, "resource_type": "web", "resource_key": "key_001", "status": "completed", "source": "url", "created_at": "2026-03-09T10:00:10Z", "modified_at": "2026-03-09T10:00:15Z" } ] } } ``` ### Resource Response Fields | Field | Type | Description | |-------|------|-------------| | `id` | string | Resource ID | | `title` | string | Resource title | | `link` | string | Resource link/URL | | `snippet` | string | Resource summary | | `thumbnail` | string | Thumbnail URL | | `resource_type` | string | Resource type (e.g. `web`, `ai_doc`, `file`) | | `resource_key` | string | Resource association key | | `status` | string | Resource status | | `source` | string | Resource source | | `created_at` | string | Creation timestamp (ISO 8601) | | `modified_at` | string | Last modification timestamp (ISO 8601) | --- ## 6. Get Single Resource ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id} ``` ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) Returns a single resource object (same structure as items in List Resources). --- ## 7. Update Resource Update a resource's `title`, `snippet`, or `thumbnail`. Only provided fields are updated; omitted fields retain their current values. ### Endpoint ``` PUT https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id} ``` ### Request Body All fields are optional. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | New resource title (max 500 characters) | | `snippet` | string | No | New resource summary (max 2000 characters) | | `thumbnail` | string | No | New thumbnail URL (max 2000 characters) | ### Example ```bash curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "title": "Updated Title", "snippet": "Updated summary of the resource." }' ``` ### Success Response (200) Returns the updated resource object (same structure as items in List Resources). --- ## 8. Update Resource Content Update the Markdown content of an `ai_doc` resource. Only supported for resources with `resource_type == ai_doc`. The `snippet` field is automatically updated from the first 2000 bytes of the new content. ### Endpoint ``` PUT https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/content ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | Yes | New Markdown content for the resource | ### Example ```bash curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/content' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "content": "# Updated Document\n\nThis is the new content." }' ``` ### Success Response (200) Returns the updated resource object (same structure as items in List Resources). --- ## 9. Create Document Resource ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/doc ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | Document title (defaults to "New Document") | | `content` | string | Yes | Document content | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/doc' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "title": "My Research Notes", "content": "Key findings from the AI research paper..." }' ``` ### Success Response (200) Returns the created resource object. --- ## 10. Upload File as Document Upload a file and convert it to a document resource (`ai_doc` type). ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/upload-doc ``` ### Content-Type `multipart/form-data` ### Request Parts | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | file | Yes | The file to upload | | `title` | string | No | Document title | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload-doc' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'file=@document.pdf' \ -F 'title=My PDF Document' ``` ### Success Response (200) Returns the created resource object. --- ## 11. Upload File Resource Upload a file and keep its original format. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/upload ``` ### Content-Type `multipart/form-data` ### Request Parts | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | file | Yes | The file to upload | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -F 'file=@report.xlsx' ``` ### Success Response (200) Returns the created resource object. --- ## 12. Add URL Resources Add one or more URLs as resources to a LiveDoc. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/urls ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `urls` | array | Yes | List of URL items to add (1-10). Each item can be a plain string or an object with `url` and optional `title`. | #### URL Item Formats Each entry in `urls` can be either: - A plain string: `"https://example.com/article"` - An object: `{"url": "https://example.com/article", "title": "Custom Title"}` | Field | Type | Required | Description | |-------|------|----------|-------------| | `url` | string | Yes | The URL to add (5-2000 characters) | | `title` | string | No | Custom title for the resource (max 1000 characters). If omitted, the title is auto-generated from the page. | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/urls' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "urls": [ "https://example.com/article-1", {"url": "https://example.com/article-2", "title": "My Custom Title"} ] }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": [ { "url": "https://example.com/article-1", "status": "success", "fail_reason": null, "resource_id": "res_003" }, { "url": "https://example.com/article-2", "status": "existed", "fail_reason": null, "resource_id": "res_004" } ] } ``` ### URL Result Fields | Field | Type | Description | |-------|------|-------------| | `url` | string | The processed URL | | `status` | string | Result status: `success`, `failed`, or `existed` | | `fail_reason` | string | Reason for failure (null if successful) | | `resource_id` | string | Created resource ID | --- ## 13. Delete Resource ### Endpoint ``` DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id} ``` ### Example ```bash curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": null } ``` --- ## 14. Retrieve (Semantic Search) Perform semantic retrieval against resources in a LiveDoc. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/retrieve ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Query content for semantic search | | `resource_ids` | string[] | No | Specific resource IDs to search within (1-50). If omitted, relevant resources are auto-routed by query | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/retrieve' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "latest developments in large language models", "resource_ids": ["res_001", "res_002"] }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": [ { "id": "res_001", "title": "LLM Research Paper", "content": "Relevant content excerpt...", "score": 0.92, "metadata": {} } ] } ``` ### Retrieve Result Fields | Field | Type | Description | |-------|------|-------------| | `id` | string | Resource ID | | `title` | string | Resource title | | `content` | string | Matched content | | `score` | number | Relevance score | | `metadata` | object | Additional metadata | --- ## 15. Route Resources Route relevant resources from a LiveDoc based on a query. Returns a list of resource IDs that can be passed to the retrieve endpoint. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/route ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Query content for routing | | `max_resources` | integer | No | Maximum number of resource IDs to return | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/route' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "latest developments in large language models", "max_resources": 5 }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": ["res_001", "res_003", "res_007"] } ``` --- ## 16. Download Resource Source File Get the source file of a resource. Returns a `302` redirect to the presigned download URL. Only supported for resources that have an associated source file (e.g. uploaded documents). ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/download ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `expires_in` | integer | No | URL expiry in seconds (default: 3600) | ### Example ```bash curl -L 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/download' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Response Returns `302 Found` with a `Location` header pointing to the presigned S3 download URL. HTTP clients with redirect support (e.g. `curl -L`) will follow the redirect and download the file directly. --- ## 17. Get Resource Content Fetch the extracted text content of a resource. Supported for most resource types (document, web, video, ai_doc, ai_ppt, text, voice, mindmap, etc.). Returns 400 for unsupported types such as `image`. ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/content ``` ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/content' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "title": "Q4 Financial Report", "type": "document", "content": "Full extracted text content of the resource..." } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `title` | string | Resource title | | `type` | string | Resource type | | `content` | string | Extracted text content | --- ## 18. PPT Page Retrieve Perform deep content retrieval on a specific page of a PPT resource. Scrapes the slide page and returns ranked content chunks. The response format is identical to the [Retrieve](#14-retrieve-semantic-search) endpoint. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/ppt-retrieve ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `resource_id` | string | Yes | PPT resource ID | | `page_number` | integer | Yes | Page number to retrieve (starts from 1) | | `query` | string | Yes | Query content describing what to look for | | `max_chunk` | integer | No | Maximum number of chunks to return (default: 3) | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/ppt-retrieve' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "resource_id": "res_001", "page_number": 3, "query": "product pricing information", "max_chunk": 3 }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": [ { "id": "res_001_page_3_chunk_1", "title": "Q4 Product Deck", "content": "Relevant slide content excerpt...", "score": null, "metadata": { "resource_id": "res_001", "page_number": 3, "index": 1 } } ] } ``` ### Response Fields Same as [Retrieve Result Fields](#retrieve-result-fields). --- ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `LIVEDOC_CREATE_FAILED` | 502 | Failed to create LiveDoc | | `LIVEDOC_UPDATE_FAILED` | 502 | Failed to update LiveDoc | | `LIVEDOC_DELETE_FAILED` | 502 | Failed to delete LiveDoc | | `LIVEDOC_NOT_FOUND` | 404 | LiveDoc not found | | `LIVEDOC_LIST_FAILED` | 502 | Failed to list LiveDocs | | `LIVEDOC_RESOURCE_CREATE_FAILED` | 502 | Failed to create resource | | `LIVEDOC_RESOURCE_UPLOAD_FAILED` | 502 | Failed to upload resource | | `LIVEDOC_RESOURCE_DELETE_FAILED` | 502 | Failed to delete resource | | `LIVEDOC_RESOURCE_NOT_FOUND` | 404 | Resource not found | | `LIVEDOC_RESOURCE_LIST_FAILED` | 502 | Failed to list resources | | `LIVEDOC_RESOURCE_RETRIEVE_FAILED` | 502 | Failed to retrieve resources | | `LIVEDOC_RESOURCE_ADD_URLS_FAILED` | 502 | Failed to add URL resources | --- ## 19. Get README Get the README content of a LiveDoc. Returns an empty string if no README has been set. ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/readme ``` ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "summary": "A brief one-line description of the project.", "content": "# My LiveDoc\n\nThis is the README content in Markdown." } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `summary` | string \| null | One-line project description. Max 2000 characters. | | `content` | string | README content (Markdown). Empty string if not set. | --- ## 20. Create or Update README Create or update the README of a LiveDoc (upsert semantics). ### Endpoint ``` PUT https://openapi.felo.ai/v2/livedocs/{short_id}/readme ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `summary` | string | No | One-line project description (max 2000 characters) | | `content` | string | No | README content (Markdown) | > **Note:** At least one of `summary` or `content` must be provided. ### Example ```bash curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "summary": "A brief one-line description of the project.", "content": "# My LiveDoc\n\nThis is the README content in Markdown." }' ``` ### Success Response (200) Returns the updated README object (same structure as Get README). --- ## 21. Append to README Append content to the end of an existing README. If no README exists, creates a new one with the provided content. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/readme/append ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | Yes | Content to append (Markdown) | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme/append' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "content": "\n\n## New Section\n\nAdditional content appended to README." }' ``` ### Success Response (200) Returns the complete README object after appending (same structure as Get README). --- ## 22. Delete README Delete the README of a LiveDoc. ### Endpoint ``` DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/readme ``` ### Example ```bash curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": null } ``` --- ## 23. List Tasks Get a paginated list of tasks in a LiveDoc. Results are sorted by `sort` asc, `status` asc, `created_at` desc. ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/tasks ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `status` | integer | No | Filter by status: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE | | `labels` | string[] | No | Filter by labels (tasks must contain all specified labels) | | `page` | integer | No | Page number (1-based) | | `size` | integer | No | Page size | ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks?status=0&page=1&size=20' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 1, "page": 1, "size": 20, "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "title": "Write documentation", "description": "Write API documentation for the new endpoints", "status": 0, "sort": 0, "labels": ["docs", "priority-high"], "created_at": "2026-03-19T10:00:00Z", "modified_at": "2026-03-19T10:00:00Z" } ] } } ``` ### Task Response Fields | Field | Type | Description | |-------|------|-------------| | `id` | string | Task ID (UUID) | | `title` | string | Task title | | `description` | string | Task description | | `status` | integer | Task status: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE | | `sort` | integer | Sort order (non-negative) | | `labels` | string[] | Label list | | `operated_by` | string | Operator signature, e.g. `claude-code`, `openclaw` | | `created_at` | string | Creation timestamp (ISO 8601) | | `modified_at` | string | Last modification timestamp (ISO 8601) | --- ## 24. Create Task Create a new task in a LiveDoc. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/tasks ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | Yes | Task title | | `description` | string | No | Task description | | `status` | integer | Yes | Task status: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE | | `sort` | integer | Yes | Sort order (non-negative integer) | | `labels` | string[] | No | Label list (max 10, each max 50 characters) | | `operated_by` | string | No | Operator signature, e.g. `claude-code`, `openclaw` (max 100 characters) | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "title": "Write documentation", "description": "Write API documentation for the new endpoints", "status": 0, "sort": 0, "labels": ["docs", "priority-high"] }' ``` ### Success Response (200) Returns the created task object (same structure as items in List Tasks). --- ## 25. Update Task Partially update a task. Only provided fields are updated; omitted fields retain their current values. ### Endpoint ``` PATCH https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id} ``` ### Request Body All fields are optional. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | New task title | | `description` | string | No | New task description | | `status` | integer | No | New status: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE | | `sort` | integer | No | New sort order (non-negative) | | `labels` | string[] | No | New label list (max 10, each max 50 characters) | | `operated_by` | string | No | Operator signature, e.g. `claude-code`, `openclaw` (max 100 characters) | ### Example ```bash curl -X PATCH 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "status": 1 }' ``` ### Success Response (200) Returns the updated task object (same structure as items in List Tasks). --- ## 26. Delete Task Soft-delete a task. ### Endpoint ``` DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id} ``` ### Example ```bash curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": null } ``` --- ## 27. List Task Records Get a paginated list of records for a task (comments and change history), sorted by `created_at` ascending. ### Endpoint ``` GET https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}/records ``` ### Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `record_type` | string | No | Filter by record type: `comment`, `edit`, `status_change` | | `page` | integer | No | Page number (1-based) | | `size` | integer | No | Page size | ### Example ```bash curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000/records' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 2, "page": 1, "size": 20, "items": [ { "id": "rec_001", "record_type": "comment", "content": "This is a comment", "meta": null, "task_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-03-19T10:05:00Z", "modified_at": "2026-03-19T10:05:00Z" }, { "id": "rec_002", "record_type": "status_change", "content": null, "meta": {"from": 0, "to": 1}, "task_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-03-19T10:10:00Z", "modified_at": "2026-03-19T10:10:00Z" } ] } } ``` ### Task Record Response Fields | Field | Type | Description | |-------|------|-------------| | `id` | string | Record ID | | `record_type` | string | Record type: `comment` / `edit` / `status_change` | | `content` | string | Comment text (only for `comment` type) | | `meta` | object | Change details (for `edit` and `status_change` types) | | `task_id` | string | Parent task ID | | `operated_by` | string | Operator signature, e.g. `claude-code`, `openclaw` | | `created_at` | string | Creation timestamp (ISO 8601) | | `modified_at` | string | Last modification timestamp (ISO 8601) | --- ## 28. Add Task Comment Add a comment to a task. ### Endpoint ``` POST https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}/comments ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | Yes | Comment content | | `operated_by` | string | No | Operator signature, e.g. `claude-code`, `openclaw` (max 100 characters) | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000/comments' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "content": "This task is now in progress." }' ``` ### Success Response (200) Returns the created record object (same structure as items in List Task Records). --- ## Error Codes (Updated) | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `LIVEDOC_CREATE_FAILED` | 502 | Failed to create LiveDoc | | `LIVEDOC_UPDATE_FAILED` | 502 | Failed to update LiveDoc | | `LIVEDOC_DELETE_FAILED` | 502 | Failed to delete LiveDoc | | `LIVEDOC_NOT_FOUND` | 404 | LiveDoc not found | | `LIVEDOC_LIST_FAILED` | 502 | Failed to list LiveDocs | | `LIVEDOC_RESOURCE_CREATE_FAILED` | 502 | Failed to create resource | | `LIVEDOC_RESOURCE_UPLOAD_FAILED` | 502 | Failed to upload resource | | `LIVEDOC_RESOURCE_DELETE_FAILED` | 502 | Failed to delete resource | | `LIVEDOC_RESOURCE_NOT_FOUND` | 404 | Resource not found | | `LIVEDOC_RESOURCE_LIST_FAILED` | 502 | Failed to list resources | | `LIVEDOC_RESOURCE_RETRIEVE_FAILED` | 502 | Failed to retrieve resources | | `LIVEDOC_RESOURCE_ADD_URLS_FAILED` | 502 | Failed to add URL resources | | `LIVEDOC_README_GET_FAILED` | 502 | Failed to get README | | `LIVEDOC_README_UPDATE_FAILED` | 502 | Failed to create or update README | | `LIVEDOC_README_DELETE_FAILED` | 502 | Failed to delete README | | `LIVEDOC_README_NOT_FOUND` | 404 | README not found | | `LIVEDOC_TASK_LIST_FAILED` | 502 | Failed to list tasks | | `LIVEDOC_TASK_CREATE_FAILED` | 502 | Failed to create task | | `LIVEDOC_TASK_UPDATE_FAILED` | 502 | Failed to update task | | `LIVEDOC_TASK_DELETE_FAILED` | 502 | Failed to delete task | | `LIVEDOC_TASK_NOT_FOUND` | 404 | Task not found | | `LIVEDOC_TASK_RECORD_LIST_FAILED` | 502 | Failed to list task records | | `LIVEDOC_TASK_COMMENT_CREATE_FAILED` | 502 | Failed to create task comment | --- # Web Fetch API URL: https://openapi.felo.ai/docs/api-reference/web-fetch Description: Extract webpage content as HTML, text, or Markdown with selector and readability options. # Web Fetch API The Web Fetch API extracts content from a target URL and returns the result in a format that is easier for agents, RAG systems, and content workflows to process. It can return HTML, plain text, or Markdown, and it supports selectors, readability options, cache control, custom user agents, and request cookies. ## Endpoint ```http POST https://openapi.felo.ai/v2/web/extract ``` ## Authentication Send your API key in the `Authorization` header: ```http Authorization: Bearer YOUR_API_KEY ``` See the [Authentication Guide](/docs/authentication) for details on creating and managing API keys. ## Use with AI Agents Install the complete `felo-ai` package when you want an Agent to extract webpages alongside every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, so it never relies on a fixed list. Install all discovered Skills in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. Use the [manual AI Agent setup guide](/docs/felo-skills) for each platform's safe installation and API key steps. ## Request ### Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | Your API key in the format `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | Must be `application/json` | ### Body Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `url` | string | Yes | - | The webpage URL to extract. | | `crawl_mode` | string | No | `fast` | Extraction mode. Use `fast` for a quicker fetch or `fine` for a more precise crawl that may handle richer pages. | | `output_format` | string | No | `html` | Output format. Supported values: `html`, `text`, `markdown`. | | `with_readability` | boolean or string | No | - | Enable readability processing to focus on main content and reduce page noise. | | `with_links_summary` | boolean | No | - | Include a summary of links when supported by the downstream extractor. | | `with_images_summary` | boolean | No | - | Include a summary of images when supported. | | `with_images_readability` | boolean | No | - | Apply readability handling to image extraction when supported. | | `with_images` | boolean | No | - | Include image information in the extracted result. | | `with_links` | boolean | No | - | Include link information in the extracted result. | | `ignore_empty_text_image` | boolean | No | - | Ignore images that do not contain useful text when supported. | | `target_selector` | string | No | - | CSS selector for the target element to extract, such as `article.main-content`. | | `wait_for_selector` | string | No | - | Wait until a CSS selector appears before extraction. Useful for dynamically rendered pages. | | `set_cookies` | array | No | - | Cookies to send with the extraction request. | | `user_agent` | string | No | - | Custom User-Agent string for the extraction request. | | `timeout` | integer | No | - | Request timeout in milliseconds. | | `with_cache` | boolean | No | `true` | Whether the downstream extractor may use cache. | | `with_stypes` | boolean | No | `false` | Include style-type metadata when supported. | ## Response ### Success Response The response uses a transparent pass-through design. The exact fields inside `data` can vary based on `output_format` and other extraction options. ```json { "status": "ok", "message": null, "data": { "content": "# Example Article\n\nExtracted article content..." } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `status` | string | Response status. Usually `ok` for a successful request. | | `message` | string or null | Additional message. Usually `null` for successful requests. | | `data` | object | Extracted content and metadata returned by the downstream extraction service. | | `data.content` | string or object | Extracted content. The shape depends on `output_format` and selected options. | ## Error Responses | HTTP Status | Error Code | Description | Suggested Action | |-------------|------------|-------------|------------------| | 400 | `WEB_EXTRACT_FAILED` | Request validation failed, the URL is invalid, or the downstream extractor returned a client-side error. | Check `url`, selectors, and request parameters. | | 401 | `INVALID_API_KEY` | API key is missing, invalid, or revoked. | Verify your API key and authorization header. | | 500 | `WEB_EXTRACT_FAILED` | Internal service error. | Retry the request. Contact support if the issue persists. | ## Examples ### Basic Extraction ```bash curl -X POST https://openapi.felo.ai/v2/web/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com" }' ``` ### Extract Markdown With Readability ```bash curl -X POST https://openapi.felo.ai/v2/web/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/article", "output_format": "markdown", "with_readability": true }' ``` ### Extract a Specific CSS Selector ```bash curl -X POST https://openapi.felo.ai/v2/web/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/article", "target_selector": "article.main-content", "output_format": "text" }' ``` ### Wait for Dynamic Content ```bash curl -X POST https://openapi.felo.ai/v2/web/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/app", "crawl_mode": "fine", "wait_for_selector": "#loaded-content", "output_format": "markdown", "timeout": 30000 }' ``` ## Use Cases - Give an agent webpage context before answering a question. - Extract article text for RAG ingestion or knowledge-base creation. - Convert webpages into Markdown for archiving or documentation workflows. - Pull focused content from a page by using CSS selectors. - Reduce page noise with readability processing before downstream AI analysis. ## Notes - The API handles one URL per request. - `data` is passed through from the downstream extraction service, so additional fields may appear over time. - `fine` mode may be slower than `fast`, but can be useful when the page needs richer rendering behavior. - Some pages may block extraction, require cookies, or need a custom `user_agent`. --- # YouTube Subtitling API URL: https://openapi.felo.ai/docs/api-reference/youtube-subtitling Description: Fetch YouTube subtitles with optional language and timestamp parameters. # YouTube Subtitling API The YouTube Subtitling API fetches structured subtitle data for a YouTube video. It is designed for agents, content analysis tools, education products, search indexes, and workflows that need video content as text. ## Endpoint ```http GET https://openapi.felo.ai/v2/youtube/subtitling ``` ## Authentication Send your API key in the `Authorization` header: ```http Authorization: Bearer YOUR_API_KEY ``` See the [Authentication Guide](/docs/authentication) for details on creating and managing API keys. ## Use with AI Agents Install the complete `felo-ai` package to give an Agent YouTube subtitling and every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, so it does not depend on a fixed Skill list. Install all discovered Skills in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. Use the [manual AI Agent setup guide](/docs/felo-skills) for platform-specific API key configuration and verification. ## Request ### Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `video_code` | string | Yes | - | YouTube video ID, such as `dQw4w9WgXcQ`. | | `language` | string | No | - | Subtitle language code, such as `en` or `zh-CN`. If omitted, the downstream service chooses the available language. | | `with_time` | boolean | No | `false` | Whether to include timestamp fields (`start` and `duration`) for each subtitle item. | The service uses the full title-and-transcript mode internally. You do not need to pass a function type or mode parameter. ## Response ### Success Response ```json { "status": "ok", "message": null, "data": { "title": "Example Video Title", "contents": [ { "start": 0.32, "duration": 14.26, "text": "Subtitle text" } ] } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `status` | string | Response status. Usually `ok` for a successful request. | | `message` | string or null | Additional message. Usually `null` for successful requests. | | `data.title` | string | YouTube video title. | | `data.contents` | array | List of subtitle items. | | `data.contents[].start` | number | Subtitle start time in seconds. Returned when timestamp data is available, especially when `with_time=true`. | | `data.contents[].duration` | number | Subtitle duration in seconds. Returned when timestamp data is available, especially when `with_time=true`. | | `data.contents[].text` | string | Subtitle text content. | ## Error Responses | HTTP Status | Error Code | Description | Suggested Action | |-------------|------------|-------------|------------------| | 400 | `YOUTUBE_SUBTITLING_FAILED` | Request validation failed, the video does not exist, subtitles are unavailable, or the downstream service returned a client-side error. | Check `video_code`, subtitle availability, and `language`. | | 401 | `INVALID_API_KEY` | API key is missing, invalid, or revoked. | Verify your API key and authorization header. | | 500 | `YOUTUBE_SUBTITLING_FAILED` | Internal service error. | Retry the request. Contact support if the issue persists. | | 502 | `YOUTUBE_SUBTITLING_FAILED` | The downstream YouTube subtitle service failed or was unavailable. | Retry later. | ## Examples ### Basic Request ```bash curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Request a Specific Language ```bash curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ&language=en" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Include Timestamps ```bash curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ&with_time=true" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Include Timestamps for a Specific Language ```bash curl -X GET "https://openapi.felo.ai/v2/youtube/subtitling?video_code=dQw4w9WgXcQ&language=zh-CN&with_time=true" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Use Cases - Let an agent understand a YouTube video before answering questions. - Build a searchable text index for video content. - Prepare source text for summarization or translation workflows. - Map generated notes or quotes back to timestamps. - Analyze educational or research videos without downloading the video file. ## Notes - This API does not download video or audio. - It returns existing subtitles. It does not generate subtitles for videos that do not have subtitle data. - Some videos may not have subtitles, or may not provide the requested language. - If `language` is omitted, subtitle language selection depends on downstream availability. --- # X Search API URL: https://openapi.felo.ai/docs/api-reference/x-search Description: Search X users, tweets, timelines, and replies with pagination metadata. # X (Twitter) Search API The X Search API provides access to X (Twitter) data, including user profiles, tweet search, user tweets, and tweet replies. ## Authentication All requests require an API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Use with AI Agents Install the complete `felo-ai` package to give an Agent X Search and every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, instead of keeping a fixed Skill list. Install all discovered Skills in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. See the [manual AI Agent setup guide](/docs/felo-skills) for platform-specific installation, API key, and verification instructions. --- ## 1. Get User Info Batch retrieve X user profiles by username. ### Endpoint ``` POST https://openapi.felo.ai/v2/x/user/info ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `usernames` | array of strings | Yes | List of X usernames to look up | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/x/user/info' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "usernames": ["elonmusk", "OpenAI"] }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 2, "users": [ { "user_id": "44196397", "username": "elonmusk", "display_name": "Elon Musk", "description": "...", "followers_count": 100000000, "following_count": 500, "tweet_count": 30000, "verified": true, "blue_verified": true, "profile_image_url": "https://pbs.twimg.com/...", "created_at": "2009-06-02T00:00:00Z", "location": "Mars" } ] } } ``` ### User Object Fields | Field | Type | Description | |-------|------|-------------| | `user_id` | string | X user ID | | `username` | string | X handle (without @) | | `display_name` | string | Display name | | `description` | string | User bio | | `followers_count` | integer | Number of followers | | `following_count` | integer | Number of following | | `tweet_count` | integer | Total tweets | | `verified` | boolean | Whether the account is verified | | `blue_verified` | boolean | Whether the account has Blue verification | | `verified_type` | string | Verification type | | `profile_image_url` | string | Profile image URL | | `cover_image_url` | string | Cover image URL | | `created_at` | string | Account creation time | | `location` | string | User location | | `url` | string | User website URL | | `protected` | boolean | Whether the account is protected | | `favorites_count` | integer | Number of likes | | `media_count` | integer | Number of media posts | | `can_dm` | boolean | Whether DM is open | | `is_automated` | boolean | Whether the account is automated | | `pinned_tweet_ids` | array of strings | Pinned tweet IDs | --- ## 2. Search Users Search X users by keyword. ### Endpoint ``` POST https://openapi.felo.ai/v2/x/user/search ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Search keyword | | `cursor` | string | No | Pagination cursor from previous response | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/x/user/search' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "artificial intelligence" }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 50, "has_next": true, "next_cursor": "cursor_abc123", "users": [ { "user_id": "...", "username": "...", "display_name": "..." } ] } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `total` | integer | Total number of results | | `has_next` | boolean | Whether more results are available | | `next_cursor` | string | Cursor for next page | | `users` | array | List of user objects (see section 1) | --- ## 3. Get User Tweets Retrieve tweets from a specific X user. ### Endpoint ``` POST https://openapi.felo.ai/v2/x/user/tweets ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `x_user_id` | string | No | X user ID (provide either `x_user_id` or `username`) | | `username` | string | No | X username (provide either `x_user_id` or `username`) | | `limit` | integer | No | Number of tweets to return | | `cursor` | string | No | Pagination cursor | | `include_replies` | boolean | No | Whether to include replies | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/x/user/tweets' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "username": "elonmusk", "limit": 20 }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 20, "has_next": true, "next_cursor": "cursor_def456", "tweets": [ { "id": "1234567890", "content": "Tweet content here...", "author": { "user_id": "...", "username": "elonmusk" }, "created_at": "2026-03-09T12:00:00Z", "metrics": { "retweet_count": 1000, "favorite_count": 5000, "reply_count": 200, "quote_count": 100, "view_count": 500000, "bookmark_count": 50 }, "hashtags": ["AI"], "mentions": ["OpenAI"], "url": "https://x.com/elonmusk/status/1234567890", "lang": "en" } ] } } ``` ### Tweet Object Fields | Field | Type | Description | |-------|------|-------------| | `id` | string | Tweet ID | | `content` | string | Tweet text content | | `author` | object | Author user object (see section 1) | | `created_at` | string | Tweet creation time | | `metrics` | object | Engagement metrics (see below) | | `replies` | array | Reply tweets (if available) | | `conversation_id` | string | Conversation thread ID | | `media_urls` | array | Attached media | | `hashtags` | array of strings | Hashtags in the tweet | | `mentions` | array of strings | Mentioned usernames | | `urls` | array of strings | URLs in the tweet | | `url` | string | Permalink to the tweet | | `source` | string | Tweet source (e.g. "Twitter Web App") | | `lang` | string | Tweet language code | | `is_reply` | boolean | Whether this is a reply | | `in_reply_to_id` | string | ID of the tweet being replied to | | `in_reply_to_user_id` | string | User ID of the tweet being replied to | | `in_reply_to_username` | string | Username of the tweet being replied to | | `quoted_tweet` | object | Quoted tweet object (recursive) | | `retweeted_tweet` | object | Retweeted tweet object (recursive) | | `is_limited_reply` | boolean | Whether replies are limited | ### Metrics Object Fields | Field | Type | Description | |-------|------|-------------| | `retweet_count` | integer | Number of retweets | | `favorite_count` | integer | Number of likes | | `reply_count` | integer | Number of replies | | `quote_count` | integer | Number of quotes | | `view_count` | integer | Number of views | | `bookmark_count` | integer | Number of bookmarks | --- ## 4. Search Tweets Search X tweets by keyword with advanced query support. ### Endpoint ``` POST https://openapi.felo.ai/v2/x/tweet/search ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | Search query (supports advanced search syntax) | | `query_type` | string | No | Query type filter | | `since_time` | integer | No | Start time filter (Unix timestamp in seconds) | | `until_time` | integer | No | End time filter (Unix timestamp in seconds) | | `limit` | integer | No | Number of tweets to return | | `cursor` | string | No | Pagination cursor | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/x/tweet/search' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "artificial intelligence", "limit": 20 }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "total": 20, "has_next": true, "next_cursor": "cursor_ghi789", "tweets": [ { "id": "...", "content": "...", "author": { "user_id": "...", "username": "..." }, "created_at": "2026-03-09T12:00:00Z", "metrics": { "retweet_count": 100, "favorite_count": 500 } } ] } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `total` | integer | Total number of results | | `has_next` | boolean | Whether more results are available | | `next_cursor` | string | Cursor for next page | | `tweets` | array | List of tweet objects (see section 3) | --- ## 5. Get Tweet Replies Retrieve replies for specific tweets. ### Endpoint ``` POST https://openapi.felo.ai/v2/x/tweet/replies ``` ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tweet_ids` | array of strings | Yes | Tweet ID(s) to get replies for | | `cursor` | string | No | Pagination cursor | | `since_time` | integer | No | Start time filter (Unix timestamp) | | `until_time` | integer | No | End time filter (Unix timestamp) | ### Example ```bash curl -X POST 'https://openapi.felo.ai/v2/x/tweet/replies' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "tweet_ids": ["1234567890"] }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "results": [ { "tweet_id": "1234567890", "total": 10, "has_next": true, "next_cursor": "cursor_jkl012", "replies": [ { "id": "...", "content": "Great tweet!", "author": { "user_id": "...", "username": "..." }, "created_at": "2026-03-09T12:30:00Z" } ] } ] } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `results` | array | List of reply result objects | | `results[].tweet_id` | string | Original tweet ID | | `results[].total` | integer | Total number of replies | | `results[].has_next` | boolean | Whether more replies are available | | `results[].next_cursor` | string | Cursor for next page | | `results[].replies` | array | List of reply tweet objects (see section 3) | --- ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `X_SEARCH_FAILED` | 400/500 | X search request failed (check parameters or downstream error) | | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests, please retry after a short delay | | `insufficient_credits` | 402 | Insufficient credits to complete the request | --- ## Credits & Rate Limiting ### Credit Costs Each API call deducts credits based on the number of results returned: | Endpoint | Credit Cost | |----------|-------------| | `POST /x/user/info` | 1 credit per user returned | | `POST /x/user/search` | 1 credit per user returned | | `POST /x/user/tweets` | 1 credit per tweet returned | | `POST /x/tweet/search` | 1 credit per tweet returned | | `POST /x/tweet/replies` | 1 credit per reply returned | Credits are deducted after the request completes, based on the actual number of results. If a request returns 0 results, no credits are deducted. **Minimum balance requirement:** Your account must have at least 10 credits to make any X API request. Requests made with fewer than 10 credits will be rejected with HTTP 402. ### Rate Limiting Non-paid-subscriber accounts with a credit balance under 100 are subject to rate limiting: | Window | Limit | |--------|-------| | 10 seconds | 1 request | | 1 minute | 3 requests | | 10 minutes | 10 requests | Paid subscribers are exempt from rate limiting regardless of credit balance. When rate limited, the API returns HTTP 429. The `Retry-After` header indicates the suggested wait time in seconds. --- # Mindmap API URL: https://openapi.felo.ai/docs/api-reference/mindmap Description: Create mindmaps from prompts and optional LiveDoc context. # Mindmap API The Mindmap API provides mindmap generation capabilities. You can create a mindmap with a topic or question, and optionally specify a layout type. ## Authentication All requests require an API Key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Use with AI Agents Install the complete `felo-ai` package to let an Agent create mindmaps alongside every other available Felo Skill. The installer dynamically discovers every package directory containing `SKILL.md`, so it includes future additions. Install all discovered Skills in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, or Hermes Agent `~/.hermes/skills`. Follow the [manual AI Agent setup guide](/docs/felo-skills) for the safe setup procedure for each platform. ## Create Mindmap Create a mindmap based on a query (topic or question). ### Endpoint ``` POST https://openapi.felo.ai/v2/mindmap ``` ### Request Headers | Header | Required | Description | |--------|----------|-------------| | `Authorization` | Yes | Your API Key in the format `Bearer YOUR_API_KEY` | | `Content-Type` | Yes | Must be `application/json` | ### Request Body | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | Yes | The topic or question for mindmap generation. Max 2000 characters | | `layout` | string | No | Layout type. Default: `MIND_MAP` | | `livedoc_short_id` | string | No | LiveDoc ID. If not provided, a new LiveDoc will be created automatically | ### Layout Types | Layout | Description | |--------|-------------| | `MIND_MAP` | Classic mind map (default) | | `LOGICAL_STRUCTURE` | Logical structure diagram | | `ORGANIZATION_STRUCTURE` | Organization chart | | `CATALOG_ORGANIZATION` | Catalog organization chart | | `TIMELINE` | Timeline diagram | | `FISHBONE` | Fishbone diagram | ### Example: Create with Auto LiveDoc ```bash curl -X POST 'https://openapi.felo.ai/v2/mindmap' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "Artificial Intelligence trends in 2024" }' ``` ### Example: Create with Specific LiveDoc ```bash curl -X POST 'https://openapi.felo.ai/v2/mindmap' \ -H 'accept: application/json' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "query": "Project timeline overview", "layout": "TIMELINE", "livedoc_short_id": "abc123xyz" }' ``` ### Success Response (200) ```json { "status": "ok", "message": null, "data": { "resource_id": "550e8400-e29b-41d4-a716-446655440000", "status": "COMPLETED", "livedoc_short_id": "PvyKouzJirXjFdst4uKRK3", "mindmap_url": "https://felo.ai/mindmap/550e8400-e29b-41d4-a716-446655440000", "svg": "...", "message": "Mindmap created successfully" } } ``` ### Response Fields | Field | Type | Description | |-------|------|-------------| | `resource_id` | string | Resource ID of the created mindmap | | `status` | string | Status of the mindmap (e.g., `COMPLETED`) | | `livedoc_short_id` | string | LiveDoc short ID where the mindmap is stored | | `mindmap_url` | string | URL to view the mindmap (format: `{host}/mindmap/{resource_id}`) | | `svg` | string | SVG content of the mindmap | | `message` | string | Status message | ## Error Codes | Code | HTTP Status | Description | |------|-------------|-------------| | `INVALID_API_KEY` | 401 | API Key is invalid or revoked | | `MINDMAP_CREATE_FAILED` | 502 | Mindmap creation failed | | `LIVEDOC_CREATE_FAILED` | 502 | Failed to create LiveDoc | | `LIVEDOC_NOT_FOUND` | 404 | Specified LiveDoc not found | | `LLM_SERVICE_UNAVAILABLE` | 503 | LLM service is unavailable | | `LLM_REQUEST_TIMEOUT` | 504 | LLM request timed out |