Praxis文档
控制台
自动化

创建触发器

为已发布脚本或工作流创建定时或 webhook 触发器，每租户最多 100 个启用中的触发器。

为已发布脚本或工作流创建定时或 webhook 触发器，每租户最多 100 个启用中的触发器。目标只接受精确版本或标签，webhook_url 仅在创建 webhook 或轮换时返回，须妥善保存。

POST /automation/v1/triggers

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
namestring必填 / 必有；触发器显示名，1–100 字符且不能全为空白；不要求唯一。 minLength: 1；maxLength: 100
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
labelsobject可选；最多 64 个用户标签，禁止 praxis. 前缀；内部标签不占用名额。键 1–40 字符、值最多 500 字符。
targetstring必填 / 必有；ns/name@tag 或 ns/name@version，省略 @ 时用 latest；触发器不接受版本范围。
inputnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]可选；定时触发的静态 JSON 输入，默认 {}；创建与修改时校验目标契约。webhook 未显式提供时不在创建阶段校验回调输入。
input（分支5).*（分支5)object递归 JSON 值。
input（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；schedule 按计划触发，webhook 由 HTTP 回调触发；创建后不可更改。
scheduleobject / object / object可选；三选一：cron 为五段表达式（支持 L/W/#）；every 为 ISO 8601 时长或时长对象，须为正整数毫秒且在 1 分钟至 366 天之间；at 为未来一年内的一次性 RFC 3339 时间。
schedule（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支3).atstring必填 / 必有；一次性触发时刻，需带 Z 或 ±HH:MM 时区；必须在请求时刻至一年后之间。调用时将示例替换为该范围内的未来时间。 pattern: "(Z|[+-]\d\d:\d\d)$"；format: "date-time"
timezonestring可选；IANA 时区，默认 UTC；夏令时跳过不存在的时刻，重复时刻只触发一次。 default: "UTC"
start_atstring / null可选；可选开始时间，RFC 3339 且带时区；null 表示不设下界。
end_atstring / null可选；可选结束时间，RFC 3339 且带时区；不能早于 start_at，null 表示不设上界。
overlap"skip" / "allow"可选；skip（默认）在前次运行未结束时跳过，allow 允许并行触发。 default: "skip"
catchup_window_secondsinteger可选；非负整数秒，默认 300；仅对定时触发器生效；延迟超过窗口时记为 missed，不补跑，webhook 不受此窗口影响。 default: 300；minimum: 0
webhookobject可选；input_mode 为 body（默认）或 envelope；后者包含 body、raw_body、raw_body_encoding、白名单 headers、webhook_id、received_at，完整 URL 仅创建或轮换时返回。 不接受额外字段。
webhook.input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。 default: "body"

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TARGET已发布的 docs-samples/name@1.0.0
: "${TARGET:?Set TARGET}"
BODY=$(jq -n --arg TARGET "$TARGET" '{
  "name": "sample-webhook",
  "target": $TARGET,
  "kind": "webhook",
  "labels": {
    "namespace": "docs-samples"
  },
  "webhook": {
    "input_mode": "body"
  }
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$BODY"
import { createAutomationClient } from '@deepractice-ai/praxis-sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.create({
  "body": {
    "name": "sample-webhook",
    "target": env("TARGET"),
    "kind": "webhook",
    "labels": {
      "namespace": "docs-samples"
    },
    "webhook": {
      "input_mode": "body"
    }
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
usage_30dobject / null可选；创建响应中恒为 null；近 30 天用量只在 GET /triggers/{id} 返回。
usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0
webhook_urlstring可选；Returned only on webhook creation or rotation. format: "uri"

实测响应

HTTP 200

{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {},
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "enabled",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:09.974Z",
  "etag": "etag_00mv67mzzqc6ef5487c69f4857b65b91dab497104c",
  "webhook_url": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/${WEBHOOK_TOKEN}"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。 INPUT_INVALID：输入不满足目标契约或业务校验。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。 NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。
429TRIGGER_LIMIT：租户已达到 100 个启用触发器的上限。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出触发器

分页列出租户触发器，可按目标、类型和状态筛选。

读取触发器

读取规则、状态、未来触发时间与最近触发结果。

导出
本页 Markdown本节 Markdown整本 PDF

本页内容

鉴权请求字段application/json示例响应HTTP 200实测响应错误码