Clari API and Schema Migration
Overview
Treat provider URL, authentication, request schema, job behavior, response schema, and destination mapping as one versioned contract. Prove the target alongside the current path before moving production traffic or published data.
Prerequisites
- Current and target hosts, versions, operations, schemas, and credential types
- Representative requests and expected reconciliations
- Dual-run environment, migration owner, and rollback deadline
Instructions
Step 1: Inventory the delta
Diff hosts, base paths, auth headers, methods, fields, enum values, errors, limits, pagination, and mutation semantics.
Step 2: Build an explicit mapping
Classify every used field and behavior as unchanged, renamed, transformed, added, removed, or unsupported.
Step 3: Update clients and fixtures
Pin the target contract, add target adapters and schemas, and retain current fixtures for regression and rollback testing.
Step 4: Dual-read safely
Run bounded non-production or approved parallel reads for identical windows and compare identifiers, counts, values, states, and latency.
Step 5: Cut over atomically
Move one workload or consumer at a time, retain the prior client and published snapshot, and stop on unexplained divergence.
Step 6: Retire with evidence
After the rollback window, remove legacy credentials and routes, update runbooks, and retain the comparison and revocation receipts.
Authentication
Do not reuse headers merely because two surfaces belong to Clari. Revenue, v2 ingestion, and Copilot each require their documented host and credentials; rotate or revoke legacy credentials only after rollback is no longer needed.
Tool Discipline
Use Read and Grep to inspect configuration, provider contracts, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for the approved plan, implementation, test, or redacted receipt; do not issue, rotate, revoke, create, update, cancel, delete, export, ingest, or publish provider data without explicit operator approval.
Output
- Contract delta and field-level compatibility map
- Dual-read reconciliation and performance report
- Cutover, rollback-window, legacy revocation, and retirement receipt
Return the exact surface, environment, resource or job identifiers, contract fingerprint, evidence, unresolved risks, and final decision without exposing credentials or sensitive customer data.
Examples
A client moves from an old Copilot host to rest-api.copilot.clari.com, validates the two-header authentication contract, dual-reads one approved week, reconciles call IDs, then revokes the legacy credential after the rollback window.
Error Handling
| Failure | Response | | --- | --- | | Target omits a required field | Stop cutover and define a supported replacement or consumer change. | | Dual-read values diverge | Classify window, scope, schema, and timing differences before accepting the target. | | Legacy credential is revoked early | Restore from the approved overlap credential or pause until a safe rollback path exists. |