Migrate from API v1 to v2

API v1 is being deprecated. Use v2 for new integrations. For existing integrations, see the migration guide and API Reference v1.

Migrate one workflow at a time and validate it in sandbox before switching production.

Methods, payloads, resource boundaries, pagination, and write headers differ; changing the URL prefix is not enough. Check each operation in API Reference v2.

1. Check credentials and operation coverage

  • Use an API key for the same environment and organization as the resources you want to access. The associated user's permissions determine access.
  • Confirm that every step in your workflow has a documented v2 equivalent. Keep using the documented v1 operation for any step you have not migrated.
  • REST API version and webhook contract version are independent. You can migrate REST calls while keeping existing V1 webhook subscriptions.

See Authentication & API Keys for credentials and Quickstart for a complete v2 starting example.

2. Map routes and request bodies

Paths below are relative to each version’s prefix. Replace {projectId} and other placeholders with resource IDs.

WorkflowV1V2
Create or list projectsPOST / GET /projectsPOST / GET /projects
Read a projectGET /projects/{projectId} returns a broad project payloadGET /projects/{projectId} returns core fields; read design, utility, pricing, financing, and documents through their subresources
Update project fieldsPUT /projects/{projectId}PATCH /projects/{projectId} for core fields; customer, co-applicant, and equipment have separate operations
Customer records/homeowners/customers
Project equipment/projects/{projectId}/equipments, updates use PUT/projects/{projectId}/equipment, updates use PATCH; primary solar panel, inverter, and battery selections use /equipment-selection
Tag definitions/tags/tag-definitions
Update users, teams, installers, roles, or custom-property definitionsPUTPATCH on the corresponding v2 resource
Update commentsPUT /projects/{projectId}/comments/{commentId}PATCH /projects/{projectId}/comments/{commentId}
Project custom-property valuesPUT /projects/{projectId}/custom-propertiesStill PUT /projects/{projectId}/custom-properties; check the v2 body schema
Utility bill analysisPOST /utility-bill/analyzePOST /projects/{projectId}/utility-bill-analyses, followed by its result-read operation

Follow each v2 request schema. For example, allowDuplicateCustomer replaces allowDuplicateHomeowner, and customer/equipment updates are separate from core project updates. Do not forward v1 bodies unchanged.

For utility bill analysis, first upload the bill as a project document and pass its documentId to the analysis operation. Its active file must be at most 3 MB, in JPEG (image/jpeg or image/jpg), PNG, WebP, or PDF format. The general document upload accepts up to 10 MB, but that does not make files above 3 MB eligible for analysis. An unsupported format, oversized file, or missing active version returns 400.

3. Update response parsing and pagination

V2 detail responses wrap the resource in data. For example, after creating a project, read response.data.id instead of the v1 response.id.

For project lists:

V1V2
Request parameterspage, pageSizelimit, cursor
Resultsdatadata
Pagination metadatapagination.page, totalItems, totalPagespage.nextCursor
Next pageIncrement pagePass the returned nextCursor as cursor
EndLast numbered pagenextCursor is null

Keep filters and sort order unchanged. Treat cursors as opaque and URL-encode them. V2 cursor responses do not provide v1 totals or page numbers; check each operation for exceptions.

A v2 project creation response is 201 after the project is saved. Utility setup and automatic design continue in the background. Read the project and its /design subresource before treating the design or proposal as ready. See Project creation and readiness.

4. Add write headers and retry handling

Check each v2 operation for its required headers:

  • Idempotency-Key: generate and persist a key for one intended operation. If its response is lost, retry with the same credential, operation, key, and payload. Use a new key only for a new intended operation. Replay protection lasts seven days.
  • If-Match: read the target resource first and save its ETag response header. Send the exact value, including quotes, when updating or deleting it. A project's ETag does not replace a comment's, equipment item's, or custom-property collection's ETag. Read the custom-property values collection before a PUT; omitted properties stay unchanged.

On 412, read current state and reconcile before retrying with the new ETag. On 428, supply the required header. Do not blindly retry an uncertain financial submission under a new idempotency key. Follow the operation's recovery steps.

V1 and v2 share the organization budget of 100 requests per minute. V2 also has a credential budget of 20 requests per 10 seconds. Parallel migration traffic consumes the shared budget; honor Retry-After on 429.

See Rate Limits & Idempotency for full retry rules and the additional v1 project-read limit.

5. Update error handling

V1 application errors normally use err; authentication failures use error and code. V2 uses code, message, and requestId, with optional fieldErrors or details.

Branch on the v2 code, not the text of message. Record requestId for support. Check the operation's documented statuses, including capability errors such as 422 when Design Help is not enabled. See Error Handling.

6. Keep or migrate webhook subscriptions separately

New subscriptions must use V2. Existing V1 subscriptions remain editable; REST migration does not convert them. Keep their receiver and signature verification while active. See V1 payload examples and V1 signing.

If you also migrate webhooks:

V1V2
Payloadevent and event-specific dataid, event, version, createdAt, and resource
Resource stateIncluded in the event dataFetch resource.href from your configured Artemis API environment
HMAC inputRaw bodyTimestamp, a dot, and raw body
Signature headerX-SignatureX-Artemis-Webhook-Signature, with X-Artemis-Webhook-Timestamp
DeduplicationEvent-specific identifiers and idempotent writesEvent id, not resource.id

Store the signing secret returned when creating a V2 subscription. It is separate from your API key, and reads do not return it. Implement V2 signature verification before enabling delivery. application-decision is V1-only; keep its V1 subscription if your integration depends on it.

Avoid applying the same business action twice while both subscriptions are active. After validating real sandbox events, move the corresponding production handlers and disable the replaced subscription. See Webhooks for supported events, signatures, and delivery behavior.

7. Verify before switching production

  • Confirm required permissions and operation coverage with your integration's user.
  • Exercise create, read, update, and pagination with the new response shapes.
  • Retry an operation with its original idempotency key and handle a stale ETag.
  • Handle validation, permission, rate-limit, and capability errors.
  • Verify signatures and duplicate delivery handling with real sandbox webhook events.
  • Keep v1 calls only for workflows you have not migrated; avoid sending the same write through both API versions.

Iframe URLs and POST /users/impersonate do not change with the REST API version. Follow Iframe Integration if you embed Artemis. Track subsequent changes in the v2 changelog.

Design response size

GET /external/v2/projects/{projectId}/design returns a summary by default. Add ?include=geometry to receive structures and the saved/combined outline fields (obstaclesWkt, roofOutlineWkt, combinedRoofOutlineWkt, parcelOutlineWkt). For large designs, read the paginated geometry endpoints instead. See both response examples in API Reference v2.