OpenMax
Free Trial

Apps API · EventBindings

EventBindings: 16 endpoints

← All groups

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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