xcrawl-search

XCrawl Search

概要

このスキルは、XCrawl Search API を使用してクエリに基づく結果を取得します。 デフォルトの動作は、上流 API のレスポンス本文をそのまま返す raw passthrough です。

必須のローカル設定

このスキルを使用する前に、ユーザーはローカル設定ファイルを作成し、XCRAWL_API_KEY を記述する必要があります。

パス：~/.xcrawl/config.json

{
  "XCRAWL_API_KEY": "<your_api_key>"
}

API キーはローカル設定ファイルのみから読み取ります。グローバル環境変数は要求しないでください。

クレジットとアカウントの設定

XCrawl API を使用するとクレジットが消費されます。 ユーザーがアカウントまたは利用可能なクレジットを持っていない場合は、https://dash.xcrawl.com/ での登録を案内してください。 登録後、リクエストを実行する前に、無料の 1000 クレジットプランを有効化できます。

ツールの権限ポリシー

実行時権限は curl と node のみを要求してください。 Python、シェルヘルパースクリプト、その他の実行時権限は要求しないでください。

API の概要

• 検索エンドポイント：POST /v1/search
• ベース URL：https://run.xcrawl.com
• 必須ヘッダー：Authorization: Bearer <XCRAWL_API_KEY>

使用例

cURL

API_KEY="$(node -e "const fs=require('fs');const p=process.env.HOME+'/.xcrawl/config.json';const k=JSON.parse(fs.readFileSync(p,'utf8')).XCRAWL_API_KEY||'';process.stdout.write(k)")"

curl -sS -X POST "https://run.xcrawl.com/v1/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"query":"AI web crawler API","location":"US","language":"en","limit":20}'

Node

node -e '
const fs=require("fs");
const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+"/.xcrawl/config.json","utf8")).XCRAWL_API_KEY;
const body={query:"web scraping pricing",location:"DE",language:"de",limit:30};
fetch("https://run.xcrawl.com/v1/search",{
  method:"POST",
  headers:{"Content-Type":"application/json",Authorization:`Bearer ${apiKey}`},
  body:JSON.stringify(body)
}).then(async r=>{console.log(await r.text());});
'

リクエストパラメーター

リクエストのエンドポイントとヘッダー

• エンドポイント：POST https://run.xcrawl.com/v1/search
• ヘッダー：
• Content-Type: application/json
• Authorization: Bearer <api_key>

リクエスト本文：トップレベルのフィールド

フィールド	型	必須	デフォルト	説明
query	string	はい	-	検索クエリ
location	string	いいえ	US	場所（国名／都市名／地域名または ISO コード。可能な範囲で対応）
language	string	いいえ	en	言語（ISO 639-1）
limit	integer	いいえ	10	結果の最大数（1-100）

レスポンスパラメーター

フィールド	型	説明
search_id	string	タスク ID
endpoint	string	常に search
version	string	バージョン
status	string	completed
query	string	検索クエリ
data	object	検索結果データ
started_at	string	開始時刻（ISO 8601）
ended_at	string	終了時刻（ISO 8601）
total_credits_used	integer	使用したクレジットの合計

現在の API リファレンスに記載されている data に関する注記：

• 具体的な結果スキーマは実装によって定義されます
• credits_used や credits_detail などの課金フィールドが含まれます

ワークフロー

1. リクエストを明確な検索目的として書き換えます。

• 対象、地域、言語、新しさに関する意図を含めます。

2. POST /v1/search を構築して実行します。

• リクエストを明示的かつ決定的なものにします。

3. API の raw レスポンスをそのまま返します。

• 要求されない限り、関連性の要約を生成しないでください。

出力仕様

以下を返します。

• 使用したエンドポイント（POST /v1/search）
• リクエストに使用した request_payload
• 検索呼び出しからの raw レスポンス本文
• リクエストが失敗した場合はエラーの詳細

ユーザーが明示的に要約を要求しない限り、要約は生成しないでください。

ガードレール

• API が提示していないランキング保証を主張しないでください。
• 利用できないフィルターやレスポンスフィールドを捏造しないでください。
• コアロジックにプロバイダー固有のツールスキーマをハードコードしないでください。