Update iteration

PATCH /api/v3/iterations/{id}

Request

Response

URL

PATCH https://example.aha.io/api/v3/iterations/123

JSON body

{
  "record": {}
}

cURL command

curl --request PATCH 'https://example.aha.io/api/v3/iterations/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 iteration

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`
Status of the iteration.	string	`status`
Include status 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)
Duration of the iteration.	integer	`duration`
Include duration in request Accepted value shape and constraints Type: `integer`
Goal of the iteration.	string	`goal`
Include goal in request Accepted value shape and constraints Type: `string`
Progress completed for the record.	number	`progress`
Include progress in request Accepted value shape and constraints Type: `number`
HTML description of the record.	string	`description`
Include description in request Accepted value shape and constraints Type: `string`

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
Status of the iteration.	string	No
Include status 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
Duration of the iteration.	integer	No
Include duration in response
Goal of the iteration.	string	No
Include goal in response
Progress completed for the record.	number	No
Include progress in response
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.
Features associated with the iteration. 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.
Requirements associated with the record. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=requirements[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 requirements 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