Update epic

PUT /api/v3/epics/{id}

Request

Response

URL

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

JSON body

{
  "record": {}
}

cURL command

curl --request PUT 'https://example.aha.io/api/v3/epics/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 or reference number of the epic

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`
Start date of the record.	date	`start_date`
Include start_date in request Accepted value shape and constraints Type: `string` (date)
End date of the record.	date	`end_date`
Include end_date in request Accepted value shape and constraints Type: `string` (date)
Progress completed for the record.	number	`progress`
Include progress in request Accepted value shape and constraints Type: `number`
Score assigned to the record.	number	`score`
Include score in request Accepted value shape and constraints Type: `number`
Initial work estimate for the record.	number	`initial_estimate`
Include initial_estimate in request Accepted value shape and constraints Type: `number`
Detailed work estimate for the record.	number	`detailed_estimate`
Include detailed_estimate in request Accepted value shape and constraints Type: `number`
Remaining work estimate for the record.	number	`remaining_estimate`
Include remaining_estimate in request Accepted value shape and constraints Type: `number`
Work completed for the record.	number	`work_done`
Include work_done in request Accepted value shape and constraints Type: `number`
Position of the record relative to its siblings.	integer	`position`
Include position in request Accepted value shape and constraints Type: `integer`
How progress is calculated for the record.	string	`progress_source`
Include progress_source in request Accepted value shape and constraints Type: `string` Allowed values: "manual", "from_features", "from_features_with_dependents", "from_remaining_estimate", "from_remaining_estimate_with_dependents", "from_todos", "from_todos_with_dependents", "from_features_completed", "from_features_completed_with_dependents" Allowed values: `manualfrom_featuresfrom_features_with_dependentsfrom_remaining_estimatefrom_remaining_estimate_with_dependentsfrom_todosfrom_todos_with_dependentsfrom_features_completedfrom_features_completed_with_dependents`
How start and end dates are calculated for the record.	string	`duration_source`
Include duration_source in request Accepted value shape and constraints Type: `string` Allowed values: "manual", "from_features", "from_releases" Allowed values: `manualfrom_featuresfrom_releases`
Whether estimates are entered on the record or calculated from its features.	string	`estimate_source`
Include estimate_source in request Accepted value shape and constraints Type: `string` Allowed values: "manual", "from_features" Allowed values: `manualfrom_features`
ID of the status assigned to the record.	string	`status`
Include status_id in request Accepted value shape and constraints Type: `string` Submit `status_id`; the response includes `status`.
ID of the user assigned to the record.	string	`assigned_to_user`
Include assigned_to_user_id in request Accepted value shape and constraints Type: `string` Submit `assigned_to_user_id`; the response includes `assigned_to_user`.
ID of the user who created the record.	string	`created_by_user`
Include created_by_user_id in request Accepted value shape and constraints Type: `string` Submit `created_by_user_id`; the response includes `created_by_user`.
HTML description of the record.	string	`description`
Include description in request Accepted value shape and constraints Type: `string`
ID of the release associated with the record.	string	`release`
Include release_id in request Accepted value shape and constraints Type: `string` Submit `release_id`; the response includes `release`.
ID of the release phase associated with the record.	string	`release_phase`
Include release_phase_id in request Accepted value shape and constraints Type: `string` Submit `release_phase_id`; the response includes `release_phase`.
ID of the iteration associated with the record.	string	`iteration`
Include iteration_id in request Accepted value shape and constraints Type: `string` Submit `iteration_id`; the response includes `iteration`.
ID of the initiative associated with the record.	string	`initiative`
Include initiative_id in request Accepted value shape and constraints Type: `string` Submit `initiative_id`; the response includes `initiative`.
ID of the team assigned to the record. Availability depends on account settings.	string	`team`
Include team_id in request Accepted value shape and constraints Type: `string` Submit `team_id`; the response includes `team`.
ID of the team status assigned to the record. Availability depends on account settings.	string	`team_status`
Include team_status_id in request Accepted value shape and constraints Type: `string` Submit `team_status_id`; the response includes `team_status`.
ID of the program increment associated with the record.	string	`program_increment`
Include program_increment_id in request Accepted value shape and constraints Type: `string` Submit `program_increment_id`; the response includes `program_increment`.
ID of the time code assigned to the record. only available when timesheets are enabled for the account. Availability depends on account settings.	string	`time_code`
Include time_code_id in request Accepted value shape and constraints Type: `string` Submit `time_code_id`; the response includes `time_code`.
Tags associated with the epic. Items are merged into the existing collection: each item adds a record, or removes it with `_destroy: true`. Records not listed are left unchanged, and an empty array changes nothing.	array	`tags`
Include tags in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` id Type: `string` name Type: `string` _destroy Type: `boolean`
Goals associated with the epic. Items are merged into the existing collection: each item adds a record, or removes it with `_destroy: true`. Records not listed are left unchanged, and an empty array changes nothing.	array	`goals`
Include goals in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` id Type: `string` reference_num Type: `string` _destroy Type: `boolean`
Key results associated with the epic. Only available when key results are enabled for the account. Items are merged into the existing collection: each item adds a record, or removes it with `_destroy: true`. Records not listed are left unchanged, and an empty array changes nothing. Availability depends on account settings.	array	`key_results`
Include key_results in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` id Type: `string` reference_num Type: `string` _destroy Type: `boolean`
Individual metric values for the epic's scorecards. Items are merged into the existing collection: each item adds a record, or removes it with `_destroy: true`. Records not listed are left unchanged, and an empty array changes nothing.	array	`score_facts`
Include score_facts in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` scoring_system_metric_id Type: `string` value Type: `number` _destroy Type: `boolean`
Custom field values to set. Property names are custom field definition keys, and each value is one of the supported input formats below, depending on the field type. Attachment fields are read-only and can't be set.	object	`custom_fields`
Include custom_fields in request Accepted value shape and constraints Type: `object` Custom property values Type: `one of the shapes below` Supported shape 1 Text field Type: `string` Supported shape 2 Note field Type: `string` Supported shape 3 URL field Type: `string` (uri) Supported shape 4 Number field Type: `string` Supported shape 5 Date field Type: `string` (date) Supported shape 6 Checkbox field Type: `boolean` Supported shape 7 Single select field Type: `object` Minimum properties: 1 id Type: `string` name Type: `string` Supported shape 8 Conditional choice field Type: `object` Required properties: id. id Type: `string` Supported shape 9 Multi-select field Type: `array` Array item shape Type: `object` id Type: `string` name Type: `string` _destroy Type: `boolean` Supported shape 10 Records field Type: `array` Array item shape Type: `object` id Type: `string` _destroy Type: `boolean` Supported shape 11 Single custom table link Type: `object` Required properties: id. id Type: `string` Supported shape 12 Custom table links Type: `array` Array item shape Type: `object` id Type: `string` _destroy Type: `boolean` Supported shape 13 Worksheet field Type: `array` Array item shape Type: `object` Required properties: id, value. id Type: `string` value Type: `string or number or boolean or null` Supported shape 14 Scorecard field Type: `object` Minimum properties: 1 score Type: `number or null` score_facts Type: `array` Array item shape Type: `object` scoring_system_metric_id Type: `string` value Type: `number` _destroy Type: `boolean` Supported shape 15 Clear value Type: `null` Use your account’s custom field API keys and values matching each field’s type.
Users watching the record for update notifications. Items are merged into the existing collection: each item adds a record, or removes it with `_destroy: true`. Records not listed are left unchanged, and an empty array changes nothing.	array	`watchers`
Include watchers in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` id Type: `string` _destroy Type: `boolean`

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
URL to view the record in Aha!	string	Yes
Include html_url in response
API URL for the record.	string	Yes
Include url in response
Name of the record.	string	Yes
Include name in response
Reference number of the record.	string	Yes
Include reference_num 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
Start date of the record.	date	No
Include start_date in response
End date of the record.	date	No
Include end_date in response
Progress completed for the record.	number	No
Include progress in response
Score assigned to the record.	number	No
Include score in response
Initial work estimate for the record.	number	No
Include initial_estimate in response
Detailed work estimate for the record.	number	No
Include detailed_estimate in response
Remaining work estimate for the record.	number	No
Include remaining_estimate in response
Work completed for the record.	number	No
Include work_done in response
Position of the record relative to its siblings.	integer	No
Include position in response
How progress is calculated for the record.	string	No
Include progress_source in response Allowed values: `manualfrom_featuresfrom_features_with_dependentsfrom_remaining_estimatefrom_remaining_estimate_with_dependentsfrom_todosfrom_todos_with_dependentsfrom_features_completedfrom_features_completed_with_dependents`
How start and end dates are calculated for the record.	string	No
Include duration_source in response Allowed values: `manualfrom_featuresfrom_releases`
Whether estimates are entered on the record or calculated from its features.	string	No
Include estimate_source in response Allowed values: `manualfrom_features`
Status assigned to the record.	Status	No
Include status in response Expand this association to browse its response fields.
User assigned to the record.	AssignedToUser	No
Include assigned_to_user in response Expand this association to browse its response fields.
User who created the record.	User	No
Include created_by_user in response Expand this association to browse its response fields.
HTML description of the record.	Note	No
Include description in response Expand this association to browse its response fields.
Workspace that contains the record.	Project	No
Include project in response Expand this association to browse its response fields.
Release associated with the record.	Release	No
Include release in response Expand this association to browse its response fields.
Release phase associated with the record.	ReleasePhase	No
Include release_phase in response Expand this association to browse its response fields.
Iteration associated with the record.	Iteration	No
Include iteration in response Expand this association to browse its response fields.
Initiative associated with the record.	Initiative	No
Include initiative in response Expand this association to browse its response fields.
Team assigned to the record. Availability depends on account settings.	Project	No
Include team in response Expand this association to browse its response fields.
Team status assigned to the record. Availability depends on account settings.	Status	No
Include team_status in response Expand this association to browse its response fields.
Program increment associated with the record.	ProgramIncrement	No
Include program_increment in response Expand this association to browse its response fields.
Time code assigned to the record. Only available when timesheets are enabled for the account. Availability depends on account settings.	TimeCode	No
Include time_code in response Expand this association to browse its response fields.
Tags associated with the epic. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=tags[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 tags in response Expand this association to browse its response fields.
Features associated with the epic. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=features[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 features in response Expand this association to browse its response fields.
Goals associated with the epic. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=goals[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 goals in response Expand this association to browse its response fields.
Key results associated with the epic. Only available when key results are enabled for the account. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=key_results[default]). Capped at 25 records. Only available on the top-level resource. Availability depends on account settings.	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 key_results in response Expand this association to browse its response fields.
Individual metric values for the epic's scorecards. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=score_facts[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 score_facts in response Expand this association to browse its response fields.
Custom field values. Property names are custom field definition keys, and each value is one of the supported formats below, depending on the field type. Omitted unless requested with the fields parameter or submitted in the request. Fields with no stored value are omitted.	object	No
Include custom_fields in responseCustom field API key Custom field keys depend on your account. Request `fields=custom_fields` or `fields=custom_fields.your_key`.
Users watching the record for update notifications. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=watchers[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 watchers 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