apix — API Explorer for Agents
INLINECODE0 is a CLI tool for importing, browsing, searching, and calling API endpoint documents stored as local markdown vaults.
Prerequisites & Installation
Before using apix, verify if it is installed:
CODEBLOCK0
If it is not installed, install it using Homebrew (macOS/Linux):
CODEBLOCK1
Or via the curl installer:
CODEBLOCK2
Agent Workflow Guidelines
When an API task is requested, follow this general workflow:
- 1. Discover: Find the relevant endpoint route.
CODEBLOCK3
- 2. Inspect: Check the endpoint parameters and schema concisely to save your context window.
CODEBLOCK4
Note: Only use apix show <route> if you need the full, detailed documentation, as it can be long.
- 3. Execute: Make the HTTP call using the route you found.
CODEBLOCK5
Core Commands
Search & Discovery
- - Search across all indexed APIs: INLINECODE3
- List namespaces: INLINECODE4
- List endpoints in a namespace:
apix ls <namespace>/<version> (e.g., apix ls petstore/v1) - Full-text search within a namespace: INLINECODE7
Inspecting Endpoints
Routes follow the format: <namespace>/<version>/<path segments>/<METHOD> (e.g., petstore/v1/pets/GET).
- - Peek (Recommended for Agents):
apix peek <route> — Outputs the YAML frontmatter and condensed required input fields. - Show:
apix show <route> — Outputs the full markdown documentation for the route or type.
Executing HTTP Calls
INLINECODE12 automatically resolves the URL, method, and auth requirements from the route's markdown frontmatter.
- - Basic call with a literal path segment:
CODEBLOCK6
(apix automatically maps item_123 to the {id} parameter if the defined route is demo/v1/items/{id}/GET)
CODEBLOCK7
- -p <key>=<value>: Path parameter
- -q <key>=<value>: Query parameter
- -H "<Header>: <Value>": HTTP Header
- -d '<data>' or -d @file.json: Request body
Importing Custom Specs
If the required API is not in the public registry, you can import an OpenAPI 3.x spec locally:
CODEBLOCK8
Notes for Agents
- - When you execute
apix commands via the shell, it detects that stdout is piped and will automatically emit raw markdown, which is perfectly structured for you to read. - INLINECODE22 routes are standard strings. If a route matches multiple sources,
apix will throw an ambiguity error. In that case, prefix the route with the source (e.g., core/petstore/v1/pets/GET). - Prioritize
peek over show to avoid flooding your context window with redundant schemas.
apix — API 探索工具（面向智能体）
apix 是一个命令行工具，用于导入、浏览、搜索和调用以本地 Markdown 仓库形式存储的 API 端点文档。
前提条件与安装
使用 apix 之前，请确认是否已安装：
bash
apix --version
如果尚未安装，可通过 Homebrew（macOS/Linux）安装：
bash
brew tap apix-sh/tap
brew install apix
或通过 curl 安装脚本：
bash
curl -fsSL https://apix.sh/install | sh
智能体工作流程指南
当收到 API 任务请求时，请遵循以下通用工作流程：
- 1. 发现：找到相关的端点路由。
bash
apix search create pet
# 或列出可用 API：apix ls
- 2. 查看：简洁地检查端点参数和模式，以节省上下文窗口。
bash
apix peek petstore/v1/pets/{petId}/GET
注意：仅当你需要完整、详细的文档时才使用 apix show ，因为它可能内容较长。
- 3. 执行：使用找到的路由发起 HTTP 调用。
bash
apix call demo/v1/items/{id}/POST -p id=item_123 -d {name:item}
核心命令
搜索与发现
- - 在所有已索引的 API 中搜索：apix search
- 列出命名空间：apix ls
- 列出命名空间中的端点：apix ls /（例如 apix ls petstore/v1）
- 在命名空间内进行全文搜索：apix grep
检查端点
路由遵循以下格式：///（例如 petstore/v1/pets/GET）。
- - 快速查看（推荐智能体使用）：apix peek — 输出 YAML 前置元数据和精简的必填输入字段。
- 完整显示：apix show — 输出该路由或类型的完整 Markdown 文档。
执行 HTTP 调用
apix call 会自动从路由的 Markdown 前置元数据中解析 URL、方法和认证要求。
bash
apix call demo/v1/items/item_123/GET
（如果定义的路由是 demo/v1/items/{id}/GET，apix 会自动将 item123 映射到 {id} 参数）_
bash
apix call demo/v1/items/{id}/POST \
-p id=item_123 \
-q expand=full \
-H Authorization: Bearer \
-d {name:item}
- -p =：路径参数
- -q =：查询参数
- -H : ：HTTP 头部
- -d 或 -d @file.json：请求体
导入自定义规范
如果所需的 API 不在公共注册表中，你可以在本地导入 OpenAPI 3.x 规范：
bash
apix import /path/to/openapi.json --name myapi
智能体注意事项
- - 当你通过 shell 执行 apix 命令时，它会检测到标准输出被管道化，并自动输出原始 Markdown，这非常适合你阅读。
- apix 路由是标准字符串。如果某个路由匹配多个来源，apix 会抛出歧义错误。此时，请在路由前加上来源前缀（例如 core/petstore/v1/pets/GET）。
- 优先使用 peek 而非 show，以避免用冗余的模式信息淹没你的上下文窗口。
