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.
| Workflow | V1 | V2 |
|---|---|---|
| Create or list projects | POST / GET /projects | POST / GET /projects |
| Read a project | GET /projects/{projectId} returns a broad project payload | GET /projects/{projectId} returns core fields; read design, utility, pricing, financing, and documents through their subresources |
| Update project fields | PUT /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 definitions | PUT | PATCH on the corresponding v2 resource |
| Update comments | PUT /projects/{projectId}/comments/{commentId} | PATCH /projects/{projectId}/comments/{commentId} |
| Project custom-property values | PUT /projects/{projectId}/custom-properties | Still PUT /projects/{projectId}/custom-properties; check the v2 body schema |
| Utility bill analysis | POST /utility-bill/analyze | POST /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:
| V1 | V2 | |
|---|---|---|
| Request parameters | page, pageSize | limit, cursor |
| Results | data | data |
| Pagination metadata | pagination.page, totalItems, totalPages | page.nextCursor |
| Next page | Increment page | Pass the returned nextCursor as cursor |
| End | Last numbered page | nextCursor 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 itsETagresponse 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 aPUT; 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:
| V1 | V2 | |
|---|---|---|
| Payload | event and event-specific data | id, event, version, createdAt, and resource |
| Resource state | Included in the event data | Fetch resource.href from your configured Artemis API environment |
| HMAC input | Raw body | Timestamp, a dot, and raw body |
| Signature header | X-Signature | X-Artemis-Webhook-Signature, with X-Artemis-Webhook-Timestamp |
| Deduplication | Event-specific identifiers and idempotent writes | Event 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.

