API v2 changelog
Changes to Artemis API v2, newest first. Review this page before updating an integration. For v1, see the API v1 changelog.
2026-11-13
Changed
POST /external/v2/projectsnow requiresaddress.state. A request without it returns a validation error onaddress.state. Before, it was accepted by validation and then failed with a 500, 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.
2026-11-12
Added
POST /external/v2/projects/{projectId}/design-helpaccepts optionalurgencyMinutes(30,60,120or240; omit or sendnullfor no rush) and optionalcategories, which defaults to["roof-planes"]. Requests without either field behave as before.GET /external/v2/projects/{projectId}/design-help/{designHelpId}returnsurgencyMinutes, ornullfor no rush. See API Reference v2.
2026-11-04
Added
POST /external/v2/projects/{projectId}/documentsnow documents its accepted file types, whenrequirementIdis required, what a same-name upload does, the413response for files over 10 MB, and a multipartcurlexample. The 10 MB limit also applies to video. The endpoint's behavior did not change. See API Reference v2.
Fixed
- Project document examples show
documentTypein the uppercase form the API returns, such asOTHER.
2026-11-02
Added
- V2
contract-signedwebhooks includedata.contractUrl, a signed link to the executed contract PDF that expires in 24 hours. It is omitted when the signed PDF is not available. Other V2 events have nodata.
2026-10-30
Changed
POST /external/v2/users,PATCH /external/v2/users/{userId},POST /external/v2/invitesandPOST /external/v2/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.PATCH /external/v2/users/{userId}and the MCPupdate_usertool return403when they change 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/v2/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-27
Changed
- For Sungage financing,
nameinGET /external/v2/projects/{projectId}/financiersnow carries the loan product, such asClassicDPP-36,Escalator-2.9orInstallment, instead of the bare product type (ClassicDPP).financingProductIdis unchanged. See API Reference v2. GET /external/v2/projects/{projectId}/designreturns the project's storedsystemSize: active panels × the panel wattage from the project's pricing version, in kW rounded to 2 decimals. It matches the size Artemis shows on the project and in contracts. It stays0when the project has no solar or no active panels. See API Reference v2.
2026-10-26
Added
- A completed utility bill analysis from
GET /external/v2/projects/{projectId}/utility-bill-analyses/{analysisId}includesresult.serviceAddress, the service address printed on the bill (street,city,state,zip,country, each nullable). It isnullwhen the bill shows no address. See API Reference v2.
2026-10-23
Changed
GET /external/v2/projects/{projectId}/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. See API Reference v2.?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/v2/users,PATCH /external/v2/users/{userId},POST /external/v2/invites, and the matching MCP tools return403when the caller is not an organization admin and assigns an admin role the user does not already hold. MCP connections authorized through OAuth never count as an organization admin, so they cannot assign admin roles. Invites previously checked only that the roles belong to the organization, anduser:*holders could assign admin roles to users.PATCH /external/v2/users/{userId}accepts roles the user already holds even when they grant permissions the caller lacks. Only added roles must fit within the caller's permissions, so sending a user's current roles unchanged works.
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 an API key attributed to an organization admin, or assign it in Artemis settings.
2026-10-22
Changed
- MCP tool calls whose arguments hold more than 10,000 array elements and object keys combined return a tool error instead of running.
- MCP requests whose body names protocol version
2026-07-28must also send theMCP-Protocol-Versionheader, as the MCP specification requires. Requests without it get400. Notifications are not checked. - MCP requests with a body over 4 MiB get
413. Other API v2 routes keep their 5 MB limit.
2026-10-21
Changed
- Webhook subscription reads return
authType: "oauth"for webhooks connected with OAuth in Artemis settings. Those deliveries are still HMAC-signed and also carry an OAuth bearer token. They list no custom headers and reject custom-header updates. API-created webhooks remainhmac. See API Reference v2.
2026-10-15
Added
GET /external/v2/projects/{projectId}/exports/job-nimbusdownloads saved roof measurements as a Job Nimbus CSV. Requires project access,project:download_proposal, an active roofing subscription, and roof or gutter equipment. See API Reference v2.
Fixed
- Project listing now accepts
project:view_ownandproject:view_teamand returns only projects the caller can access, including when filtering or paging. - Webhook subscription reads, updates, and deletion now enforce installer access, matching subscription creation. Lists exclude inaccessible installers.
- Custom-property writes reject repeated IDs and values incompatible with their definitions, including invalid numbers, calendar dates, checkbox values, and action options.
Changed
- Get the project design returns a lightweight
summary by default. Add
?include=geometryfor the complete geometry response. The reference includes examples of both modes for the same project.
Effective when this release is deployed, clients using structures,
obstaclesWkt, roofOutlineWkt, combinedRoofOutlineWkt, or parcelOutlineWkt
from GET /external/v2/projects/{projectId}/design must add include=geometry.
Those fields are omitted by default. For large designs, use the paginated
geometry endpoints; the full response is still subject to the MCP 1 MB limit.
- The organization budget shared by v1 and v2 is now 100 requests per minute. The v2 credential budget remains 20 requests per 10 seconds. See Rate Limits & Idempotency.
- Custom-property value collections now return an
ETagon reads and writes.PUTrequiresIf-Match, preserves omitted properties, and rejects stale or conflicting writes with412.
Effective when this release is deployed, read the custom-property values
collection and send its ETag in If-Match before updating values. Missing
headers return 428; after 412, read and reconcile before retrying.
Use decimal strings, real YYYY-MM-DD dates, "true"/"false" checkbox values,
and exact configured action options. Use null to clear a value. Manage file
uploads in Artemis and hyperlink URLs through property definitions.
Webhook integrations must use a user with access to the subscription's installer.
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. To create a new subscription, configure a V2 receiver using the Webhooks guide.
2026-10-07
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.
On deployment of this release, integrations must handle 422, complete the
listed checklist items, and retry with the latest If-Match value.
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.
-
The API v2 reference now includes named models for projects, customers, equipment, and other resources. Response schemas link to these models; API fields and behavior are unchanged.
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-23
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-21
Added
- API v2 now exposes the project's selected solar panel, inverter, and battery at
GET /external/v2/projects/{projectId}/equipment-selection. Update one or more selections by exact model number withPATCHand the latestIf-Matchvalue. Artemis validates the project's pinned pricing catalog and battery/inverter compatibility, then runs the existing pricing and design recalculation. - API v2 now accepts idempotent roof-plane design-help requests at
POST /external/v2/projects/{projectId}/design-help. The operation requires an attributed caller with project access,project:edit_details, and anIdempotency-Key. It creates persistent design-team work and may notify or assign staff when the organization's design-assistance pipeline is enabled.
Changed
PATCH /external/v2/projects/{projectId}/equipment/{projectEquipmentId}now acceptsoptionsMode: "replace". Replacement removes option groups omitted from the request, andoptions: []clears optional selections. The default remains merge. Artemis validates group and option ids and required groups against the project's pinned pricing catalog.- API v2 project-equipment create and update operations now accept catalog-backed
adders. Omit
adderson update to preserve the list, send[]to clear it, or send a replacement list of adder ids, quantities, selection state, and select options. Artemis derives all prices; caller-supplied price fields are rejected. Equipment reads now include each adder's calculation type, unit, unit price, and selected option.
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
Added
- Added project comments to the API v2 preview under
/external/v2:GET /external/v2/projects/{projectId}/commentslists threads with their replies,POST /external/v2/projects/{projectId}/commentscreates a comment or reply for an organization member, and the/comments/{commentId}operations get, edit, resolve, and delete one comment.GET .../comments/taggable-userslists the members who can be mentioned. Create requiresIdempotency-Key; update, resolve, and delete requireIf-Match. Writes accept an attributed API key or MCP OAuth withprojects:write. Create and update reject blank or whitespace-only content.
2026-09-05
Added
- Introduced the initial API v2 preview under
/external/v2, with project creation and reads, automatic design progress, and signed webhook subscriptions. API v1 remains supported alongside v2.

