Apps API · EventBindings
EventBindings: 16 个接口
POST /api/v1/automation-authorizations/preview
Render an exact automation authorization proposal
权限(scope): automations:binding:read · 调用方式: appToken · operationId: preview-automation-authorization
Required app scope: automations:binding:read.
请求体
application/json · AutomationAuthorizationPlan
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
configuration |
AutomationCreationConfiguration |
是 | |
expected_version |
integer (int64) | ||
operation |
string: create, update |
是 | |
source_kind |
string: timer, webhook |
是 | |
target_binding_id |
string (uuid) |
回包
200OK —application/json·DataResponseAutomationAuthorizationPreviewBodydefaultError —application/problem+json·D8Error
POST /api/v1/automation-authorizations/proposals
Send a readable automation confirmation
权限(scope): automations:binding:write · 调用方式: appToken · operationId: propose-automation-authorization
Required app scope: automations:binding:write.
请求体
application/json · AutomationProposalRequest
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
configuration |
AutomationCreationConfiguration |
是 | |
expected_version |
integer (int64) | ||
operation |
string: create, update |
是 | |
replaces_proposal_message_id |
string | ||
request_id |
string (uuid) | 是 | |
requester_member_id |
string (uuid) | ||
source_kind |
string: timer, webhook |
是 | |
target_binding_id |
string (uuid) |
回包
200OK —application/json·DataResponseAutomationProposalResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/automation-authorizations/proposals/{message_id}
Read automation confirmation status
权限(scope): automations:binding:read · 调用方式: appToken · operationId: get-automation-authorization-proposal
Required app scope: automations:binding:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
message_id |
path | string | 是 |
回包
200OK —application/json·DataResponseAutomationProposalStatusBodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings
List event bindings
权限(scope): automations:binding:read · 调用方式: appToken · operationId: list-event-bindings
Required app scope: automations:binding:read.
Returns the EventBindings of the calling org that the caller can see (the platform hides private projects' automations from everyone but the project owner and the owner's Agents). Optional scope=org|private narrows the list. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
scope |
query | string: org, private |
Narrow to automations of organization or private projects; omitted lists every automation the caller can see |
回包
200OK —application/json·DataResponseListEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings
Create event binding
权限(scope): automations:binding:write · 调用方式: appToken · operationId: create-event-binding
Required app scope: automations:binding:write.
Creates a timer EventBinding. The server enforces who may create one: an Agent caller must set a human owner and itself as lead. Response wrapped in standard envelope.
请求体
application/json · CreateEventBindingRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
anchor_at |
string (date-time) | Interval phase anchor instant | |
authorization_card_interaction_id |
string (uuid) | ||
authorization_confirmation_message_id |
string | ||
authorization_proposal_message_id |
string | ||
cron_expr |
string | 5-field cron expression, required for cron schedules | |
interval_seconds |
integer (int64) | Elapsed interval in seconds | |
lead_member_id |
string (uuid) | 是 | Lead agent member UUID (executor) |
owner_member_id |
string (uuid) | Human Owner UUID; omitted defaults to the human caller. Agent callers require an explicit human Owner | |
project_member_additions |
array of string | Members added to spec.project_id atomically with this write: only lead_member_id and/or owner_member_id, each once. The acting human (caller, or the confirming human for Agent writes) needs project write access. Must be empty for the Inbox | |
result_notification_policy |
string: every, failure_only, none |
Final result DM policy; omitted timer creates default to every. HTTP null is tolerated as omission | |
run_at |
string (date-time) | Once trigger instant | |
schedule_kind |
string: cron, once, interval |
Schedule mode; omitted means cron | |
spec |
SpecStruct |
是 | |
timezone |
string | IANA timezone |
回包
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/preview
Preview upcoming trigger times
权限(scope): automations:binding:read · 调用方式: appToken · operationId: preview-event-binding
Required app scope: automations:binding:read.
Returns upcoming trigger instants for a cron expression and optional timezone without creating or changing a binding. Scheduling is validated server-side.
请求体
application/json · PreviewEventBindingRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
anchor_at |
string (date-time) | Interval phase anchor instant | |
cron_expr |
string | Five-field cron expression, required for cron schedules | |
interval_seconds |
integer (int64) | Elapsed interval in seconds | |
run_at |
string (date-time) | Once trigger instant | |
schedule_kind |
string: cron, once, interval |
Schedule mode; omitted means cron | |
timezone |
string | IANA timezone; omitted or empty applies no timezone |
回包
200OK —application/json·DataResponseEventBindingPreviewBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/event-bindings/{event_binding_id}
Delete event binding
权限(scope): automations:binding:write · 调用方式: appToken · operationId: delete-event-binding
Required app scope: automations:binding:write.
Deletes an EventBinding; it no longer triggers. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings/{event_binding_id}
Get event binding
权限(scope): automations:binding:read · 调用方式: appToken · operationId: get-event-binding
Required app scope: automations:binding:read.
Returns an EventBinding by ID. Response wrapped in standard envelope.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
回包
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
PUT /api/v1/event-bindings/{event_binding_id}
Replace event binding configuration
权限(scope): automations:binding:write · 调用方式: appToken · operationId: update-event-binding
Required app scope: automations:binding:write.
Replaces the timer configuration using expected_version. Updating a completed single-run timer to a different valid future single-run schedule atomically reactivates it; otherwise its paused/enabled state is preserved. The server enforces caller ownership; stale versions return WORK_EVENT_BINDING_VERSION_CONFLICT (409).
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
请求体
application/json · UpdateEventBindingRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
anchor_at |
string (date-time) | Interval phase anchor instant | |
authorization_card_interaction_id |
string (uuid) | ||
authorization_confirmation_message_id |
string | ||
authorization_proposal_message_id |
string | ||
cron_expr |
string | Five-field cron expression, required for cron schedules | |
expected_version |
integer (int64) | 是 | Current binding version for optimistic concurrency control |
interval_seconds |
integer (int64) | Elapsed interval in seconds | |
lead_member_id |
string (uuid) | 是 | Lead agent member UUID |
owner_member_id |
string (uuid) | Human Owner UUID; omitted defaults to the human caller, not the previous owner. Agent callers require an explicit human Owner; the server enforces authorization | |
project_member_additions |
array of string | Members added to spec.project_id atomically with this write: only lead_member_id and/or owner_member_id, each once. The acting human (caller, or the confirming human for Agent writes) needs project write access. Must be empty for the Inbox. A non-empty list also resumes an automation paused for LEAD_PROJECT_ACCESS_REQUIRED or OWNER_PROJECT_ACCESS_REQUIRED once every dependency validates. Where resume-on-save is enabled on the deployment, any save by the Owner (direct, or confirmed in chat) that passes every check resumes an automation paused for LEAD_PROJECT_ACCESS_REQUIRED, OWNER_PROJECT_ACCESS_REQUIRED, MEMBER_UNAVAILABLE, PRIVATE_LEAD_OWNER_CHANGED or PROJECT_UNAVAILABLE, with or without this list; never a manual pause, and an elapsed single run stays paused. Read enabled and pause_reason in the response | |
result_notification_policy |
string: every, failure_only, none |
Omitted preserves the current policy and migration notice; an explicit enum value clears the notice, even when unchanged. HTTP null is tolerated as omission | |
run_at |
string (date-time) | Once trigger instant | |
schedule_kind |
string: cron, once, interval |
Replacement schedule mode; omitted means cron | |
spec |
UpdateEventBindingSpec |
是 | Complete issue specification to replace the current configuration; an omitted knowledge base choice (knowledge_base_mode with knowledge_base_id) or unattached keeps the current one |
timezone |
string | 是 | Required for full replacement, unlike create. IANA timezone, or an explicit empty string to apply no timezone; does not retain the previous timezone |
回包
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings/{event_binding_id}/changes
List automation configuration changes
权限(scope): automations:binding:read · 调用方式: appToken · operationId: list-event-binding-changes
Required app scope: automations:binding:read.
Lists retained changes for one configuration, newest first. The server enforces organization and owner/lead authorization. Existing configurations have no fabricated history.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | |
cursor |
query | string | Pagination cursor (opaque, from previous response; omit for first page) | |
limit |
query | integer (int32) | Items per page (default: 20, max: 100) | |
order_by |
query | string | Sort expression, e.g. created_at:desc |
回包
200OK —application/json·CursorListResponseEventBindingChangeItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings/{event_binding_id}/occurrences
List event binding execution records
权限(scope): automations:binding:read · 调用方式: appToken · operationId: list-event-occurrences
Required app scope: automations:binding:read.
Returns a bounded window of scheduled occurrences and notification state, not the execution outcome of created issues. Records are ordered by scheduled_at descending, then id descending. The response contains only data, request_id, and server_time; it provides no total, has_more, or next-offset metadata. Returning limit records does not establish whether more records exist. History can change between requests, so limit and offset do not provide a stable snapshot. Access follows the caller's own permissions.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
limit |
query | integer (int32) | Maximum records in this bounded window; a full window does not guarantee more records exist | |
offset |
query | integer (int32) | Number of records to skip in the current history; separate requests do not share a snapshot |
回包
200OK —application/json·DataResponseListEventOccurrenceItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/{event_binding_id}/pause
Pause event binding
权限(scope): automations:binding:write · 调用方式: appToken · operationId: pause-event-binding
Required app scope: automations:binding:write.
Pauses future scheduling using expected_version. The server enforces caller ownership; stale versions return WORK_EVENT_BINDING_VERSION_CONFLICT (409).
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
请求体
application/json · ChangeEventBindingStateRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
expected_version |
integer (int64) | 是 | Current binding version for optimistic concurrency control |
回包
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/{event_binding_id}/resume
Resume event binding
权限(scope): automations:binding:write · 调用方式: appToken · operationId: resume-event-binding
Required app scope: automations:binding:write.
Resumes scheduling using expected_version after the server validates dependencies and caller ownership. Stale versions return WORK_EVENT_BINDING_VERSION_CONFLICT (409).
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
请求体
application/json · ChangeEventBindingStateRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
expected_version |
integer (int64) | 是 | Current binding version for optimistic concurrency control |
回包
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/{event_binding_id}/run
Run an event binding once
权限(scope): automations:binding:write · 调用方式: appToken · operationId: run-event-binding
Required app scope: automations:binding:write.
Creates one manual occurrence and Issue using a binding-scoped idempotency key. The server enforces ownership and expected_version. Does not change pause state or the next scheduled trigger; occurrence success is not Agent execution success.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
请求体
application/json · RunEventBindingRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
confirm_paused |
boolean | Explicit acknowledgement to run once while paused; does not resume scheduling | |
expected_version |
integer (int64) | 是 | Current configuration version |
idempotency_key |
string | 是 | Stable key for retries of one manual run, scoped to this binding |
回包
200OK —application/json·DataResponseEventBindingRunBodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings/{event_binding_id}/runs
List automation runs
权限(scope): automations:binding:read · 调用方式: appToken · operationId: list-automation-runs
Required app scope: automations:binding:read.
Returns a bounded window of timer, manual and webhook runs with authoritative outcomes and latest revisions. Filtered webhook receipts are excluded. Pagination does not share a snapshot.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 | EventBinding UUID |
limit |
query | integer (int32) | Maximum records in this bounded window; a full window does not guarantee more records exist | |
offset |
query | integer (int32) | Number of records to skip in the current history; separate requests do not share a snapshot |
回包
200OK —application/json·DataResponseListEventOccurrenceItemBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/event-bindings/{event_binding_id}/title
Rename an automation
权限(scope): automations:binding:write · 调用方式: appToken · operationId: rename-event-binding
Required app scope: automations:binding:write.
Active human owners can rename a current timer or webhook without changing execution configuration. The server checks organization, ownership and expected version, and records the title change atomically. Agents must continue using the existing confirmed configuration update flow.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | 是 |
请求体
application/json · RenameEventBindingRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
expected_version |
integer (int64) | 是 | |
title |
string | 是 | Automation title; at most 200 Unicode code points |
回包
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
