API v1 changelog
Changes to the Artemis API v1, newest first. Review this page before updating an integration. For v2, see the API v2 changelog.
2026-11-13
Changed
POST /external/v1/projectsnow requiresaddress.state. A request without it returns a validation error onaddress.state. Before, it was accepted by validation and then failed later with an error, so no project was ever created without a state.
Effective when this release is deployed. Send address.state on every project
create, such as CA for California.
-
POST /projects/{id}/prepaids/active/estimateprices Participate Energy with PE's Design API v2 and returns onlyestimateSnapshot. ItsparticipateEnergyblock is{ version: 2, homeowner }, wherehomeownerholds the system price PE discounts from (adjustedEpc), the lease discount (leaseDiscountPercent,leaseDiscount),netAmountDueand the lease sales tax (salesTax.rate,salesTax.amount). PE is offered only for an installer connected to PE, on a cash solar project or one financed with a Sungage Prepaid TPO loan (below), without roofing, other home improvement or the legacyParticipate Discountadder. Errors carry acode:422PE_NOT_OFFERED(withdetails.reason) for a project PE can't price, whichGET /projects/{id}/prepaidsalso marks withunavailableReason;422PE_NOT_CONNECTEDwhen the installer's PE connection can't price;422PE_NOT_ELIGIBLEwith PE's failed checks indetails.checks; and502with PE's own code when a PE call fails. -
POST /projects/{id}/prepaids/active/estimatealso prices Participate Energy with a Sungage Prepaid TPO loan, when PE is attached to the project's Sungage lender. Without thepricing:sungagescope on the installer's PE connection, PE is listed withunavailableReasonmissing-scope. PE prices the project's loan as its assigned sales rep, andparticipateEnergy.homeowneraddsloanAmount, what Sungage lends; the discount, Net Amount Due and lease sales tax then come from the loan. The Sungage estimate for that loan financesloanAmount, and answers422PE_SUNGAGE_QUOTE_REQUIREDuntil PE has quoted the loan at the project's current price with no down payment. New error codes:422PE_SUNGAGE_LOAN_REQUIRED,PE_SUNGAGE_DOWN_PAYMENT,PE_SALES_REP_REQUIRED,PE_SUNGAGE_FEE_MISMATCH,PE_SUNGAGE_PRICING_CHECKS_FAILED,PE_SCOPE_NOT_GRANTED(withdetails.scope), and PE'sSUNGAGE_NOT_ENROLLED,ACTOR_NOT_ON_ROSTER,SUNGAGE_USER_NOT_REGISTEREDandSUNGAGE_PRODUCT_UNAVAILABLE(withdetails.installerNameanddetails.repEmail);503SUNGAGE_UNAVAILABLE, which you can retry.unavailableReasonaddssungage-roofing.
The estimate response no longer includes sourceHash, netAmountDue,
energyCommunityEligible or domesticContent, effective when this release is
deployed. Read the Net Amount Due and the lease sales tax from
estimateSnapshot.participateEnergy.homeowner.netAmountDue and
estimateSnapshot.participateEnergy.homeowner.salesTax instead.
Removed
The Participate Energy operations POST /projects/{id}/prepaids/active/submit,
/refresh, and /update were removed on 2026-11-13 and now return 404.
Participate Energy retired the project API they called, so there is no
replacement. Stop calling them.
POST /projects/{id}/prepaids/active/submit,/refresh, and/update, announced on 2026-09-29.POST /projects/{id}/prepaids/active/estimatestays; its new response is under Changed above.
2026-11-06
Added
- Project creation, update, and retrieval by ID responses and
v1 project-updated webhook payloads include
financeReporting. It classifies the current selected composition as Cash, Loan, TPO, Prepaid TPO, Mixed, or Unknown, with customer funding, prepaid provider, product identities, stored amounts, and explicit data issues. Prepaid with associated Cash or Loan remains Prepaid TPO; independent financing legs with different known types become Mixed. This is current selection data, not a record of the financier at signing. ExistingpaymentOptionvalues remain unchanged. No migration is required.
Fixed
GET /external/v1/projects/{id}and v1 project-updated webhook payloads retain the active financier representation for Prepaid + Cash. Native prepaid selections without an active financier row expose their provider infinanceReporting.prepaid; the existingfinancierfield remains null.- A financed project missing its selected financier no longer fails the project-detail response at the financier access. Reporting returns Unknown with an explicit issue.
2026-11-05
Added
- Project details and project webhooks include priced battery expansion packs in
equipmentBreakdown.batteryExpansionsfor Standard and Margin pricing. Match a line toequipmentsby itsid. EachtotalPricecovers the full quantity and is already included inbattery.totalPriceandtotalEquipmentPrice, so do not add it again. The field is omitted when the project has no priced pack and for other pricing methods.
Fixed
- On Margin pricing,
equipmentBreakdown.battery.totalEquipmentPriceandunitPricenow leave out expansion packs at their Margin price. They used to subtract the pack's catalog tier price, which is not what the pack costs under Margin pricing.battery.totalPricedoes not change.
2026-10-30
Changed
POST /external/v1/users,PUT /external/v1/users/{id},POST /external/v1/invitesandPOST /external/v1/installer-onboardingreturn403with codeinternal_email_reservedwhen they would give a user an@monalee.coor@monalee.comaddress. Those addresses are reserved for Monalee staff. A user who already has one keeps it, and you can still invite one that has an account.PUT /external/v1/users/{id}returns403when it changes the email of a user who also belongs to another organization. That email is their login everywhere, so only the user can change it.POST /external/v1/usersfor a member your organization removed earlier now reactivates them without changing their existing account. The request'spassword,firstName,lastNameandphoneNumberare ignored for that account, because it is also their login in other organizations.
Effective when this release is deployed. To correct the email of a user who belongs to several organizations, ask the user to change it in their Artemis profile.
2026-10-29
Changed
- When AutoDesign is at capacity during project creation, Artemis now retries
it up to twice within the 120-second request budget. If it is still busy,
the request returns a retryable
503saying the service is busy instead of a500.
2026-10-27
Changed
- For Sungage financing,
financier.nameinGET /external/v1/projects/{id}and the project webhooks now carries the loan product, such asClassicDPP-36,Escalator-2.9orInstallment, instead ofnull.GET /external/v1/projects/{id}/financiersreturns the same value innameinstead of the bare product type (ClassicDPP).financingProductIdis unchanged. - Legacy
PUT /projects/{id}andPATCH /projects/{id}/designignoreactivePanelsCount. Artemis counts a project's active panels itself. A request that still sends the field succeeds and the value is dropped.
Effective when this release is deployed, PUT /projects/{id} with
activePanelsCount: 0 and solarPanelTypeId: null no longer turns off every
panel. Send removeSolarPanel: true to remove a project's panels.
2026-10-26
Added
POST /external/v1/utility-bill/analyzeresponses includedata.serviceAddress, the service address printed on the bill (street,city,state,zip,country, each nullable). It isnullwhen the bill shows no address.
Changed
- Legacy
POST /leads/{id}/cloneno longer requiresprojectName. Without it, the clone gets the next number in the customer's sequence, such asProject 2forProject 1orRoof mount 2forRoof mount. AprojectNameyou send is still used as is.
2026-10-23
Changed
GET /external/v1/projects/{id}/exports/job-nimbusnow prefixes an address that starts with=,+,-, or@with an apostrophe ('), so spreadsheets show it as text instead of running it as a formula. Other addresses and all measurement columns are unchanged.GETandPUT /external/v1/projects/{id},GET /external/v1/projects/{id}/financiers,POST /external/v1/projects/{id}/{financierType}/applications, and the legacy/leads/{id},/leads/{id}/clone, and/leads/{id}/{financierType}/applicationsroutes now return403when the API key's user cannot access that project. A user whose role only views their own or their team's projects can no longer read or change other projects in the organization. See Projects.PUT /external/v1/projects/{id}andPUT /leads/{id}now check the same per-field permissions as the Artemis app, including the lock on equipment, utility, and financing changes after Contract Signed. A request that touches a field the user cannot edit returns403and saves nothing.- The legacy
/leads/{id}routes now require the same permissions as/external/v1/projects/{id}: a project view permission forGET,project:clonefor clone, andproject:submit_applicationfor applications. ?authToken=signs in only when Artemis loads inside an iframe or on the/impersonatepopup. A top-level link with?authToken=no longer signs in: Artemis removes the parameter and keeps the visitor's current session, or shows the login page. The/impersonatepopup now shows which account the token belongs to before Enable Authentication. See Iframe Integration.POST /external/v1/users,PUT /external/v1/users/{id}, andPOST /external/v1/invitesreturn403when a key attributed to a user who is not an organization admin assigns an admin role the user does not already hold. Sending a user's current roles unchanged still works. Keys with no attributed user are unchanged.
Effective when this release is deployed, integrations that open Artemis in a
new tab or window with ?authToken= must load that URL in an iframe, or use
the /impersonate popup on Safari.
Effective when this release is deployed. To assign an admin role, use a key attributed to an organization admin.
Effective when this release is deployed. If an integration needs every project
in the organization, attribute its API key to a user whose role has
project:view_all and the edit permissions it uses. Legacy API keys without
an attributed user keep their current access.
Fixed
assignedSalesRepEmailonPOST /external/v1/projectsandPUT /external/v1/projects/{id}(and the/leadsequivalents) now only matches members of your organization. Any other email returns404with "Sales rep doesn't exist."
2026-10-22
Added
- Project responses from
GET,POSTandPUT/external/v1/projectsand the project webhooks now includeutilityCompanyId: the utility company ID sent asutilityCompanyExternalIdwhen the project was created, ornullwhen none was stored.
Fixed
POST /projectsnow storesutilityRatePreSolarandutilityRatePostSolarwhen sent. They were accepted but replaced by a recalculated rate. AutilityPreSolarorutilityPostSolarsnapshot still takes precedence. When an installer default rate schedule replaces the tariff you sent, the rate is still calculated from that default. Omit a rate to have it calculated as before.
On deployment, POST /projects returns 400 with PROJECT_INPUT_INVALID when
utilityRatePreSolar or utilityRatePostSolar is negative. Send a rate of 0 or
more, or omit it.
2026-10-21
Fixed
GET /external/v1/projects/{id}and the project-updated webhook now include battery expansions inequipments, withequipmentType: battery-expansion, the catalog name, model number, and quantity, listed after home-improvement items. They were previously left out. The expansion price stays included inbattery.adder; do not add it again.
2026-10-20
Fixed
- Legacy
/leads/{id}routes now return404whenidis not a single project UUID, such as two UUIDs joined by a comma, matching/external/v1/projects/{id}.GETandPUTpreviously returned500; the clone and application routes previously returned400. Rejected requests save no changes; send one project ID per request.
2026-10-19
Fixed
- Project creation now enforces configured project
limits on active subscriptions.
POST /external/v1/projectsreturns403withcode: PROJECT_LIMIT_REACHEDwhen the organization has no remaining project capacity. Concurrent requests cannot consume the same remaining slot. Dedicated project cloning remains exempt from the creation check.
On deployment of this hotfix, integrations must handle 403 with
PROJECT_LIMIT_REACHED and stop retrying until project capacity is available.
Subscriptions without a configured project limit remain unlimited.
2026-10-15
Added
GET /external/v1/projects/{id}/exports/job-nimbusdownloads the project's saved roof measurements as a Job Nimbus CSV, using the same generator as the Export Center. Requires project access,project:download_proposal, an active roofing subscription, and roof or gutter equipment. No migration is required.
Changed
- The organization budget shared by API v1 and v2 is now 100 requests per minute. The additional v1 project-detail limit remains 20 reads per minute. See Rate Limits & Idempotency.
2026-10-08
Changed
With the v2 launch, new webhook subscriptions must use V2. Existing V1
subscriptions continue delivering events and can still be edited and tested.
In the legacy subscription-creation flow, requests with contractVersion: 1
or no contractVersion return HTTP 400 with code
WEBHOOK_V1_CREATION_DISABLED; set contractVersion: 2 explicitly.
POST /external/v2/webhook-subscriptions selects V2 automatically and does
not require this field.
To create a new subscription, configure a V2 receiver using the
Webhooks guide.
2026-10-07
Deprecated
API v1 deprecation is announced on October 7, 2026. Use API v2 for new integrations and plan migration of existing v1 integrations. Compare operation coverage in API Reference v2 and follow the v2 Quickstart. This notice does not set a removal date.
Fixed
- Project updates now save stage, status, timestamp,
and history together. Requests blocked by the current stage's required checklist
return
422withcode: INCOMPLETE_STAGE_CHECKLISTanddetails.missingRequiredItemscontaining item IDs and names. Rejected updates save no changes. Duplicate and same-stage requests remain successful no-ops. - Concurrent stage changes through API v1 and legacy
PUT /leads/{id}now return409withcode: PROJECT_STAGE_CONFLICTwhen another update wins. Reload the project and retry; the rejected request saves no changes.
On deployment of this release, integrations must handle 422, complete the
listed checklist items, and retry the update. Legacy PUT /leads/{id} updates
also require project:edit_details for attributed API keys, matching API v1.
Changed
- Automatic roof previews now generate one principal image followed by four
colour variants using that same image, improving scene consistency without
cropping a grid. Each preview becomes ready independently; keep polling
GET /projects/{projectId}/roof-previewswhile any previews are pending. Response fields are unchanged. - The roof-preview prompt version has changed. Existing version-based cache filtering applies: older previews are excluded from the list, which can return catalogue defaults until new previews are generated in Artemis. Reading the API does not regenerate previews.
2026-10-02
Added
- AI roof previews can now be read through the API, on both v1 and v2:
GET /projects/{projectId}/roof-previewslists the project's previews in creation order, with the catalogue preview image for each colour as a fallback, andGET /projects/{projectId}/roof-previews/{renderId}returns one preview with its status and image. Previews are generated in Artemis; the API does not generate them.
2026-09-30
Changed
- Financing applications submitted through API v1 now accept either the last four or all nine SSN digits for GoodLeap, Dividend, and EnFin. Other lenders continue to require all nine digits. The same rule applies to primary and co-applicants.
2026-09-29
Added
- Organizations enabled for prepaid TPO can select Participate Energy as a prepaid
provider on eligible solar projects. The project prepaid API now offers
POST /projects/{id}/prepaids/active/estimate,/submit,/refresh, and/updatefor that provider. Estimates save the contribution used to reduce a paired Sungage Prepaid TPO loan before its dealer fee; submission requires the current estimate's preview token. These operations are available only to authorized callers with the prepaid TPO feature enabled.
2026-09-23
Added
- V1
design-help-startedanddesign-help-endedwebhooks now includedata.projectIdso integrations can associate the event with a project. The existingdata.idfield is unchanged. See the webhook guide.
Changed
- API keys created in Settings can now expire or be revoked. Expired and revoked keys are rejected immediately by both API v1 and API v2. Existing keys remain active with no expiration unless they are explicitly revoked.
2026-09-15
Added
- Added
design-help-startedanddesign-help-endedwebhook events for v1 and v2 subscriptions. Started fires when a designer claims the work, including a new claim after reopen. Ended fires when the reviewed result is submitted. Cancellation, reopen itself, and repeated no-op transitions do not emit an event. Both payload versions identify the project; see the webhook guide.
2026-09-10
Fixed
- Project creation now continues when utility-rate calculations return no data or the rate provider fails. Submitted bill or consumption values are retained; unavailable rates remain null and savings calculations wait for usable rates. Integrations must treat null rates as unavailable, not as zero.
- Lead consumption updates now save even when the rate lookup fails, preserving the existing bill and payment history. A later successful update can restore missing rates. Missing data and rejected provider inputs are reported as warnings; provider outages continue to be reported as errors.
2026-09-08
Changed
- Automation rules using the is not operator on an equipment-model condition (solar
panel, inverter, battery, battery expansion, or EV charger) now also match projects that
carry no equipment in that category. Previously such a rule never matched a project
without that equipment, so "battery model is not X" skipped every battery-less project.
Projects created or updated through
POST /external/v1/projects,PUT /external/v1/projects/{project_id}, or the project equipment operations may now receive an additional automatic entry inupgrades, which also changesaddersTotalPrice,grossSystemPrice, andfinalSystemPrice. Only organizations with such a rule enabled are affected. Review your enabled automation rules that use is not on an equipment model before this release and disable any that should not apply to projects lacking that equipment.
2026-08-27
Fixed
POST /external/v1/usersnow returns409withcode: email_in_usewhen the email belongs to an existing global user, instead of returning500. Use the existing-user/membership flow to add the account; this endpoint will not attach it to another organization.
2026-08-18
Added
- Added external API documentation for custom property definitions and project custom-property values, including:
/external/v1/custom-properties,/external/v1/custom-properties/{id}, and/external/v1/projects/{project_id}/custom-properties. - Added permission metadata to the OpenAPI document for external project, comment, financing, custom property, user, role, team, installer, pricing, invite, tag, homeowner, and property operations.
Changed
- Documented additional project-creation fields for panel, inverter, and battery model numbers, payment option, duplicate-homeowner handling, energy-audit details, and external pricing.
- Documented optional project address and homeowner fields, including optional state and last name where supported.
2026-08-04
Added
- Added obstacles to each structure in external project responses, including geometry, dimensions, classification, status, and roofing-square behavior.
2026-07-30
Fixed
- Improved external project creation for large properties and parcel-radius inference.
AutoDesign timeouts now return a retryable
504response, and API clients should allow at least 120 seconds for project-creation requests.
2026-07-27
Added
- Added
POST /external/v1/projects/{project_id}/design-helpso integrations can request a roof-plane review when AutoDesign returns low or medium confidence.
2026-07-24
Added
- Added the
proposal-sentwebhook event. Its payload includesproposalSentTo, the proposal recipient.
2026-07-23
Added
- Added
projectRadiusMandinferProjectRadiusMto external project creation. Responses now include the resolved parcel radius.

