Apps API · EventBindings
EventBindings: 16 endpoints
POST /api/v1/automation-authorizations/preview
Render an exact automation authorization proposal
Scope: automations:binding:read · Called with: appToken · operationId: preview-automation-authorization
Required app scope: automations:binding:read.
Request body
application/json · AutomationAuthorizationPlan
| Field | Type | Required | Description |
|---|---|---|---|
configuration |
AutomationCreationConfiguration |
yes | |
expected_version |
integer (int64) | ||
operation |
string: create, update |
yes | |
source_kind |
string: timer, webhook |
yes | |
target_binding_id |
string (uuid) |
Responses
200OK —application/json·DataResponseAutomationAuthorizationPreviewBodydefaultError —application/problem+json·D8Error
POST /api/v1/automation-authorizations/proposals
Send a readable automation confirmation
Scope: automations:binding:write · Called with: appToken · operationId: propose-automation-authorization
Required app scope: automations:binding:write.
Request body
application/json · AutomationProposalRequest
| Field | Type | Required | Description |
|---|---|---|---|
configuration |
AutomationCreationConfiguration |
yes | |
expected_version |
integer (int64) | ||
operation |
string: create, update |
yes | |
replaces_proposal_message_id |
string | ||
request_id |
string (uuid) | yes | |
requester_member_id |
string (uuid) | ||
source_kind |
string: timer, webhook |
yes | |
target_binding_id |
string (uuid) |
Responses
200OK —application/json·DataResponseAutomationProposalResponseBodydefaultError —application/problem+json·D8Error
GET /api/v1/automation-authorizations/proposals/{message_id}
Read automation confirmation status
Scope: automations:binding:read · Called with: appToken · operationId: get-automation-authorization-proposal
Required app scope: automations:binding:read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
message_id |
path | string | yes |
Responses
200OK —application/json·DataResponseAutomationProposalStatusBodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings
List event bindings
Scope: automations:binding:read · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
scope |
query | string: org, private |
Narrow to automations of organization or private projects; omitted lists every automation the caller can see |
Responses
200OK —application/json·DataResponseListEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings
Create event binding
Scope: automations:binding:write · Called with: 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.
Request body
application/json · CreateEventBindingRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
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) | yes | 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 |
yes | |
timezone |
string | IANA timezone |
Responses
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/preview
Preview upcoming trigger times
Scope: automations:binding:read · Called with: 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.
Request body
application/json · PreviewEventBindingRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
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 |
Responses
200OK —application/json·DataResponseEventBindingPreviewBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/event-bindings/{event_binding_id}
Delete event binding
Scope: automations:binding:write · Called with: appToken · operationId: delete-event-binding
Required app scope: automations:binding:write.
Deletes an EventBinding; it no longer triggers. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Responses
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings/{event_binding_id}
Get event binding
Scope: automations:binding:read · Called with: appToken · operationId: get-event-binding
Required app scope: automations:binding:read.
Returns an EventBinding by ID. Response wrapped in standard envelope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Responses
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
PUT /api/v1/event-bindings/{event_binding_id}
Replace event binding configuration
Scope: automations:binding:write · Called with: 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).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Request body
application/json · UpdateEventBindingRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
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) | yes | Current binding version for optimistic concurrency control |
interval_seconds |
integer (int64) | Elapsed interval in seconds | |
lead_member_id |
string (uuid) | yes | 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 |
yes | 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 | yes | Required for full replacement, unlike create. IANA timezone, or an explicit empty string to apply no timezone; does not retain the previous timezone |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | |
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 |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | 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 |
Responses
200OK —application/json·DataResponseListEventOccurrenceItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/{event_binding_id}/pause
Pause event binding
Scope: automations:binding:write · Called with: 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).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Request body
application/json · ChangeEventBindingStateRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
expected_version |
integer (int64) | yes | Current binding version for optimistic concurrency control |
Responses
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/event-bindings/{event_binding_id}/resume
Resume event binding
Scope: automations:binding:write · Called with: 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).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Request body
application/json · ChangeEventBindingStateRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
expected_version |
integer (int64) | yes | Current binding version for optimistic concurrency control |
Responses
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 · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | EventBinding UUID |
Request body
application/json · RunEventBindingRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
confirm_paused |
boolean | Explicit acknowledgement to run once while paused; does not resume scheduling | |
expected_version |
integer (int64) | yes | Current configuration version |
idempotency_key |
string | yes | Stable key for retries of one manual run, scoped to this binding |
Responses
200OK —application/json·DataResponseEventBindingRunBodydefaultError —application/problem+json·D8Error
GET /api/v1/event-bindings/{event_binding_id}/runs
List automation runs
Scope: automations:binding:read · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes | 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 |
Responses
200OK —application/json·DataResponseListEventOccurrenceItemBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/event-bindings/{event_binding_id}/title
Rename an automation
Scope: automations:binding:write · Called with: 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.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
event_binding_id |
path | string (uuid) | yes |
Request body
application/json · RenameEventBindingRequestBody
| Field | Type | Required | Description |
|---|---|---|---|
expected_version |
integer (int64) | yes | |
title |
string | yes | Automation title; at most 200 Unicode code points |
Responses
200OK —application/json·DataResponseEventBindingItemBodydefaultError —application/problem+json·D8Error
