XCrawl Map
Overview
This skill uses XCrawl Map API to discover URLs for a site.
Default behavior is raw passthrough: return upstream API response bodies as-is.
Required Local Config
Before using this skill, the user must create a local config file and write XCRAWL_API_KEY into it.
Path: INLINECODE1
CODEBLOCK0
Read API key from local config file only. Do not require global environment variables.
Credits and Account Setup
Using XCrawl APIs consumes credits.
If the user does not have an account or available credits, guide them to register at https://dash.xcrawl.com/.
After registration, they can activate the free 1000 credits plan before running requests.
Tool Permission Policy
Request runtime permissions for curl and node only.
Do not request Python, shell helper scripts, or other runtime permissions.
API Surface
- - Start map task: INLINECODE6
- Base URL: INLINECODE7
- Required header: INLINECODE8
Usage Examples
cURL
CODEBLOCK1
Node
CODEBLOCK2
Request Parameters
Request endpoint and headers
- - Endpoint: INLINECODE9
- Headers:
- INLINECODE10
- INLINECODE11
Request body: top-level fields
| Field | Type | Required | Default | Description |
|---|
| INLINECODE12 | string | Yes | - | Site entry URL |
| INLINECODE13 |
string | No | - | Regex filter for URLs |
|
limit | integer | No |
5000 | Max URLs (up to
100000) |
|
include_subdomains | boolean | No |
true | Include subdomains |
|
ignore_query_parameters | boolean | No |
true | Ignore URLs with query parameters |
Response Parameters
| Field | Type | Description |
|---|
| INLINECODE21 | string | Task ID |
| INLINECODE22 |
string | Always
map |
|
version | string | Version |
|
status | string |
completed |
|
url | string | Entry URL |
|
data | object | URL list data |
|
started_at | string | Start time (ISO 8601) |
|
ended_at | string | End time (ISO 8601) |
|
total_credits_used | integer | Total credits used |
INLINECODE32 fields:
- -
links: URL list - INLINECODE34 : URL count
- INLINECODE35 : credits used
- INLINECODE36 : credit breakdown
Workflow
- 1. Restate mapping objective.
- - Discovery only, selective crawl planning, or structure analysis.
- 2. Build and execute
POST /v1/map.
- - Keep filters explicit and reproducible.
- 3. Return raw API response directly.
- - Do not synthesize URL-family summaries unless requested.
Output Contract
Return:
- - Endpoint used (
POST /v1/map) - INLINECODE39 used for the request
- Raw response body from map call
- Error details when request fails
Do not generate summaries unless the user explicitly requests a summary.
Guardrails
- - Do not claim full site coverage if
limit is reached. - Do not mix inferred URLs with returned URLs.
- Do not hardcode provider-specific tool schemas in core logic.
XCrawl Map
概述
此技能使用 XCrawl Map API 来发现网站的 URL。
默认行为是原始透传：按原样返回上游 API 响应体。
所需本地配置
使用此技能前，用户必须创建本地配置文件并在其中写入 XCRAWLAPIKEY。
路径：~/.xcrawl/config.json
json
{
XCRAWLAPIKEY: apikey>
}
仅从本地配置文件读取 API 密钥。不需要全局环境变量。
积分与账户设置
使用 XCrawl API 会消耗积分。
如果用户没有账户或可用积分，请引导他们前往 https://dash.xcrawl.com/ 注册。
注册后，他们可以在运行请求前激活免费的 1000 积分套餐。
工具权限策略
仅请求 curl 和 node 的运行时权限。
不请求 Python、Shell 辅助脚本或其他运行时权限。
API 接口
- - 启动地图任务：POST /v1/map
- 基础 URL：https://run.xcrawl.com
- 必需请求头：Authorization: Bearer APIKEY>
使用示例
cURL
bash
APIKEY=$(node -e const fs=require(fs);const p=process.env.HOME+/.xcrawl/config.json;const k=JSON.parse(fs.readFileSync(p,utf8)).XCRAWLAPI_KEY||;process.stdout.write(k))
curl -sS -X POST https://run.xcrawl.com/v1/map \
-H Content-Type: application/json \
-H Authorization: Bearer ${API_KEY} \
-d {url:https://example.com,filter:/docs/.*,limit:2000,includesubdomains:true,ignorequery_parameters:false}
Node
bash
node -e
const fs=require(fs);
const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+/.xcrawl/config.json,utf8)).XCRAWLAPIKEY;
const body={url:https://example.com,filter:/docs/.*,limit:3000,includesubdomains:true,ignorequery_parameters:false};
fetch(https://run.xcrawl.com/v1/map,{
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/map
- 请求头：
- Content-Type: application/json
- Authorization: Bearer
请求体：顶层字段
| 字段 | 类型 | 必需 | 默认值 | 描述 |
|---|
| url | 字符串 | 是 | - | 网站入口 URL |
| filter |
字符串 | 否 | - | URL 的正则过滤器 |
| limit | 整数 | 否 | 5000 | 最大 URL 数量（上限 100000） |
| include_subdomains | 布尔值 | 否 | true | 包含子域名 |
| ignore
queryparameters | 布尔值 | 否 | true | 忽略带查询参数的 URL |
响应参数
| 字段 | 类型 | 描述 |
|---|
| map_id | 字符串 | 任务 ID |
| endpoint |
字符串 | 始终为 map |
| version | 字符串 | 版本号 |
| status | 字符串 | completed |
| url | 字符串 | 入口 URL |
| data | 对象 | URL 列表数据 |
| started_at | 字符串 | 开始时间（ISO 8601） |
| ended_at | 字符串 | 结束时间（ISO 8601） |
| total
creditsused | 整数 | 总消耗积分 |
data 字段：
- - links：URL 列表
- totallinks：URL 数量
- creditsused：消耗积分
- credits_detail：积分明细
工作流程
- 1. 明确地图绘制目标。
- 2. 构建并执行 POST /v1/map。
- 3. 直接返回原始 API 响应。
输出约定
返回：
- - 使用的端点（POST /v1/map）
- 请求使用的 request_payload
- 地图调用的原始响应体
- 请求失败时的错误详情
除非用户明确要求摘要，否则不生成摘要。
防护措施
- - 如果达到 limit 限制，不要声称覆盖了全站。
- 不要将推断的 URL 与返回的 URL 混在一起。
- 不要在核心逻辑中硬编码特定提供商的工具模式。
