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/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 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-help accepts optional urgencyMinutes (30, 60, 120 or 240; omit or send null for no rush) and optional categories, which defaults to ["roof-planes"]. Requests without either field behave as before.
  • GET /external/v2/projects/{projectId}/design-help/{designHelpId} returns urgencyMinutes, or null for no rush. See API Reference v2.

2026-11-04

Added

  • POST /external/v2/projects/{projectId}/documents now documents its accepted file types, when requirementId is required, what a same-name upload does, the 413 response for files over 10 MB, and a multipart curl example. The 10 MB limit also applies to video. The endpoint's behavior did not change. See API Reference v2.

Fixed

  • Project document examples show documentType in the uppercase form the API returns, such as OTHER.

2026-11-02

Added

  • V2 contract-signed webhooks include data.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 no data.

2026-10-30

Changed

  • POST /external/v2/users, PATCH /external/v2/users/{userId}, POST /external/v2/invites and POST /external/v2/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.
  • PATCH /external/v2/users/{userId} and the MCP update_user tool return 403 when 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/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-27

Changed

  • For Sungage financing, name in GET /external/v2/projects/{projectId}/financiers now carries the loan product, such as ClassicDPP-36, Escalator-2.9 or Installment, instead of the bare product type (ClassicDPP). financingProductId is unchanged. See API Reference v2.
  • GET /external/v2/projects/{projectId}/design returns the project's stored systemSize: 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 stays 0 when 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} includes result.serviceAddress, the service address printed on the bill (street, city, state, zip, country, each nullable). It is null when the bill shows no address. See API Reference v2.

2026-10-23

Changed

  • GET /external/v2/projects/{projectId}/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. See API Reference v2.
  • ?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/v2/users, PATCH /external/v2/users/{userId}, POST /external/v2/invites, and the matching MCP tools return 403 when 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, and user:* 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-28 must also send the MCP-Protocol-Version header, as the MCP specification requires. Requests without it get 400. 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 remain hmac. See API Reference v2.

2026-10-15

Added

  • GET /external/v2/projects/{projectId}/exports/job-nimbus downloads 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_own and project:view_team and 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=geometry for 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 ETag on reads and writes. PUT requires If-Match, preserves omitted properties, and rejects stale or conflicting writes with 412.

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 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.

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-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.

  • 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-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-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 with PATCH and the latest If-Match value. 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 an Idempotency-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 accepts optionsMode: "replace". Replacement removes option groups omitted from the request, and options: [] 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 adders on 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-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

Added

  • Added project comments to the API v2 preview under /external/v2: GET /external/v2/projects/{projectId}/comments lists threads with their replies, POST /external/v2/projects/{projectId}/comments creates a comment or reply for an organization member, and the /comments/{commentId} operations get, edit, resolve, and delete one comment. GET .../comments/taggable-users lists the members who can be mentioned. Create requires Idempotency-Key; update, resolve, and delete require If-Match. Writes accept an attributed API key or MCP OAuth with projects: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.