Aurora releases a new API version when we make backward-incompatible changes to the Aurora API. Your Aurora API version controls the API behavior you see and is set the first time you make an API request. When we change the API in a backward-incompatible way (something that you can expect to happen at least once a year), we release a new dated version and support it for a minimum of 12 months. To avoid disrupting your integration and breaking your code, we don’t change your version automatically. It is your responsibility to upgrade when you are ready.
Upgrading your API version
We continually evolve the Aurora API by making non-breaking changes to the current version. If you’re running an older version of the API, upgrade to the current version to take advantage of new functionality and improved performance. When you are confident that your code can handle the current API version, use the Upgrade API. Upgrading your API version will affect the parameters you can send and the structure of objects returned for the API calls. The Upgrade API switches the version used by API calls that don’t have the Aurora-API-Version
header.
Testing a new API version
To test a newer version for API calls, set the Aurora-API-Version
header. You can set the Aurora-API-Version
header to the latest available version only.
Rolling back your API version
For 120 hours after you have upgraded your API version using the Upgrade API, you can safely roll back to the version that you were upgrading from using the Rollback API.
Staying informed
We publish information about non-breaking changes made to the current API version and announcements about new API versions to the API product changelog. Subscribe to RSS updates to be notified about new changelog entries:
- RSS feed (https://docs.aurorasolar.com/changelog.rss)
API versions
The following are all breaking changes to the Aurora API. Each date corresponds with a new version of the Aurora API. If you are looking for all API additions and improvements, see the API product changelog.
2022.09
- Removed
/
(root) API endpoint. - Removed
/v2
from all API resource URLs. For example,/v2/tenants/{tenant_id}/projects/{id}
is now/tenants/{tenant_id}/projects/{id}
. - Removed HMAC authentication. Use bearer token authentication instead.
- Replaced
user_level
withrole_id
and switched from the human-readable user level to role uuid in Create User, Invite User, Retrieve User, and Update User.# in API version 2018.01 "user": { "first_name": "Jessica", "last_name": "Solar", "user_level": "Team Member" } # in API version 2022.09 "user": { "first_name": "Jessica", "last_name": "Solar", "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
- Made messages in
HTTP 4xx
responses use a consistent format:{ "errors": [ {"message": "something went wrong"}, {"message": "something else went wrong"} ] }
- Made
HTTP 404 Not Found
response reference the resource that’s not found. For example,{"error": [{"message": "The project with id 12345343-5343-4345-3445-123456789012 could not be found"}]}
- Removed a previously deprecated
system_size
field from Retrieve Design Summary endpoint. Usesystem_size_ac
,system_size_ptc
orsystem_size_stc
instead. - Reduced fields returned by List Financing to
id,
name
,selected_in_sales_mode
, andfinancing option
. The rest of the fields are available via Retrieve Financing. - Removed
site_model_design_id
andinclude_design
query parameters from Create Design. Use the new Duplicate Design endpoint instead. - For Run AutoDesigner:
- Removed
_meters
suffix from the following input fieldsrow_spacing_meters
,column_spacing_meters
,flat_face_row_spacing_meters
,flat_face_column_spacing_meters
. The unit of measure (meters) is listed in API docs. - Removed a previously deprecated
allow_filler_row
field. Usefiller_row_locations
instead. - Restructured
placement_options
field:# in API version 2018.01 placement_options: { orientations, flat_face_orientations, filler_row_locations, min_sap, min_tsrf, pitched_face_tilt_threshold, column_spacing, row_spacing, min_contiguous_panels, panel_tilt, flat_face_column_spacing_meters, flat_face_row_spacing_meters, flat_face_panel_tilt_deg, azimuth_min_deg, azimuth_max_deg } #in API version 2022.09 placement_options: { pitched_face_tilt_threshold, orientations, column_spacing, row_spacing, panel_tilt } flat_face_placement_options: { flat_face_orientations, flat_face_column_spacing, flat_face_row_spacing, flat_face_panel_tilt } irradiance_constraints: { min_sap, min_tsrf } placement_constraints: { min_contiguous_panels, azimuth_min_deg, azimuth_max_deg, filler_row_locations }
- Removed