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/projects now requires address.state. A request without it returns a validation error on address.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/estimate prices Participate Energy with PE's Design API v2 and returns only estimateSnapshot. Its participateEnergy block is { version: 2, homeowner }, where homeowner holds the system price PE discounts from (adjustedEpc), the lease discount (leaseDiscountPercent, leaseDiscount), netAmountDue and 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 legacy Participate Discount adder. Errors carry a code: 422 PE_NOT_OFFERED (with details.reason) for a project PE can't price, which GET /projects/{id}/prepaids also marks with unavailableReason; 422 PE_NOT_CONNECTED when the installer's PE connection can't price; 422 PE_NOT_ELIGIBLE with PE's failed checks in details.checks; and 502 with PE's own code when a PE call fails.

  • POST /projects/{id}/prepaids/active/estimate also prices Participate Energy with a Sungage Prepaid TPO loan, when PE is attached to the project's Sungage lender. Without the pricing:sungage scope on the installer's PE connection, PE is listed with unavailableReason missing-scope. PE prices the project's loan as its assigned sales rep, and participateEnergy.homeowner adds loanAmount, what Sungage lends; the discount, Net Amount Due and lease sales tax then come from the loan. The Sungage estimate for that loan finances loanAmount, and answers 422 PE_SUNGAGE_QUOTE_REQUIRED until PE has quoted the loan at the project's current price with no down payment. New error codes: 422 PE_SUNGAGE_LOAN_REQUIRED, PE_SUNGAGE_DOWN_PAYMENT, PE_SALES_REP_REQUIRED, PE_SUNGAGE_FEE_MISMATCH, PE_SUNGAGE_PRICING_CHECKS_FAILED, PE_SCOPE_NOT_GRANTED (with details.scope), and PE's SUNGAGE_NOT_ENROLLED, ACTOR_NOT_ON_ROSTER, SUNGAGE_USER_NOT_REGISTERED and SUNGAGE_PRODUCT_UNAVAILABLE (with details.installerName and details.repEmail); 503 SUNGAGE_UNAVAILABLE, which you can retry. unavailableReason adds sungage-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/estimate stays; 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. Existing paymentOption values 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 in financeReporting.prepaid; the existing financier field 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.batteryExpansions for Standard and Margin pricing. Match a line to equipments by its id. Each totalPrice covers the full quantity and is already included in battery.totalPrice and totalEquipmentPrice, 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.totalEquipmentPrice and unitPrice now 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.totalPrice does not change.

2026-10-30

Changed

  • POST /external/v1/users, PUT /external/v1/users/{id}, POST /external/v1/invites and POST /external/v1/installer-onboarding return 403 with code internal_email_reserved when they would give a user an @monalee.co or @monalee.com address. 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} returns 403 when 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/users for a member your organization removed earlier now reactivates them without changing their existing account. The request's password, firstName, lastName and phoneNumber are 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 503 saying the service is busy instead of a 500.

2026-10-27

Changed

  • For Sungage financing, financier.name in GET /external/v1/projects/{id} and the project webhooks now carries the loan product, such as ClassicDPP-36, Escalator-2.9 or Installment, instead of null. GET /external/v1/projects/{id}/financiers returns the same value in name instead of the bare product type (ClassicDPP). financingProductId is unchanged.
  • Legacy PUT /projects/{id} and PATCH /projects/{id}/design ignore activePanelsCount. 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/analyze responses include data.serviceAddress, the service address printed on the bill (street, city, state, zip, country, each nullable). It is null when the bill shows no address.

Changed

  • Legacy POST /leads/{id}/clone no longer requires projectName. Without it, the clone gets the next number in the customer's sequence, such as Project 2 for Project 1 or Roof mount 2 for Roof mount. A projectName you send is still used as is.

2026-10-23

Changed

  • GET /external/v1/projects/{id}/exports/job-nimbus now 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.
  • GET and PUT /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}/applications routes now return 403 when 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} and PUT /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 returns 403 and saves nothing.
  • The legacy /leads/{id} routes now require the same permissions as /external/v1/projects/{id}: a project view permission for GET, project:clone for clone, and project:submit_application for applications.
  • ?authToken= signs in only when Artemis loads inside an iframe or on the /impersonate popup. 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 /impersonate popup now shows which account the token belongs to before Enable Authentication. See Iframe Integration.
  • POST /external/v1/users, PUT /external/v1/users/{id}, and POST /external/v1/invites return 403 when 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

  • assignedSalesRepEmail on POST /external/v1/projects and PUT /external/v1/projects/{id} (and the /leads equivalents) now only matches members of your organization. Any other email returns 404 with "Sales rep doesn't exist."

2026-10-22

Added

  • Project responses from GET, POST and PUT /external/v1/projects and the project webhooks now include utilityCompanyId: the utility company ID sent as utilityCompanyExternalId when the project was created, or null when none was stored.

Fixed

  • POST /projects now stores utilityRatePreSolar and utilityRatePostSolar when sent. They were accepted but replaced by a recalculated rate. A utilityPreSolar or utilityPostSolar snapshot 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 in equipments, with equipmentType: battery-expansion, the catalog name, model number, and quantity, listed after home-improvement items. They were previously left out. The expansion price stays included in battery.adder; do not add it again.

2026-10-20

Fixed

  • Legacy /leads/{id} routes now return 404 when id is not a single project UUID, such as two UUIDs joined by a comma, matching /external/v1/projects/{id}. GET and PUT previously returned 500; the clone and application routes previously returned 400. 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/projects returns 403 with code: PROJECT_LIMIT_REACHED when 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-nimbus downloads 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 422 with code: INCOMPLETE_STAGE_CHECKLIST and details.missingRequiredItems containing 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 return 409 with code: PROJECT_STAGE_CONFLICT when 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-previews while 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-previews lists the project's previews in creation order, with the catalogue preview image for each colour as a fallback, and GET /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 /update for 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-started and design-help-ended webhooks now include data.projectId so integrations can associate the event with a project. The existing data.id field 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-started and design-help-ended webhook 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 in upgrades, which also changes addersTotalPrice, grossSystemPrice, and finalSystemPrice. 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/users now returns 409 with code: email_in_use when the email belongs to an existing global user, instead of returning 500. 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 504 response, 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-help so integrations can request a roof-plane review when AutoDesign returns low or medium confidence.

2026-07-24

Added

  • Added the proposal-sent webhook event. Its payload includes proposalSentTo, the proposal recipient.

2026-07-23

Added

  • Added projectRadiusM and inferProjectRadiusM to external project creation. Responses now include the resolved parcel radius.