{ "openapi": "3.1.0", "info": { "title": "AI123Box Public API", "version": "1.6.1", "summary": "Agent-friendly JSON API over the AI123Box AI tool directory, task-first use cases, daily AI updates, product submissions, and opt-in newsletter capture.", "description": "JSON API covering curated AI tools, task-first AI use cases, English-first best-tool rankings, a balanced daily AI radar, daily-curated AI news, X-sourced AI builder voices, the latest arXiv/HF papers, trending HuggingFace models, trending AI GitHub repositories, and an AI startup directory. `/api/manifest` is the agent discovery surface for entrypoints, scoring fields, pricing, submission policy, newsletter opt-in policy, and citation rules. The `/api/tools`, `/api/use-cases`, `/api/submit`, `/api/newsletter`, `/data/tools.json`, `/data/best-tools.json`, `/data/use-cases.json`, `/data/daily-radar.json`, `/data/news.json`, `/data/voices.json`, `/news.xml`, and `/ai-news-digest.txt` surfaces stay public for catalog, submission, newsletter, best-list, and news discovery; everything under `/api/feed` requires an API key (register at https://ai123box.com/docs, then pass `Authorization: Bearer sk-ai123box-…`). New keys are issued on the free tier (100 calls/day). Paid Stripe subscription tiers: Pro $19/month = 10000 calls/day, Business $99/month = 100000 calls/day.", "contact": { "name": "AI123Box", "url": "https://ai123box.com", "email": "support@ai123box.com" }, "license": { "name": "Attribution — link back to ai123box.com" } }, "servers": [ { "url": "https://ai123box.com", "description": "Production" } ], "security": [{ "ApiKeyBearer": [] }, {}], "paths": { "/api/manifest": { "get": { "summary": "Agent discovery manifest", "operationId": "getAgentManifest", "description": "Public machine-readable manifest for AI agents and developers. Includes API entrypoints, English response defaults, ranking and readiness fields, evidence policy, API pricing in USD, submission policy, rate-limit notes, and citation rules.", "security": [{}], "responses": { "200": { "description": "Agent manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentManifest" } } } } } } }, "/api/tools": { "get": { "summary": "Search or list AI tools", "operationId": "searchTools", "description": "Returns a paginated list of AI tools. Supports full-text search across name, description, category, and tags. Pass `useCase=` to rank tools for a task-first AI use case such as `invoice-pdf-to-excel` or `short-video-production`. When `id` is provided, returns a single tool object (not wrapped in `{tools, total}`). Public — no API key required. Agent-facing calls (`search`, `useCase`, or `format=agent`) default to English when `lang` is omitted, while the compatibility catalog call `/api/tools` without those parameters keeps the raw catalog shape for the website.", "security": [{}], "parameters": [ { "name": "search", "in": "query", "description": "Free-text query matched against name, description, category and tags.", "schema": { "type": "string" } }, { "name": "useCase", "in": "query", "description": "Optional use-case slug. When provided, tools are ranked using the use-case search query and related category boosts. Example: `invoice-pdf-to-excel`, `short-video-production`, `ai-coding-feature`, `rag-knowledge-base`, `presentation-deck`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Optional response locale for `name`, `desc`, `categoryLabel`, `localizedTags`, and page URLs. Defaults to `en` for `search`, `useCase`, and `format=agent` calls.", "schema": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"] } }, { "name": "format", "in": "query", "description": "Pass `agent` to receive the localized agent-friendly shape even when no search query is provided.", "schema": { "type": "string", "enum": ["agent"] } }, { "name": "category", "in": "query", "description": "Category slug or legacy internal value. Prefer English slugs; omit or pass `all` for all categories.", "schema": { "type": "string", "enum": [ "all", "chatbots", "image-generation", "video-generation", "audio-music", "coding", "writing-content", "design-tools", "productivity", "model-platforms", "ai-agents", "ai-search", "ai-research", "marketing-sales", "ai-infrastructure", "prompt-engineering", "data-tools", "content-detection", "jobs-learning", "community", "industry-reports", "model-evaluation", "open-source", "other-tools" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["hot", "rating", "newest", "name"], "default": "hot" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 200, "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "id", "in": "query", "description": "If provided, returns a single tool by stable id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ToolList" }, { "$ref": "#/components/schemas/Tool" } ] } } } }, "404": { "description": "Tool id not found, or use-case slug not found." } } } }, "/api/search": { "post": { "summary": "AI-assisted tool search for agents", "operationId": "aiSearch", "description": "AI-assisted semantic search and reranking over the AI123Box catalog. Defaults to English response content for agent callers even when the query is Chinese; pass `locale=zh-CN` only for a Chinese UI. The endpoint never invents tools: the LLM can only rerank candidates recalled from the catalog, with deterministic fallback when no model key is configured.", "security": [{}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["query"], "properties": { "query": { "type": "string", "description": "Task or search intent, any language." }, "category": { "type": "string", "description": "Optional category slug or legacy internal category value." }, "locale": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"], "default": "en", "description": "Response language. Defaults to English for agents." } } } } } }, "responses": { "200": { "description": "AI-reranked or deterministic fallback results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AISearchResponse" } } } }, "400": { "description": "Query is missing or too short." }, "429": { "description": "Too many search requests." } } } }, "/api/alternatives": { "get": { "summary": "Find nearby alternatives for one AI tool", "operationId": "getAlternatives", "description": "Public JSON endpoint for peer/competitor discovery. Returns the target tool plus nearby alternatives ranked by same category, shared tags, rating, hot/new signals, and match reasons. Defaults to English response content for agents.", "security": [{}], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Stable tool id, e.g. `chatgpt`, `claude`, `cursor`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Response locale.", "schema": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"], "default": "en" } }, { "name": "limit", "in": "query", "description": "Maximum alternatives.", "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Target tool and ranked alternatives.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlternativesResponse" } } } }, "400": { "description": "Missing id." }, "404": { "description": "Tool id not found." } } } }, "/api/best-tools": { "get": { "summary": "Best AI tools by topic", "operationId": "getBestTools", "description": "Public English-first ranking API for high-intent best-tool queries. Returns all best-tool topics or one topic when `topic` is provided. Ranking uses AI123Box category fit, topic keyword fit, rating, hot/new signals, recency, and official URL availability.", "security": [{}], "parameters": [ { "name": "topic", "in": "query", "description": "Optional topic slug.", "schema": { "type": "string", "enum": ["ai-agents", "ai-coding-tools", "ai-video-generators", "ai-image-generators", "ai-search-engines", "ai-productivity-tools", "ai-model-platforms", "open-source-ai-tools", "ai-writing-tools", "ai-marketing-tools"] } }, { "name": "limit", "in": "query", "description": "Maximum tools per topic.", "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Best-tool topics or one topic.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Topic slug not found." } } } }, "/api/use-cases": { "get": { "summary": "List AI use cases or fetch one use-case playbook", "operationId": "getUseCases", "description": "Public task-first API for real AI workflows. Defaults to English for agent consumption. Without `slug`, returns all use cases. With `slug`, returns one use-case playbook including outcome, workflow steps, tool stack, checklist, mistakes, search query, category routing, and localized page URLs. Add `includeTools=true` to attach ranked candidate tools with official URLs, AI123Box pages, match scores, and match reasons.", "security": [{}], "parameters": [ { "name": "slug", "in": "query", "description": "Use-case slug, e.g. `invoice-pdf-to-excel`, `short-video-production`, `ai-coding-feature`, `rag-knowledge-base`, `meeting-notes-action-items`, or `presentation-deck`.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "Response locale.", "schema": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"], "default": "en" } }, { "name": "includeTools", "in": "query", "description": "When true and `slug` is provided, include ranked candidate tools for this use case.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "description": "Maximum related tools when `includeTools=true`.", "schema": { "type": "integer", "default": 12, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Use-case list or detail", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UseCaseList" }, { "$ref": "#/components/schemas/UseCaseResponse" } ] } } } }, "404": { "description": "Use-case slug not found." } } } }, "/api/compare": { "get": { "summary": "Side-by-side comparison of 2-4 AI tools", "operationId": "compareTools", "description": "Aligned JSON shape for 2-4 AI tools (name, description, category, rating, tags, pricing heuristic, official URL, AI123Box page URL). Pass `mode=diff` to additionally receive an LLM-generated comparison summary, key differences, and a use-case-aware recommendation. The `mode=diff` branch calls the configured server-side LLM with prompt-injection guards on user-supplied tool fields. Public — no API key required.", "security": [{}], "parameters": [ { "name": "ids", "in": "query", "required": true, "description": "Comma-separated tool ids, 1-4 items. Example: `chatgpt,claude,gemini` or `midjourney,stable-diffusion,flux`.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "description": "Optional. Pass `diff` to attach an LLM-generated comparison summary, differences array, and recommendation. Without it, only the aligned per-tool JSON is returned (cheaper, cacheable).", "schema": { "type": "string", "enum": ["diff"] } }, { "name": "lang", "in": "query", "description": "Response locale for `name`, `description`, `category`, localized tags, and the diff summary.", "schema": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"], "default": "en" } } ], "responses": { "200": { "description": "Aligned per-tool JSON, optionally with diff summary.", "content": { "application/json": { "examples": { "table-only": { "summary": "GET /api/compare?ids=chatgpt,claude", "value": { "tools": [ { "id": "chatgpt", "name": "ChatGPT", "category": "Chatbots", "rating": 4.8, "tags": ["chat", "reasoning"], "pricing": ["paid", "api"], "url": "https://chat.openai.com", "page": "https://ai123box.com/tool/chatgpt" }, { "id": "claude", "name": "Claude", "category": "Chatbots", "rating": 4.8, "tags": ["chat", "reasoning", "coding"], "pricing": ["paid", "api"], "url": "https://claude.ai", "page": "https://ai123box.com/tool/claude" } ] } }, "diff-mode": { "summary": "GET /api/compare?ids=chatgpt,claude&mode=diff", "value": { "tools": [ { "id": "chatgpt" }, { "id": "claude" } ], "summary": "Both are general-purpose chatbots with strong reasoning. ChatGPT ships faster product surface area; Claude leans into long-context coding and writing.", "differences": [ { "axis": "context window", "chatgpt": "shorter default", "claude": "1M token tier" }, { "axis": "coding", "chatgpt": "code interpreter", "claude": "Claude Code agent + 1M context" } ], "recommendation": "Long-context coding or doc-heavy reasoning → Claude. Product features and a broader plugin/agent surface → ChatGPT." } } } } } }, "400": { "description": "Missing or malformed `ids` (need 1-4 valid tool ids)." }, "404": { "description": "None of the requested ids matched a tool." } } } }, "/api/feed": { "get": { "summary": "Daily AI updates (daily-radar / news / voices / papers / models / github / startups / daily-tools)", "operationId": "getFeed", "description": "Gated endpoint that returns the daily curated AI update feed of the chosen type. Requires `Authorization: Bearer sk-ai123box-…`. Free keys get 100 calls/day. Paid subscriptions are upgraded by Stripe webhook: Pro $19/month = 10000 calls/day, Business $99/month = 100000 calls/day.", "security": [{ "ApiKeyBearer": [] }], "parameters": [ { "name": "type", "in": "query", "required": true, "description": "Which feed to read.", "schema": { "type": "string", "enum": ["daily-radar", "news", "voices", "papers", "models", "github", "startups", "daily-tools"] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "q", "in": "query", "description": "Optional free-text filter (matches title / summary / authors / keywords depending on type).", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "description": "For type=news: filter by source language.", "schema": { "type": "string", "enum": ["zh", "en"] } }, { "name": "locale", "in": "query", "description": "For type=daily-tools: optional response locale for descriptions, category labels, localized tags, and page URLs.", "schema": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"] } }, { "name": "pipeline", "in": "query", "description": "For type=models: HuggingFace pipeline tag.", "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "For type=github: programming language.", "schema": { "type": "string" } }, { "name": "track", "in": "query", "description": "For type=startups: track (app, agent, infra, …).", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "description": "For type=startups: funding stage.", "schema": { "type": "string" } }, { "name": "section", "in": "query", "description": "For type=daily-radar: vertical filter such as news, papers, models, github, tools, voices, or startups.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "For type=daily-tools: category slug such as chatbots, coding, ai-search, or prompt-engineering. Legacy internal values are still accepted.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedResponse" } } } }, "401": { "description": "Missing / malformed / revoked API key." }, "429": { "description": "Daily quota exhausted or IP rate-limited." } } } }, "/api/submit": { "post": { "summary": "Submit an AI product for review", "operationId": "submitAiProduct", "description": "Public rate-limited intake endpoint for AI products. Free submissions enter manual review; featured submissions indicate commercial intent but do not bypass quality or safety review. IP rate-limited at 5 requests per minute.", "security": [{}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "url"], "properties": { "name": { "type": "string", "description": "Product name." }, "url": { "type": "string", "description": "Product homepage. `https://` is added server-side when omitted." }, "desc": { "type": "string", "description": "Short product description." }, "category": { "type": "string", "description": "Preferred AI123Box category." }, "submissionPlan": { "type": "string", "enum": ["free", "featured"], "default": "free" }, "contactEmail": { "type": "string", "format": "email" }, "budget": { "type": "string", "description": "Optional commercial placement budget note." }, "goals": { "type": "string", "description": "Optional placement or launch goal." }, "locale": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"], "default": "en" } } } } } }, "responses": { "200": { "description": "Submission stored for review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionResponse" } } } }, "400": { "description": "Missing name or url." }, "429": { "description": "Too many submissions from this IP." } } } }, "/api/newsletter": { "post": { "summary": "Subscribe to AI123Box daily AI radar updates", "operationId": "subscribeNewsletter", "description": "Public rate-limited opt-in endpoint for the daily AI radar and AI123Box launch updates. The endpoint stores subscriber intent only; it does not send email or trigger outreach automatically. IP rate-limited at 8 requests per 10 minutes.", "security": [{}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" }, "locale": { "type": "string", "enum": ["en", "zh-CN", "ja", "ko", "es", "de"], "default": "en" }, "source": { "type": "string", "description": "Signup surface, such as daily-radar, agent-api, commercial, or site-footer." }, "interests": { "type": "array", "items": { "type": "string", "enum": ["daily-radar", "ai-tools", "agent-api", "commercial"] }, "default": ["daily-radar"] }, "referrer": { "type": "string", "description": "Optional local path or campaign path that led to the signup." } } } } } }, "responses": { "201": { "description": "New subscriber stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscriptionResponse" } } } }, "200": { "description": "Email already existed and was reactivated or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterSubscriptionResponse" } } } }, "400": { "description": "Invalid email." }, "429": { "description": "Too many signup requests from this IP." }, "503": { "description": "Newsletter database is not configured." } } } }, "/api/keys": { "post": { "summary": "Register a free API key for an email", "operationId": "registerApiKey", "description": "Idempotent: if the email already has an active key, the same key is returned (`reused: true`). Returns a fresh `sk-ai123box-…` token otherwise. IP rate-limited at 5 / 10 min.", "security": [{}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" }, "note": { "type": "string", "description": "Optional free-form note (≤200 chars)." } } } } } }, "responses": { "201": { "description": "New key created." }, "200": { "description": "Existing active key returned (reused)." }, "400": { "description": "Invalid email." }, "429": { "description": "Too many registrations from this IP." } } }, "get": { "summary": "Inspect the API key bound to the bearer token", "operationId": "getApiKeyInfo", "security": [{ "ApiKeyBearer": [] }], "responses": { "200": { "description": "Key info: tier, plan, quotaDaily, usedToday, remaining, totalCalls, billingStatus, resetAt, and public plan metadata." }, "401": { "description": "Missing bearer token." }, "404": { "description": "Key not found or revoked." } } } }, "/api/billing/checkout": { "post": { "summary": "Create a Stripe Checkout subscription session", "operationId": "createBillingCheckout", "description": "Creates a Stripe Checkout session for the Pro or Business API tier. Requires an existing API key in the Authorization bearer header. On successful payment, Stripe calls `/api/billing/webhook` and the API key is upgraded automatically.", "security": [{ "ApiKeyBearer": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["plan"], "properties": { "plan": { "type": "string", "enum": ["pro", "business"], "description": "Paid plan to subscribe to. Pro = $19/month / 10000 calls/day. Business = $99/month / 100000 calls/day." } } } } } }, "responses": { "201": { "description": "Stripe Checkout session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutResponse" } } } }, "400": { "description": "Invalid plan." }, "401": { "description": "Missing or invalid API key." }, "429": { "description": "Too many checkout attempts." }, "503": { "description": "Stripe secret or price id not configured." } } } }, "/data/tools.json": { "get": { "summary": "Full tool snapshot", "operationId": "fullSnapshot", "description": "Static JSON of every tool in the directory. Public.", "security": [{}], "responses": { "200": { "description": "Array of Tool", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } } } } } }, "/data/i18n/tools.en.json": { "get": { "summary": "English tool translation bundle", "operationId": "englishToolTranslations", "description": "Static public JSON containing the currently completed English tool description translations. Batch files remain available for editorial workflow; this bundle is optimized for runtime and agent consumption.", "security": [{}], "responses": { "200": { "description": "English translation bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolTranslationBundle" } } } } } } }, "/data/news.json": { "get": { "summary": "Daily AI news snapshot", "operationId": "dailyAiNewsSnapshot", "description": "Static public JSON for the latest AI news briefing. Includes topic labels, importance scores, language, source, host, image, summary, and source URL for each story.", "security": [{}], "responses": { "200": { "description": "Daily AI news snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsSnapshot" } } } } } } }, "/data/daily-radar.json": { "get": { "summary": "Balanced daily AI radar snapshot", "operationId": "dailyAiRadarSnapshot", "description": "Static public JSON for cross-domain daily AI rankings. Includes a balanced top list and per-section rankings for news, papers, models, GitHub repositories, tools, voices, and startups.", "security": [{}], "responses": { "200": { "description": "Daily AI radar snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/data/best-tools.json": { "get": { "summary": "Best AI tools ranked lists", "operationId": "bestAiToolsSnapshot", "description": "Static public English-first JSON for Top/Rising-style best-tool lists. Includes topic metadata, ranking criteria, rankingSignals, reviewPolicy, tool scores, reasons, official URLs, and AI123Box tool pages. Prefer this endpoint when an agent needs best AI tools by category or task.", "security": [{}], "responses": { "200": { "description": "Best AI tools snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BestToolsSnapshot" } } } } } } }, "/data/voices.json": { "get": { "summary": "Daily AI voices snapshot", "operationId": "dailyAiVoicesSnapshot", "description": "Static public JSON for X-sourced AI builder and KOL viewpoints when the X API token is configured. Includes summaries, source links, author metadata, topics, and metrics.", "security": [{}], "responses": { "200": { "description": "Daily AI voices snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/data/papers.json": { "get": { "summary": "Daily AI papers snapshot", "operationId": "dailyAiPapersSnapshot", "description": "Static public JSON for the latest AI paper picks. Includes titles, summaries, arXiv IDs, PDF links, Hugging Face Daily Papers links, authors, keywords, and community signals.", "security": [{}], "responses": { "200": { "description": "Daily AI papers snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/data/models.json": { "get": { "summary": "Daily Hugging Face models snapshot", "operationId": "dailyAiModelsSnapshot", "description": "Static public JSON for trending open models. Includes model IDs, authors, task tags, likes, downloads, summaries, and Hugging Face URLs.", "security": [{}], "responses": { "200": { "description": "Daily Hugging Face models snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/data/github.json": { "get": { "summary": "Daily AI GitHub projects snapshot", "operationId": "dailyAiGithubSnapshot", "description": "Static public JSON for rising and interesting AI/open-source repositories. Includes full repo names, descriptions, languages, topics, stars, badges, and GitHub URLs.", "security": [{}], "responses": { "200": { "description": "Daily AI GitHub projects snapshot", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/data/startups.json": { "get": { "summary": "AI startups directory snapshot", "operationId": "aiStartupsSnapshot", "description": "Static public JSON for the AI startup directory. Includes names, tracks, stages, years, headquarters, descriptions, official URLs, and source batches.", "security": [{}], "responses": { "200": { "description": "AI startups directory snapshot", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } } } }, "/data/use-cases.json": { "get": { "summary": "AI use-case library snapshot", "operationId": "aiUseCasesSnapshot", "description": "Static public JSON for task-first AI use cases. Includes localized copy, search queries, category routing, and canonical use-case page URLs.", "security": [{}], "responses": { "200": { "description": "AI use-case library snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UseCaseStaticSnapshot" } } } } } } }, "/llms.json": { "get": { "summary": "Structured LLM context pack", "operationId": "llmsJsonContext", "description": "Public JSON context pack for generative engines. Includes AI123Box purpose, citation policy, entrypoints, dataset URLs, category counts, top tools, and daily AI updates.", "security": [{}], "responses": { "200": { "description": "Structured AI123Box context for LLMs and answer engines", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/news.xml": { "get": { "summary": "Daily AI news RSS feed", "operationId": "dailyAiNewsRss", "description": "RSS 2.0 feed for the daily AI news briefing. Public.", "security": [{}], "responses": { "200": { "description": "RSS 2.0 XML", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } }, "/news.zh-CN.xml": { "get": { "summary": "Chinese daily AI news RSS feed", "operationId": "dailyAiNewsChineseRss", "description": "Chinese RSS 2.0 feed for the daily AI news briefing. Public.", "security": [{}], "responses": { "200": { "description": "RSS 2.0 XML", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } }, "/ai-news-digest.txt": { "get": { "summary": "LLM-friendly daily AI news digest", "operationId": "dailyAiNewsTextDigest", "description": "Plain-text digest of top AI stories, topic counts, source counts, and canonical links. Public.", "security": [{}], "responses": { "200": { "description": "Plain text digest", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/ai-news-digest.zh-CN.txt": { "get": { "summary": "Chinese LLM-friendly daily AI news digest", "operationId": "dailyAiNewsChineseTextDigest", "description": "Chinese plain-text digest of top AI stories, topic counts, source counts, and canonical links. Public.", "security": [{}], "responses": { "200": { "description": "Plain text digest", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "sk-ai123box-…", "description": "Get a free key at https://ai123box.com/docs. Pass as `Authorization: Bearer sk-ai123box-`." } }, "schemas": { "Tool": { "type": "object", "required": ["id", "name", "url", "category"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "desc": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Official tool homepage. `officialUrl` is also returned in localized agent-facing responses." }, "officialUrl": { "type": "string", "format": "uri", "description": "Official tool homepage for agents." }, "category": { "type": "string" }, "categorySlug": { "type": "string", "description": "Stable English category slug for routing and filtering." }, "localizedName": { "type": "string", "description": "Localized display name when `lang` or agent mode is used." }, "originalName": { "type": "string", "description": "Original catalog name when it differs from the localized display name." }, "categoryLabel": { "type": "string", "description": "Localized display label when `lang` is provided." }, "tags": { "type": "array", "items": { "type": "string" } }, "originalTags": { "type": "array", "items": { "type": "string" }, "description": "Original catalog tags when localized tags differ." }, "localizedTags": { "type": "array", "items": { "type": "string" }, "description": "Localized / filtered tag labels when `lang` is provided." }, "page": { "type": "string", "format": "uri", "description": "Canonical AI123Box tool page when `lang` is provided." }, "ai123boxPage": { "type": "string", "format": "uri", "description": "Canonical AI123Box tool page for agents." }, "interfaceTypes": { "type": "array", "items": { "type": "string", "enum": ["web", "api", "cli", "open_source", "agent"] }, "description": "Inferred product surfaces useful for agents and developers." }, "installCommand": { "type": "string", "description": "CLI/package install command when known." }, "repositoryUrl": { "type": "string", "format": "uri", "description": "Repository URL when known." }, "packageUrl": { "type": "string", "format": "uri", "description": "Package registry URL when known." }, "docsUrl": { "type": "string", "format": "uri", "description": "Documentation URL when known." }, "agentReadiness": { "$ref": "#/components/schemas/AgentReadiness" }, "scoreBreakdown": { "$ref": "#/components/schemas/ScoreBreakdown" }, "evidence": { "$ref": "#/components/schemas/ToolEvidence" }, "matchScore": { "type": "integer", "description": "Semantic ranking score when returned from `search`, `useCase`, or related use-case tools." }, "matchReasons": { "type": "array", "items": { "type": "string" }, "description": "Short reasons explaining why the tool matched the query or use case." }, "hot": { "type": "boolean" }, "isNew": { "type": "boolean" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "users": { "type": "string" }, "updated": { "type": "string", "format": "date" }, "source": { "type": "string" }, "addedAt": { "type": "string", "format": "date" } } }, "AgentReadiness": { "type": "object", "required": ["schemaVersion", "score", "level", "checks", "summary"], "properties": { "schemaVersion": { "type": "string", "example": "ai123box.agent-readiness.v1" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "level": { "type": "string", "enum": ["high", "medium", "low"] }, "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "object", "required": ["id", "label", "ok", "weight"], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "ok": { "type": "boolean" }, "weight": { "type": "integer" } } } } } }, "ScoreBreakdown": { "type": "object", "required": ["total", "catalogQuality", "agentUtility", "freshness", "trustEvidence"], "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 100 }, "catalogQuality": { "type": "integer", "minimum": 0, "maximum": 35 }, "agentUtility": { "type": "integer", "minimum": 0, "maximum": 30 }, "freshness": { "type": "integer", "minimum": 0, "maximum": 20 }, "trustEvidence": { "type": "integer", "minimum": 0, "maximum": 15 } } }, "ToolEvidence": { "type": "object", "properties": { "source": { "type": "string" }, "policy": { "type": "string" }, "officialUrl": { "type": ["string", "null"], "format": "uri" }, "ai123boxPage": { "type": ["string", "null"], "format": "uri" }, "repositoryUrl": { "type": ["string", "null"], "format": "uri" }, "packageUrl": { "type": ["string", "null"], "format": "uri" }, "docsUrl": { "type": ["string", "null"], "format": "uri" } } }, "AgentManifest": { "type": "object", "required": ["schemaVersion", "name", "canonicalUrl", "defaultLanguage", "agentEntrypoints", "rankingFields", "pricing", "submissionPolicy", "citationPolicy"], "properties": { "schemaVersion": { "type": "string", "example": "ai123box.agent-manifest.v1" }, "name": { "type": "string", "example": "AI123Box" }, "canonicalUrl": { "type": "string", "format": "uri" }, "updatedAt": { "type": "string", "format": "date-time" }, "defaultLanguage": { "type": "string", "example": "en" }, "discovery": { "type": "object", "additionalProperties": { "type": "string" } }, "agentEntrypoints": { "type": "array", "items": { "type": "object", "required": ["intent", "method", "path", "auth", "responseLanguage", "returns"], "properties": { "intent": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "auth": { "type": "string" }, "responseLanguage": { "type": "string" }, "returns": { "type": "string" } } } }, "rankingFields": { "type": "object", "additionalProperties": { "type": "string" } }, "pricing": { "type": "object" }, "submissionPolicy": { "type": "object" }, "newsletterPolicy": { "type": "object" }, "citationPolicy": { "type": "object" }, "rateLimits": { "type": "object" } } }, "SubmissionResponse": { "type": "object", "required": ["success", "submissionPlan"], "properties": { "success": { "type": "boolean" }, "submissionPlan": { "type": "string", "enum": ["free", "featured"] } } }, "NewsletterSubscriptionResponse": { "type": "object", "required": ["success", "email", "interests", "reused", "message"], "properties": { "success": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "interests": { "type": "array", "items": { "type": "string", "enum": ["daily-radar", "ai-tools", "agent-api", "commercial"] } }, "reused": { "type": "boolean", "description": "True when the email already existed and was updated/reactivated." }, "message": { "type": "string", "example": "Subscribed to AI123Box updates." } } }, "ToolList": { "type": "object", "required": ["tools", "total"], "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "total": { "type": "integer" }, "query": { "type": "string", "description": "Effective search query used for ranking, including expanded use-case queries." }, "responseLanguage": { "type": "string", "description": "Language used for agent-facing response text." }, "useCase": { "$ref": "#/components/schemas/UseCase", "description": "Present when `useCase` query is used." } } }, "AISearchResponse": { "type": "object", "required": ["query", "mode", "tools", "totalTools", "candidateCount"], "properties": { "schemaVersion": { "type": "string", "example": "ai123box.ai-search.v1" }, "query": { "type": "string" }, "mode": { "type": "string", "enum": ["ai", "empty", "semantic-fallback", "semantic-fallback-nokey"] }, "responseLanguage": { "type": "string", "example": "en" }, "scoringLanguage": { "type": "string", "example": "zh-CN" }, "totalTools": { "type": "integer" }, "candidateCount": { "type": "integer" }, "analysis": { "type": "object", "properties": { "intent": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } }, "AlternativesResponse": { "type": "object", "required": ["schemaVersion", "locale", "id", "target", "alternatives", "count"], "properties": { "schemaVersion": { "type": "string", "example": "ai123box.alternatives.v1" }, "locale": { "type": "string", "example": "en" }, "id": { "type": "string" }, "target": { "$ref": "#/components/schemas/Tool" }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "count": { "type": "integer" } } }, "BillingCheckoutResponse": { "type": "object", "required": ["id", "url", "plan", "quotaDaily"], "properties": { "id": { "type": "string", "description": "Stripe Checkout Session id." }, "url": { "type": "string", "format": "uri", "description": "Redirect the user to this Stripe Checkout URL." }, "plan": { "type": "string", "enum": ["pro", "business"] }, "quotaDaily": { "type": "integer" } } }, "ToolTranslationBundle": { "type": "object", "required": ["locale", "count", "items"], "properties": { "locale": { "type": "string", "example": "en" }, "files": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "items": { "type": "object", "additionalProperties": { "type": "object", "required": ["desc"], "properties": { "desc": { "type": "string" } } } } } }, "UseCase": { "type": "object", "required": ["slug", "title", "summary", "outcome", "steps", "checklist", "page"], "properties": { "slug": { "type": "string" }, "group": { "type": "string" }, "title": { "type": "string" }, "shortTitle": { "type": "string" }, "audience": { "type": "string" }, "summary": { "type": "string" }, "outcome": { "type": "string" }, "time": { "type": "string" }, "stack": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ] } }, "steps": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "string" } }, "mistakes": { "type": "array", "items": { "type": "string" } }, "search": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" } } } }, "page": { "type": "string", "format": "uri" }, "localizedPages": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "UseCaseList": { "type": "object", "required": ["useCases", "total"], "properties": { "schemaVersion": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "locale": { "type": "string" }, "total": { "type": "integer" }, "useCases": { "type": "array", "items": { "$ref": "#/components/schemas/UseCase" } } } }, "UseCaseResponse": { "type": "object", "required": ["useCase"], "properties": { "schemaVersion": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "locale": { "type": "string" }, "useCase": { "$ref": "#/components/schemas/UseCase" }, "relatedTools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } } }, "UseCaseStaticSnapshot": { "type": "object", "required": ["schemaVersion", "count", "items"], "properties": { "schemaVersion": { "type": "string" }, "updatedAt": { "type": "string", "format": "date" }, "api": { "type": "string", "format": "uri" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object" } } } }, "BestToolListItem": { "type": "object", "required": ["id", "name", "desc", "url", "category", "score", "reasons", "page"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "desc": { "type": "string", "description": "English description for agent use." }, "url": { "type": "string", "format": "uri" }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "categoryLabel": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "rating": { "type": ["number", "null"] }, "hot": { "type": "boolean" }, "isNew": { "type": "boolean" }, "updated": { "type": ["string", "null"] }, "score": { "type": "integer" }, "reasons": { "type": "array", "items": { "type": "string" } }, "page": { "type": "string", "format": "uri" } } }, "BestToolsSnapshot": { "type": "object", "required": ["schemaVersion", "locale", "updatedAt", "rankingSignals", "reviewPolicy", "topics"], "properties": { "schemaVersion": { "type": "string", "example": "ai123box.best-tools.v1" }, "locale": { "type": "string", "example": "en" }, "updatedAt": { "type": "string", "format": "date-time" }, "sourceCatalog": { "type": "string", "format": "uri" }, "objective": { "type": "string" }, "referencePatterns": { "type": "array", "items": { "type": "string" } }, "rankingSignals": { "type": "array", "items": { "type": "string" } }, "reviewPolicy": { "type": "string" }, "agentUsage": { "type": "object" }, "indexUrl": { "type": "string", "format": "uri" }, "topics": { "type": "array", "items": { "type": "object", "required": ["slug", "title", "summary", "criteria", "tools"], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "audience": { "type": "string" }, "category": { "type": "string" }, "categorySlug": { "type": "string" }, "categoryLabel": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "criteria": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" }, "dataUrl": { "type": "string", "format": "uri" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/BestToolListItem" } } } } } } }, "NewsItem": { "type": "object", "required": ["title", "link"], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "origSummary": { "type": "string" }, "link": { "type": "string", "format": "uri" }, "image": { "type": "string", "format": "uri" }, "source": { "type": "string" }, "host": { "type": "string" }, "lang": { "type": "string", "enum": ["zh", "en"] }, "topics": { "type": "array", "items": { "type": "string" } }, "importance": { "type": "integer", "minimum": 1, "maximum": 10 }, "publishedAt": { "type": "string", "format": "date-time" }, "collectedAt": { "type": "string", "format": "date-time" } } }, "NewsSnapshot": { "type": "object", "required": ["items"], "properties": { "updatedAt": { "type": "string", "format": "date-time" }, "date": { "type": "string", "format": "date" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NewsItem" } } } }, "FeedResponse": { "type": "object", "required": ["type", "items"], "properties": { "type": { "type": "string", "enum": ["daily-radar", "news", "voices", "papers", "models", "github", "startups", "daily-tools"] }, "items": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object", "properties": { "updatedAt": { "type": "string", "format": "date-time" }, "date": { "type": "string", "format": "date" }, "count": { "type": "integer" } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }