shipp

Shipp API

Shipp.ai は、AI 開発者向けのリアルタイムデータコネクターです。

API キーを作成

できるだけ早く、できるだけ多くのテストを実装してください。 データと、アプリがデータをどのように使用するかを確認してください。 スキーマには柔軟性を持たせてください。イベントの行はスキーマに柔軟な JSON であり、フィールドはスポーツ、フィード、イベントによって異なります。

ベース 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>"

サイトマップ全体

ページ	markdown.new URL
はじめに	https://markdown.new/docs.shipp.ai/
セットアップ手順	https://markdown.new/docs.shipp.ai/instructions/setup/
接続をテストする	https://markdown.new/docs.shipp.ai/instructions/test/
製品を Shipp する	https://markdown.new/docs.shipp.ai/instructions/shipp/
Shipp の使い方	https://markdown.new/docs.shipp.ai/how-to/
API リファレンス	https://markdown.new/docs.shipp.ai/api-reference/
接続を作成	https://markdown.new/docs.shipp.ai/api-reference/connections-create/
接続の一覧を取得	https://markdown.new/docs.shipp.ai/api-reference/connections-list/
接続を実行	https://markdown.new/docs.shipp.ai/api-reference/connections-run/
スポーツのスケジュール	https://markdown.new/docs.shipp.ai/api-reference/sport-schedule/
データ構造	https://markdown.new/docs.shipp.ai/api-reference/connections-run-data-shape/
エラー形式	https://markdown.new/docs.shipp.ai/api-reference/error-format/
使用上のヒント	https://markdown.new/docs.shipp.ai/api-reference/usage-tips/
バージョン管理	https://markdown.new/docs.shipp.ai/api-reference/versioning/
x402 決済	https://markdown.new/docs.shipp.ai/api-reference/x402/
プラットフォームガイド	https://markdown.new/docs.shipp.ai/platform-guides/
Lovable ガイド	https://markdown.new/docs.shipp.ai/platform-guides/lovable/
Base44 ガイド	https://markdown.new/docs.shipp.ai/platform-guides/base44/
Claude Code ガイド	https://markdown.new/docs.shipp.ai/platform-guides/claude-code/
Blink ガイド	https://markdown.new/docs.shipp.ai/platform-guides/blink/
Replit ガイド	https://markdown.new/docs.shipp.ai/platform-guides/replit/

---

はじめに

Shipp を使うと、リアルタイムデータへの接続をより速く作成できます。コスト効率が高く、実行も速く、簡単に始められます。

1. Shipp に登録します
2. お好みの AI ビルダーに API キーを貼り付けます。プラットフォームガイドを参照してください
3. Shipp は AI ビルダーと連携し、アプリに必要なライブデータを提供します

手順（セットアップ、テスト、Shipp）に従うことが、最初の接続を作成する最善の方法です。

利用可能なデータ

• スポーツ： NBA、NFL、NCAA フットボール、MLB、サッカー（複数のリーグ）
• ニュース、金融、旅行、ショッピング、ソーシャル、予測市場、天気 — 近日公開

---

認証

すべてのエンドポイントには API キーが必要です。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（int）：返すイベントの最大数。デフォルト：100
• since_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（int、省略可能）
• since_event_id（ULID、省略可能）

フロー：

1. エージェントがリクエストを送信し、料金の詳細を含む 402 Payment Required を受け取ります
2. エージェントが資金の入ったウォレットで支払いに署名します
3. エージェントが PAYMENT-SIGNATURE ヘッダーを付けて再試行します
4. サーバーがデータを返します（Run Connection と同じ形式）

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

すべての行にすべてのフィールドが含まれるわけではありません。すべてのフィールドを省略可能なものとして扱ってください。エージェントとクライアントは、キーが欠落していても適切に処理できるようにしてください。

ドキュメント全文

---

エラー形式

エラーは 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[] 配列から未加工のイベントデータを取得します。

手順

1. 1 つの画面について「リアルタイム契約」を作成します — ユーザーへの約束、トリガーとなるイベント、必要なデータ形式、鮮度の許容範囲、障害時の動作を定義します。

2. 契約を filter_instructions に変換します — 短く、明確で、テスト可能かつ対象を絞った指示にします。ドメイン（例：「NBA」）を含め、対象のエンティティや時間を絞り込み、表示したい内容を明記します。

3. 接続を一度だけ作成し、connection_id を保存します — 実行のたびに作成しないでください。時間とコストを節約し、安定性も向上します。

4. 接続を実行して更新情報を取得します — プル型のポーリングを使用します。

   • ページ読み込み時：妥当な since を指定して実行します
   • 一定間隔（5～30 秒）：直近のイベントを since_event_id に設定して再実行します
   • UI の状態にイベントをマージし、重複を除去します

5. スキーマが柔軟な data[] を慎重に扱います — すべてのフィールドを任意として扱い、安全なアクセス方法を優先し、未知のデータ形式をログに記録します。

6. 重複を除去し、順序を整え、整合させます — 確認済みのイベント ID を一定期間保持し、タイムスタンプまたは ID 順（辞書順で安定）に並べ替え、最大のイベント ID を since_event_id として送信します。

スポーツ向けヘルパー

スケジュールエンドポイントを使用して、現在の試合を確認します。試合の情報を参考に filter_instructions を作成し、接続を作成します。

---

セットアップ手順

ドキュメント全文

1. 接続を作成します： 希望するデータを説明する filter_instructions を指定して /api/v1/connections/create に POST します（例：「今日の NBA の全試合を追跡し、得点とプレイごとの状況を含める」）
2. レスポンスから connection_id を保存します
3. 接続を一覧表示します： /api/v1/connections に GET して、保存済みの接続を確認します（呼び出しは無料です）

---

接続のテスト

ドキュメント全文

コストと時間を抑えるには、任意のパラメーターを指定して接続を呼び出します。

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 を使用します。
• 接続を作成する前に、スケジュールエンドポイントを使用して game_id とチーム名を確認します。
• 上限に達したときは、エラーメッセージをユーザーに直接表示します。
• data[] 内のすべてのフィールドを任意として扱います — 存在確認と適切なフォールバックを使用します。
• 開発中は未知のデータ形式をログに記録し、filter_instructions の改善に役立てます。
• ポーリング間隔：ドメインとコストへの配慮に応じて 5～30 秒です。
• 確認済みのイベント ID を一定期間保持して、イベントの重複を除去します。

---

プラットフォームガイド

全ガイド一覧

プラットフォーム	ガイド
Lovable	https://markdown.new/docs.shipp.ai/platform-guides/lovable/
Base44	https://markdown.new/docs.shipp.ai/platform-guides/base44/
Claude Code	https://markdown.new/docs.shipp.ai/platform-guides/claude-code/
Blink	https://markdown.new/docs.shipp.ai/platform-guides/blink/
Replit	https://markdown.new/docs.shipp.ai/platform-guides/replit/

ガイドがないプラットフォームには、https://docs.shipp.ai のドキュメントを読むよう伝えてください。

Claude Code の場合：

1. shipp スキル（このファイル）を使うか、curl -fsSL "https://shipp.ai/SKILL.md" > ~/.claude/skills/shipp/SKILL.md を実行します
2. .env に API キーを追加します：SHIPP_API_KEY=shipp-live-123-your-api-key
3. 統合をテストします

---

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/ でバージョン管理されています。互換性を損なう変更が必要になった場合は、新しいプレフィックスで新しいバージョンを導入します。

ドキュメント全文