Versioning

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 every 1-2 years), 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.

Backwards-compatible changes

Aurora defines the following types of changes as backwards compatible:

  • Adding new API resources
  • Adding new optional request parameters to existing API methods
  • Adding new properties to existing API responses
  • Changing the order of properties in existing API responses
  • Changing the length or format of opaque strings such as object IDs, error messages and other human-readable strings
  • Webhook parameters. Webhook listeners should gracefully handle unfamiliar enum values
  • Adding new values to enumerations such as a new component_type in the bill of materials

Additionally, we recommend avoiding assumptions about anything not specified in our documentation. For example, endpoints that return arrays do not guarantee order unless explicitly stated in the documentation.

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. You can do so in the Aurora app or use the Upgrade API.

To upgrade your version in the Aurora app, navigate to the API Tokens page in Settings, then select the upgrade button, as shown below. You can upgrade each of your API keys independently.

Upgrading your API version will affect the parameters you can send and the structure of objects returned for the API calls.

Testing a new API version

To test a newer version for API calls, use the sandbox environment and set the Aurora-API-Version header. Once your integration is working in sandbox, you can upgrade your production version as shown above. Please note the Aurora-API-Version header will not work in production.

Rolling back your API version

For 120 hours after you have upgraded your API version, you can safely roll back to the version that you were upgrading from using the Rollback API, or by selecting rollback from the dropdown menu on your key.

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:

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.

2024.05

  • Removed Aurora-API-Version header from production. The header is still available for use in sandbox for testing. To upgrade your production version, please use versioning API or visit the settings page in the Aurora app.
  • Remove user_ids field from Retrieve Tenant endpoint
  • Changed preferred_solar_panels to preferred_solar_modules in Create Project and Update Project
  • Changed customer_address to mailing_address in Project APIs
  • Changed address to property_address and added property_address, longitude, and latitude to the location object in Project APIs
  • Removed updated_at from Project and Agreement endpoints
  • Added Nearmap (True Ortho) as option for image_src in Design Request endpoints
  • Changed NearMap to Nearmap in Retreive Design Request endpoint
  • Removed manufacturer field from Retrieve Design Summary arrays when redundant with bill_of_materials items
  • Changed panels to modules in Retrieve Roof Summary
  • Changed max_panel_spacing to max_module_spacing, and increased default value from 1cm to 2.6cm in List Racking Arrays
  • Updated url path for Retrieve Design Asset from /tenants/{tenant_id}/assets/{id} to /tenants/{tenant_id}/designs/{design_id}/assets/{id}
  • Changed several fields in Retrieve Design Pricing and Update Design Pricing:
    • Changed all references to cost to price
    • Changed pricing_mode to pricing_method
    • Change line_items to pricing_by_component
    • Changed adders_without_discounts to adders and adders to discounts in system_price_breakdown and storage_system_price_breakdown
  • Changed system_cost to system_price and inverter_cost_per_watt to inverter_price_per_watt in Retrieve Financing API
  • Removed support for string values in the enabled field from Create Webhook and Update Webhook
  • Updated webhook filters to use a list of objects with static keys url_parameter and value instead of an object with each url_parameter as a key.

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 with role_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. Use system_size_ac ,system_size_ptc or system_size_stc instead.
  • Reduced fields returned by List Financing to id, name, selected_in_sales_mode, and financing option. The rest of the fields are available via Retrieve Financing.
  • Removed site_model_design_id and include_design query parameters from Create Design. Use the new Duplicate Design endpoint instead.
  • For Run AutoDesigner:
    • Removed _meters suffix from the following input fields row_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. Use filler_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     
}