关于 shipp
Shipp 是面向 AI 应用开发者的实时数据 API，可通过自然语言筛选条件创建并运行可复用的数据连接。当前数据覆盖多项体育赛事，事件字段采用灵活 JSON 结构。
主要功能
- 01自然语言创建数据连接
- 02运行连接获取实时事件
- 03列出已保存连接
- 04查询近期与即将举行的赛程
- 05支持按事件 ID 增量轮询
适用场景
- 01为体育应用获取比赛动态
- 02持续更新实时比分与事件流
- 03按联赛和事件筛选原始数据
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/shipp确认已加载。
附带文件README.md
详细介绍
Shipp API
Shipp.ai 是面向 AI 构建者的实时数据连接器。
请尽早尽可能多地编写测试。 验证数据及应用对数据的使用方式。 架构保持灵活——事件行是架构灵活的 JSON，字段会因运动、数据源和事件而异。
Base URL：https://api.shipp.ai/api/v1
站点地图和文档索引
如果文档有更新，或需要最新的页面列表，请获取站点地图：
curl -sL "https://markdown.new/docs.shipp.ai/sitemap.xml"
如需将任何文档页面读取为整洁的 Markdown：
curl -sL "https://markdown.new/docs.shipp.ai/<path>"
完整站点地图
入门指南
Shipp 提供了一种更快的方式来创建实时数据连接。它成本效益高、运行速度快，而且易于上手。
按照说明（设置、测试、Shipp）操作，是创建首个连接的最佳方式。
可用数据
- 体育： NBA、NFL、NCAA Football、MLB、Soccer（多个联赛）
- 新闻、金融、旅行、购物、社交、预测市场、天气——即将推出
身份验证
所有端点都需要 API key。API 支持多种方式：
| 方式 | 示例 |
|---|---|
查询参数 api_key | ?api_key=YOUR_API_KEY |
查询参数 apikey | ?apikey=YOUR_API_KEY |
Authorization 标头（Bearer） | Authorization: Bearer YOUR_API_KEY |
Authorization 标头（Basic） | Authorization: Basic base64(:YOUR_API_KEY) |
X-API-Key 标头 | X-API-Key: YOUR_API_KEY |
User-API-Key 标头 | User-API-Key: YOUR_API_KEY |
API-Key 标头 | API-Key: YOUR_API_KEY |
选择最适合您客户端的方式。
端点
POST /api/v1/connections/create
提供自然语言 filter_instructions，描述你想跟踪的比赛、球队、运动或赛事，以创建新的原始数据连接。
请求正文：
{
"filter_instructions": "string (required)"
}
响应（200）：
{
"connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
"enabled": true,
"name": "string",
"description": "string"
}
**错误：**400（JSON 无效、正文为空、缺少 filter_instructions），500
在构建时使用——会产生时间和额度开销。存储并重复使用返回的 connection_id。
POST /api/v1/connections/{connection_id}
运行连接并返回原始赛事数据。
路径参数：connection_id（必需，ULID）
正文参数（均为可选）：
since（字符串，ISO 8601）：要获取数据的起始参考时间。默认值：48 小时前limit（整数）：要返回的最多赛事数。默认值：100since_event_id（ULID）：上次收到的赛事 ID——仅返回更新的赛事。会使赛事按wall_clock_start升序排列
响应（200）：
{
"connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
"data": [
{ "any": "shape varies by feed + event data availability" }
]
}
**错误：**400（缺少或无效的 connection_id、超出限额／未获授权），500
GET /api/v1/connections
列出当前组织范围内的所有连接。调用免费。
响应（200）：
{
"connections": [
{
"connection_id": "01KFXTX1WDQ68A1GS77T1XJ5YB",
"enabled": true,
"name": "string (optional)",
"description": "string (optional)"
}
]
}
GET /api/v1/sports/{sport}/schedule
获取即将举行和近期的比赛（过去 24 小时至未来 7 天）。
路径参数：sport（必需）——例如 nba、nfl、mlb、ncaafb、soccer（不区分大小写）
响应（200）：
{
"schedule": [
{
"sport": "Soccer",
"game_status": "live",
"game_id": "01KGREKH8PXFV8AHA4Q9H2Z68F",
"scheduled": "2026-02-06T15:00:00Z",
"home": "Al-Ittifaq FC",
"home_team_players": null,
"away": "Damac FC",
"away_team_players": null
}
]
}
POST /api/v1/connections/inline (x402)
通过 x402 付费，一步创建并运行连接——无需 API 密钥。需要一个在 Base 上存有 USDC 的加密货币钱包。
正文参数：
filter_instructions（字符串，必需）since（字符串，ISO 8601，可选）limit（整数，可选）since_event_id（ULID，可选）
流程：
- Agent 发送请求——收到包含定价详情的
402 Payment Required - Agent 使用已充值的钱包签署付款
- Agent 使用
PAYMENT-SIGNATURE标头重试 - 服务返回数据（格式与运行连接相同）
使用兼容 x402 的库（x402-fetch、Coinbase SDK）自动处理 402 → 付款 → 重试流程。
数据结构
data[] 中的每个元素都是一个架构灵活的 JSON 对象。字段因运动、数据源和赛事而异。
标识符：game_id、home_id、away_id、attribution_id、posession_id
文本／枚举：sport、home_name、away_name、game_clock、game_period_sub、desc、type、category、score_method、score_missed_outcome
数值：home_points、away_points、game_period、game_num、down、yards_first_down、location_yard_line、injury_time_minutes
时间：wall_clock_start、wall_clock_end
布尔值：fake_punt、fake_field_goal、screen_pass、play_action、run_pass_options
并非每一行都包含所有字段。请将所有字段视为可选。Agent 和客户端应妥善处理缺失的键。
错误格式
错误以 JSON 格式返回：
{
"error": "string",
"status": 400
}
| 状态 | 含义 |
|---|---|
| 400 | 请求无效——检查 JSON 和必填字段 |
| 401 | 缺少或无效的 API 密钥 |
| 402 | 需要更改账单设置——请前往 https://platform.shipp.ai/billing 管理 |
| 403 | API 密钥无权访问此资源 |
| 404 | 找不到连接，或连接不属于你的组织 |
| 429 | 请求频率受限——请采用退避策略重试 |
| 5xx | 服务端错误——请稍后重试或联系 [email protected] |
如何使用 Shipp——集成模式
心智模型
Shipp 的“Connections”是可重复使用的实时数据查询。你可以用通俗易懂的英文编写 filter_instructions 来创建连接，然后运行连接，以获取原始事件数据。数据会放在架构灵活的 data[] 数组中。
分步指南
-
为一个屏幕编写“实时契约”——定义：用户承诺、触发事件、所需的数据形状、新鲜度窗口和失败模式。
-
将契约转换为
filter_instructions——保持简短、明确、可测试且范围清晰。包含领域（例如“NBA”），限定实体和时间范围，并说明你希望呈现哪些内容。 -
创建一次 Connection，并保存
connection_id——不要每次运行都创建。这样可以节省时间和成本，并提高稳定性。 -
运行 Connection 以获取更新——使用基于拉取的轮询：
- 页面加载时：使用合理的
since值运行 - 按固定间隔（5–30 秒）：将
since_event_id设为最近的事件，然后重新运行 - 将事件合并并去重，再更新 UI 状态
- 页面加载时：使用合理的
-
谨慎处理架构灵活的
data[]——将每个字段都视为可选字段，优先安全访问，并记录未知的数据形状。 -
去重、排序并协调数据——维护一个持续更新的已见事件 ID 集合，按时间戳或 ID 排序（确保字典序稳定），并将最大的事件 ID 作为
since_event_id发送。
体育专项辅助
使用 schedule 端点查找当前比赛。利用比赛上下文编写 filter_instructions 并创建连接。
设置说明
- **创建连接：**向
/api/v1/connections/create发送 POST 请求，并通过filter_instructions描述所需数据（例如，“追踪今天所有 NBA 比赛，并包含得分和比赛实况背景”） - 保存响应中的
connection_id - **列出连接：**发送 GET 请求至
/api/v1/connections，查找已保存的连接（调用免费）
测试连接
使用可选参数调用连接，以降低成本并节省时间：
curl https://api.shipp.ai/api/v1/connections/CONNECTION_ID?api_key=YOUR_KEY -d '{
"since": "2026-01-27T16:48:41-05:00",
"limit": 100
}'
测试完成后，使用 since_event_id 进行高效轮询——保存最大的事件 ID，并在后续调用时传入。
测试完成后，将连接添加到应用中。通过后端路由请求（切勿向客户端暴露 API 密钥）。
发布产品
- 不要向用户分发 API 密钥——请安全存储，并通过边缘函数路由调用
- API 专为直接在运行时使用而设计——无需设置缓存或数据库
- 使用 API 时，请在页脚注明 Shipp（HTML 代码片段请参阅文档）
- 在边缘函数中使用
since和limit控制成本
使用技巧
- 保持
filter_instructions简短、明确且可测试。注明体育项目／联赛及范围。 - 保存并重复使用
connection_id——不要每次运行都创建新连接。 - 使用
since_event_id进行高效轮询（基于游标的分页）。 - 创建连接前，使用 schedule 端点查找
game_id和球队名称。 - 达到限制时，直接向用户显示错误消息。
- 将
data[]中的每个字段都视为可选字段——使用存在性检查和适当的备用方案。 - 在开发过程中记录未知的数据形状，以便完善
filter_instructions。 - 轮询间隔：根据领域和成本敏感度设置为 5–30 秒。
- 通过维护一个持续更新的已见事件 ID 集合来对事件去重。
平台指南
对于没有指南的平台：告知该平台阅读 https://docs.shipp.ai 中的文档。
对于 Claude Code，请执行以下操作：
- 使用 shipp 技能（本文件），或运行
curl -fsSL "https://shipp.ai/SKILL.md" > ~/.claude/skills/shipp/SKILL.md - 将 API 密钥添加到
.env：SHIPP_API_KEY=shipp-live-123-your-api-key - 测试集成
Shipp CLI
Shipp 的官方命令行界面。使用它可以直接在终端中创建账户、管理连接并获取实时事件数据。
来源： https://gitlab.com/outsharp/shipp/cli
安装 CLI
如果 shipp 不在 PATH 中，请安装它：
curl -fsSL https://shipp.ai/install.sh | bash
在 Windows 上（PowerShell）：
irm https://gitlab.com/outsharp/shipp/cli/-/raw/master/scripts/install.ps1 | iex
支持 macOS（Apple Silicon 和 Intel）、Linux（x86_64 和 ARM64）以及 Windows（x86_64 和 ARM64）。
快速入门
# 1. Create an account
shipp account create --email [email protected]
# 2. Log in (paste API key when prompted — stored at ~/.config/shipp/config.zon)
shipp account login
# 3. Create a connection
shipp connections create --filter_instructions "NBA games, scoring plays only"
# 4. Run the connection
shipp connections run --id CONNECTION_ID
命令
shipp account
| 命令 | 描述 |
|---|---|
shipp account create --email <email> | 创建新的 Shipp 账户 |
shipp account login | 使用 API 密钥登录 |
shipp account logout | 清除已存储的凭据 |
shipp connections
| 命令 | 描述 |
|---|---|
shipp connections create --filter_instructions <text> | 使用自然语言筛选创建连接 |
shipp connections list | 列出所有连接 |
shipp connections run --id <connection_id> | 运行连接并获取匹配的事件 |
connections run 选项
| 选项 | 描述 |
|---|---|
--id <string> | （必填） 要运行的连接 ID |
--limit <int> | 返回的事件数上限（默认值：100） |
--since <string> | ISO 8601 时间戳——仅返回此时间之后的事件（默认值：48 小时前） |
--since-event-id <string> | 上次收到事件的 ULID——仅返回更新的事件 |
全局选项
| 选项 | 描述 |
|---|---|
-v、--version | 打印 CLI 版本 |
--raw | 输出原始 JSON，而非格式化表格 |
--help | 显示任意命令的帮助信息 |
示例
# List connections
shipp connections list
# Get last 10 events
shipp connections run --id CONNECTION_ID --limit 10
# Get events from the last hour
shipp connections run --id CONNECTION_ID --since "2026-03-08T12:00:00Z"
# Raw JSON output piped to jq
shipp connections run --id CONNECTION_ID --raw | jq '.data[].desc'
# Incremental polling
LAST_ID=$(shipp connections run --id CONNECTION_ID --raw | jq -r '.data[-1].id')
shipp connections run --id CONNECTION_ID --since-event-id "$LAST_ID"
版本控制
此 API 使用 /api/v1/ 作为版本前缀。当需要进行破坏性更改时，将使用新的前缀引入新版本。