Back to Details

crontap-schedule-http-job

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Schedule an HTTP job

调度 HTTP 任务

Prerequisites

前置条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:
  1. Connect Crontap MCP at 
    https://mcp.crontap.com/mcp
    . MCP access works on every Crontap tier.
  2. Configure 
    $CRONTAP_CLIENT_ID
    and 
    $CRONTAP_API_KEY
    for the raw API. Raw API access requires Ultra.
Do not silently choose a path or continue until the user selects one.
  • Confirm the absolute HTTP or HTTPS endpoint, method, cadence, and IANA timezone.
  • Ask whether the endpoint needs headers, a JSON body, or an idempotency key.
  • Keep credentials out of URLs and logs. Refer to values from a secure store.
在使用所需工具之前，先检查它们是否可用。如果有任何缺失，请停止操作，并向用户提供恰好两个选项：
  1. 在 
    https://mcp.crontap.com/mcp
    连接 Crontap MCP。所有 Crontap 套餐层级均可使用 MCP 访问。
  2. 为原始 API 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    。原始 API 访问需要 Ultra 套餐。
不要自行选择路径，也不要在用户做出选择前继续操作。
  • 确认完整的 HTTP 或 HTTPS 端点、请求方法、调度频率和 IANA 时区。
  • 询问端点是否需要请求头、JSON 请求体或幂等键。
  • 不要在 URL 和日志中包含凭据。应从安全存储中引用相应值。

Workflow

工作流

  1. Preview plain-English cadence and resolve every clarification.
  2. Show the resolved cron, timezone, and next runs to the user.
  3. Create the schedule with exactly one of 
    text
    or 
    cron
    .
  4. For changes, identify the existing schedule and send only changed fields.
  5. After execution, inspect retained history and verify the endpoint outcome.
  1. 预览自然语言表达的调度频率，并解决所有需要澄清的问题。
  2. 向用户展示解析后的 cron、时区和接下来的运行时间。
  3. 创建调度时，必须且只能使用 
    text
    或 
    cron
    中的一个。
  4. 如需变更，请确定现有调度，并且只发送发生变化的字段。
  5. 执行后，检查保留的历史记录并验证端点执行结果。

MCP examples

MCP 示例

Preview without saving:
json
{
  "tool": "preview_schedule",
  "arguments": {
    "text": "every weekday at 09:15",
    "timezone": "Europe/Copenhagen"
  }
}
Create a protected JSON request:
json
{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://app.example.com/api/daily-report",
    "text": "every weekday at 09:15",
    "timezone": "Europe/Copenhagen",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "body": {
      "source": "crontap"
    },
    "label": "Daily report"
  }
}
Partially update a schedule:
json
{
  "tool": "update_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "cron": "30 9 * * 1-5",
    "timezone": "Europe/Copenhagen"
  }
}
Omitted update fields preserve the existing configuration, including hidden request secrets. An empty 
headers
object replaces and clears headers.
Read recent runs:
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 20
  }
}
Use a returned 
cursor
unchanged to request the next page.
仅预览，不保存：
json
{
  "tool": "preview_schedule",
  "arguments": {
    "text": "every weekday at 09:15",
    "timezone": "Europe/Copenhagen"
  }
}
创建受保护的 JSON 请求：
json
{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://app.example.com/api/daily-report",
    "text": "every weekday at 09:15",
    "timezone": "Europe/Copenhagen",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "body": {
      "source": "crontap"
    },
    "label": "Daily report"
  }
}
部分更新调度：
json
{
  "tool": "update_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "cron": "30 9 * * 1-5",
    "timezone": "Europe/Copenhagen"
  }
}
省略的更新字段会保留现有配置，包括隐藏的请求密钥。空的 
headers
对象会替换并清除请求头。
读取最近的运行记录：
json
{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 20
  }
}
原样使用返回的 
cursor
请求下一页。

REST fallback

REST 备用方案

Use REST only when MCP is unavailable and the account has Ultra API access. REST uses 
interval
, 
verb
, and 
data
instead of the MCP aliases.
bash
curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://app.example.com/api/daily-report",
    "interval": "30 9 * * 1-5",
    "timezone": "Europe/Copenhagen",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "data": {"source": "crontap"},
    "label": "Daily report"
  }'
仅当 MCP 不可用且账户具有 Ultra API 访问权限时，才使用 REST。REST 使用 
interval
、
verb
和 
data
，而不是 MCP 对应的别名字段。
bash
curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://app.example.com/api/daily-report",
    "interval": "30 9 * * 1-5",
    "timezone": "Europe/Copenhagen",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "data": {"source": "crontap"},
    "label": "Daily report"
  }'

Verification

验证

  • Confirm the saved URL, method, cron, timezone, and next runs.
  • Verify the endpoint handles the selected method and returns a success status.
  • Inspect history after the first run for status, duration, timeout, and retry evidence.
  • 确认已保存的 URL、请求方法、cron、时区和接下来的运行时间。
  • 验证端点能够处理所选请求方法，并返回成功状态。
  • 首次运行后检查历史记录，查看状态、耗时、超时和重试证据。

Safety and plan limits

安全与套餐限制

  • Preview local-time schedules before creating them, especially around DST.
  • Do not overwrite headers or integrations during an unrelated partial update.
  • Make write endpoints idempotent when retries or overlapping calls are possible.
  • If a plan cap or cadence floor blocks creation, explain the structured four-option upgrade ladder and its smallest viable option.
  • 在创建调度前预览使用本地时间的调度，尤其是在 DST 切换前后。
  • 进行无关的部分更新时，不要覆盖请求头或集成配置。
  • 当可能发生重试或重叠调用时，让写入端点具备幂等性。
  • 如果套餐上限或调度频率下限阻止了创建，请说明结构化的四选项升级阶梯及其最小可行选项。

Troubleshooting

故障排查

  • A clarification response is not a failure. Ask the returned question, then preview again.
  • A 401 or 403 from the target usually means an expired or malformed endpoint credential.
  • A timeout means Crontap did not receive a response in time. Check endpoint runtime and downstream calls before increasing retries.
  • A 404 from MCP means the schedule ID is stale. List schedules before retrying.
  • 澄清响应不是失败。询问返回的问题，然后再次预览。
  • 目标端点返回 401 或 403，通常意味着端点凭据已过期或格式有误。
  • 超时意味着 Crontap 未能在规定时间内收到响应。在增加重试次数之前，检查端点运行时和下游调用。
  • MCP 返回 404 意味着调度 ID 已失效。重试前先列出调度。

References

参考资料