Update automation

PUT /api/v3/automations/{id}

Request

Response

URL

PUT https://example.aha.io/api/v3/automations/123

JSON body

{
  "record": {}
}

cURL command

curl --request PUT 'https://example.aha.io/api/v3/automations/123' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "record": {}
}'

Request conventions

API key or OAuth2 access token. See Authentication.

Use your account domain and token in copied requests. Request values and conditional fields must satisfy your account’s validation rules.

URL settings

Account subdomain

The part before .aha.io. Leave blank to use the example domain.

ID of the automation

Request fields

Send only the fields you want to change inside a JSON record object. This applies to both PUT and PATCH.

Only writable fields for this endpoint are listed. Required flags reflect the endpoint schema; record and workspace validation also applies.

Search request fields

Field	Type	Response field
Name of the record.	string	`name`
Include name in request Accepted value shape and constraints Type: `string`
Trigger kind of the automation.	string	`trigger_kind`
Include trigger_kind in request Accepted value shape and constraints Type: `string` Allowed values: "field_changed", "record_created", "delayed_field_changed" Allowed values: `field_changedrecord_createddelayed_field_changed`
The field that will cause the automation to trigger for field_changed automations.	string	`trigger_field`
Include trigger_field in request Accepted value shape and constraints Type: `string` Allowed values: "name", "status", "team_status", "type", "initiative", "assigned_to_user", "created_by_user", "epic", "end_date", "start_date", "tags", "goals", "key_results", "score", "release", "watchers", "team", "iteration", "record_risk", "progress", "initial_estimate", "detailed_estimate", "record_links", "custom_field", "owner", "release_date", "development_started_on", "external_release_date", "initiatives", "roll_up_initiative", "time_frame", "rollup_goals", "target_metric", "starting_metric", "current_metric", "duplicate_idea", "categories", "visibility", "num_endorsements", "num_organizations", "submitted_idea_portal", "parent", "collections", "task_status", "due_date", "approval_groups", "assignees" Allowed values: `namestatusteam_statustypeinitiativeassigned_to_usercreated_by_userepicend_datestart_datetagsgoalskey_resultsscorereleasewatchersteamiterationrecord_riskprogressinitial_estimatedetailed_estimaterecord_linkscustom_fieldownerrelease_datedevelopment_started_onexternal_release_dateinitiativesroll_up_initiativetime_framerollup_goalstarget_metricstarting_metriccurrent_metricduplicate_ideacategoriesvisibilitynum_endorsementsnum_organizationssubmitted_idea_portalparentcollectionstask_statusdue_dateapproval_groupsassignees`
ID of the custom field definition id associated with the automation if trigger_field is custom_field.	string	`custom_field_definition`
Include custom_field_definition_id in request Accepted value shape and constraints Type: `string` Submit `custom_field_definition_id`; the response includes `custom_field_definition`.
Values that will be used to compare against the trigger field to determine if the automation should trigger.	array	`values`
Include values in request Accepted value shape and constraints Type: `array` Array item shape Type: `string`
The operation to use to determine if the automation should trigger.	string	`change_type`
Include change_type in request Accepted value shape and constraints Type: `string` Allowed values: "specific", "any", "=", "add", "remove", ">", "<", "current", "present", "blank", "present_with_comment", "parking_lot", "non_parking_lot" Allowed values: `specificany=addremove><currentpresentblankpresent_with_commentparking_lotnon_parking_lot`
Additional field information when using the record_links trigger_field.	string	`link_filter_type`
Include link_filter_type in request Accepted value shape and constraints Type: `string` Allowed values: "link_type", "linked_record", "linked_record_status" Allowed values: `link_typelinked_recordlinked_record_status`
The worksheet row of a worksheet custom field if applicable.	string	`field_worksheet_row`
Include field_worksheet_row in request Accepted value shape and constraints Type: `string`
Whether the automation is enabled.	boolean	`enabled`
Include enabled in request Accepted value shape and constraints Type: `boolean`
A list of additional conditions that must be met for the automation to trigger.	array	`trigger_conditions`
Include trigger_conditions in request Accepted value shape and constraints Type: `array` Array item shape Type: `one of the shapes below` Supported shape 1 Type: `string` Supported shape 2 Type: `object` field Type: `string` values Type: `array` Array item shape Type: `string` change_type Type: `string` field_worksheet_row Type: `string` custom_field_definition CustomFieldDefinition Type: `object` id Type: `integer` name Type: `string` internal_name Type: `string` key Type: `string` type Type: `string` Allowed values: "text", "note", "number", "date", "url", "checkbox", "attachment", "predefined_choice_list", "editable_choice_list", "predefined_tags", "tags", "conditional_choice", "scorecard", "worksheet", "many_to_many_relationship", "many_to_one_relationship", "one_to_many_relationship", "users", "workspaces", "goals", "initiatives", "key_results", "releases", "epics", "features", "ideas", "idea_categories", "organizations", "idea_created_by", "competitors", "personas", "creative_briefs" record_type Type: `string` Allowed values: "project", "feature", "epic", "requirement", "release", "release_phase", "initiative", "goal", "key_result", "idea", "idea_endorsement", "idea_organization", "idea_user", "creative_brief", "persona", "competitor", "capacity_investment", "team", "program_increment", "task", "document", "study", "interview", "custom_table" custom_table CustomObjectDefinition Type: `object` id Type: `integer` name Type: `string` key Type: `string` created_at Type: `string` (date-time) updated_at Type: `string` (date-time) description Note Type: `object` id Type: `integer` body Type: `string` editor_version Type: `integer` created_at Type: `string` (date-time) updated_at Type: `string` (date-time) prefix Type: `string` suffix Type: `string` use_delimiters Type: `boolean` label Type: `string` display Type: `string` Allowed values: "plain_text", "colored_labels" scope Type: `string` Allowed values: "account", "project_line", "project", "related" supported_file_types Type: `array` Array item shape Type: `string` linked_custom_table CustomObjectDefinition Type: `object` id Type: `integer` name Type: `string` key Type: `string` created_at Type: `string` (date-time) updated_at Type: `string` (date-time) project_scope Type: `string` Allowed values: "account", "project" scoring_system ScoringSystem Type: `object` id Type: `integer` name Type: `string` created_at Type: `string` (date-time) updated_at Type: `string` (date-time)

