# 创建触发器 (/docs/api/native/automation/createTrigger)





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

`POST /automation/v1/triggers`

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

## 请求字段 [#请求字段]

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

### application/json [#applicationjson]

不接受额外字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| name | `string` | 必填 / 必有；触发器显示名，1–100 字符且不能全为空白；不要求唯一。 minLength: 1；maxLength: 100 |
| description | `string` | 可选；说明，最多 1000 个字符。 maxLength: 1000 |
| labels | `object` | 可选；最多 64 个用户标签，禁止 praxis. 前缀；内部标签不占用名额。键 1–40 字符、值最多 500 字符。 |
| target | `string` | 必填 / 必有；ns/name@tag 或 ns/name@version，省略 @ 时用 latest；触发器不接受版本范围。 |
| input | `null` / `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 回调触发；创建后不可更改。 |
| schedule | `object` / `object` / `object` | 可选；三选一：cron 为五段表达式（支持 L/W/#）；every 为 ISO 8601 时长或时长对象，须为正整数毫秒且在 1 分钟至 366 天之间；at 为未来一年内的一次性 RFC 3339 时间。 |
| schedule（分支1).cron | `string` | 必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule（分支2).every | `string` / `object` | 必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。 |
| schedule（分支2).every（分支2).days | `integer` | 可选；天数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).hours | `integer` | 可选；小时数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).minutes | `integer` | 可选；分钟数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).seconds | `integer` | 可选；秒数，非负整数。 minimum: 0 |
| schedule（分支2).every（分支2).milliseconds | `integer` | 可选；毫秒数，非负整数。 minimum: 0 |
| schedule（分支3).at | `string` | 必填 / 必有；一次性触发时刻，需带 Z 或 ±HH:MM 时区；必须在请求时刻至一年后之间。调用时将示例替换为该范围内的未来时间。 pattern: "(Z\|[+-]\\d\\d:\\d\\d)$"；format: "date-time" |
| timezone | `string` | 可选；IANA 时区，默认 UTC；夏令时跳过不存在的时刻，重复时刻只触发一次。 default: "UTC" |
| start_at | `string` / `null` | 可选；可选开始时间，RFC 3339 且带时区；null 表示不设下界。 |
| end_at | `string` / `null` | 可选；可选结束时间，RFC 3339 且带时区；不能早于 start_at，null 表示不设上界。 |
| overlap | `"skip"` / `"allow"` | 可选；skip（默认）在前次运行未结束时跳过，allow 允许并行触发。 default: "skip" |
| catchup_window_seconds | `integer` | 可选；非负整数秒，默认 300；仅对定时触发器生效；延迟超过窗口时记为 missed，不补跑，webhook 不受此窗口影响。 default: 300；minimum: 0 |
| webhook | `object` | 可选；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 安装与示例环境](/docs/api/native/automation)

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

| 变量 | 来源 |
| --- | --- |
| TARGET | [已发布的 docs-samples/name@1.0.0](/docs/api/native/automation/publishScriptVersion) |

```bash
: "${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"
```

```typescript
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 [#http-200]

Success

| 响应头 | 类型 | 说明 |
| --- | --- | --- |
| ETag | `string` | Current resource revision for conditional updates. |
| Idempotent-Replayed | `boolean` | Present and true when replaying the first response for this key. |

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| name | `string` | 必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100 |
| description | `string` | 必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000 |
| labels | `object` | 必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。 |
| target | `string` | 必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。 |
| input | `null` / `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 请求触发。 |
| schedule | `object` / `object` / `object` / `null` | 必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。 |
| schedule（分支1)（分支1).cron | `string` | 必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once. |
| schedule（分支1)（分支2).every | `string` / `object` | 必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。 |
| schedule（分支1)（分支2).every（分支2).days | `integer` | 可选；天数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).hours | `integer` | 可选；小时数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).minutes | `integer` | 可选；分钟数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).seconds | `integer` | 可选；秒数，非负整数。 minimum: 0 |
| schedule（分支1)（分支2).every（分支2).milliseconds | `integer` | 可选；毫秒数，非负整数。 minimum: 0 |
| schedule（分支1)（分支3).at | `string` | 必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time" |
| timezone | `string` | 必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC" |
| start_at | `string` / `null` | 必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。 |
| end_at | `string` / `null` | 必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。 |
| overlap | `"skip"` / `"allow"` | 必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip" |
| catchup_window_seconds | `integer` | 必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0 |
| webhook | `object` / `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_hint | `string` | 必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。 |
| id | `string` | 必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。 |
| owner | `string` | 必填 / 必有；所属租户，由网关注入；按不透明字符串处理。 |
| state | `"enabled"` / `"paused"` / `"expired"` | 必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。 |
| source | `"api"` / `"definition"` | 必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。 |
| created_by | `object` | 必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。 |
| created_by.type | `"user"` / `"api_key"` / `"agent"` / `"run"` / `"trigger"` | 必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。 |
| created_by.id | `string` | 必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。 |
| created_by_user_id | `string` | 必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。 |
| next_fire_times | `string[]` | 必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5 |
| last_firing | `object` / `null` | 必填 / 必有；最近一次触发记录；从未触发为 null。 |
| last_firing（分支1).id | `string` | 必填 / 必有；触发记录 ID；记录保留 30 天。 |
| last_firing（分支1).trigger_id | `string` | 必填 / 必有；所属触发器 ID（trg_ 前缀）。 |
| last_firing（分支1).scheduled_at | `string` | 必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time" |
| last_firing（分支1).fired_at | `string` | 必填 / 必有；实际触发的时间（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_id | `string` / `null` | 必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。 |
| last_firing（分支1).resolved_version | `string` / `null` | 必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。 |
| last_firing（分支1).error | `object` / `null` | 必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。 |
| last_firing（分支1).error（分支1).code | `string` | 必填 / 必有；失败的错误码。 |
| last_firing（分支1).error（分支1).message | `string` | 必填 / 必有；失败的说明文字。 |
| counts | `object` | 必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。 |
| counts.started | `integer` | 必填 / 必有；成功启动运行的次数。 minimum: 0 |
| counts.skipped | `integer` | 必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0 |
| counts.missed | `integer` | 必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0 |
| counts.failed | `integer` | 必填 / 必有；创建运行失败的次数。 minimum: 0 |
| created_at | `string` | 必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time" |
| updated_at | `string` | 必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time" |
| etag | `string` | 必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。 |
| usage_30d | `object` / `null` | 可选；创建响应中恒为 null；近 30 天用量只在 GET /triggers/{id} 返回。 |
| usage_30d（分支1).currency | `"USD"` | 必填 / 必有；金额币种，固定为 USD。 |
| usage_30d（分支1).cost | `string` | 必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\\.[0-9]{6}$" |
| usage_30d（分支1).pending_events | `integer` | 必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0 |
| webhook_url | `string` | 可选；Returned only on webhook creation or rotation. format: "uri" |

### 实测响应 [#实测响应]

HTTP 200

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

[鉴权错误与通用错误](/docs/api/errors) · 排查时保留响应头 `X-Request-Id`。