Response fields

Choose which fields to include in the response. Expand a field for examples and associated fields. Collections can only be returned on the top-level resource, not inside an associated resource.

Default response fields are returned until you select specific fields.

Search fields

Field	Type	Returned by default
Unique record ID.	integer	Yes
Include id in response
Name of the record.	string	Yes
Include name in response
Trigger kind of the automation.	string	No
Include trigger_kind in response Allowed values: `field_changedrecord_createddelayed_field_changed`
What record type the automation is for.	string	No
Include trigger_record_type in response Allowed values: `featurereleaserelease_phaseepicrequirementideainitiativegoalkey_resulttaskapprovalwork_requestdocument`
The field that will cause the automation to trigger for field_changed automations.	string	No
Include trigger_field in response Allowed values: `namestatusteam_statustypeinitiativeassigned_to_usercreated_by_userepicend_datestart_datetagsgoalskey_resultsscorereleasewatchersteamiterationrecord_riskprogressinitial_estimatedetailed_estimaterecord_linkscustom_fieldownerrelease_datedevelopment_started_onexternal_release_dateinitiativesroll_up_initiativetime_framerollup_goalstarget_metricstarting_metriccurrent_metricduplicate_ideacategoriesvisibilitynum_endorsementsnum_organizationssubmitted_idea_portalparentcollectionstask_statusdue_dateapproval_groupsassignees`
Custom field definition ID associated with the automation if trigger_field is custom_field.	CustomFieldDefinition	No
Include custom_field_definition in response Expand this association to browse its response fields.
Custom table ID associated with the automation if trigger_record_type is custom_table.	CustomObjectDefinition	No
Include custom_table in response Expand this association to browse its response fields.
Values that will be used to compare against the trigger field to determine if the automation should trigger.	array	No
Include values in response
The operation to use to determine if the automation should trigger.	string	No
Include change_type in response Allowed values: `specificany=addremove><currentpresentblankpresent_with_commentparking_lotnon_parking_lot`
Additional field information when using the record_links trigger_field.	string	No
Include link_filter_type in response Allowed values: `link_typelinked_recordlinked_record_status`
The worksheet row of a worksheet custom field if applicable.	string	No
Include field_worksheet_row in response
Whether the automation is enabled.	boolean	No
Include enabled in response
Run count of the automation.	integer	No
Include run_count in response
Date and time when the record was created.	date-time	No
Include created_at in response
Date and time when the record was last updated.	date-time	No
Include updated_at in response
Workspace on which the automation runs.	AutomationTarget	No
Include automatable in response Expand this association to browse its response fields.
A list of additional conditions that must be met for the automation to trigger. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=trigger_conditions[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include trigger_conditions in response Expand this association to browse its response fields.
Logs associated with the automation. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=logs[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include logs in response Expand this association to browse its response fields.

Search matches the start of a field path and includes matching associations’ subfields. Use a dotted path to search within a specific association.

Response field selection

Create and update responses also include fields submitted in the record body. Submitted association IDs return their associated response fields.

Return selected fields with a comma-separated fields parameter, or add a field to the defaults with fields=default,{field}. Expand an association above for its supported subfields and selection examples.

See field selection for details.

Response statuses

Error shape for 400, 401, 403, 404, 409

Type: object

error

Type: object

Required properties: status, code, message, request_id.

status

Type: integer

code

Type: string

message

Type: string

request_id

Type: string

Error shape for 422

Type: object

error

Type: object

Required properties: status, code, message, details, request_id.

status

Type: integer

Allowed values: 422

code

Type: string

Allowed values: "record.validation_failed", "record.cannot_delete"

message

Type: string

details

Type: array

Array item shape

Type: object

field

Type: string

message

Type: string

code

Type: string

request_id

Type: string

Response envelope and pagination

record: a single record. Fields are documented above.

Download the complete OpenAPI specification