Migrate from Public API V1 to V2

​

V1 and V2 coexistence

• V1 continues to serve its released routes under /public/v1 while it is deprecated.
• V2 uses independent routes, schemas, OpenAPI documentation, and versioned client defaults. Changing a V1 base URL is always your decision.
• V1 requests are not redirected or translated into V2 requests, including prompt imports.
• The V1 prompt-import route is an accelerated exception to the broader V1 read-retirement process. It remains operational only until the V2 prompt-import production gate passes, then returns 410 version_retired. There is no redirect, translation, mirroring, or dual write between versions.
• No Sunset date or retirement date has been announced for the broader V1 read surface.
• The Videntic MCP integration remains on V1 pending a separate consumer audit and rollout. Do not migrate or override its base URL as part of an API V2 preview.

​

Current V2 private-preview surface

​

V2 prompt-import surface

​

Contract differences to plan for

​

Practical migration plan

1. Request private-preview access. Email [email protected] with your workspace, current V1 routes, expected volume, and whether you use prompt imports. V2 remains unavailable until access is explicitly enabled.
2. Inventory your V1 dependency. Record every route, selected field, pagination assumption, metric calculation, retry rule, and downstream table. Treat MCP as a separate V1 consumer and leave it unchanged.
3. Build a version-specific adapter. Keep independent V1 and V2 base URLs, response parsers, cursor storage, and error handling. Store opaque V2 IDs as strings and preserve the version metadata returned with analytics.
4. Run bounded dual reads. For preview-approved read routes, fetch V1 and V2 independently into separate staging tables. Compare resource coverage, nullability, finalized-analysis timestamps, metric definitions, evidence counts, and pagination completion. Do not overwrite your V1 analytical baseline with V2 values during comparison.
5. Approve a separate V2 baseline before cutover. Do not pass this gate until your integration owner has recorded and explained every expected metric delta found during dual reads; preserved the returned V2 contract, projection, metric-definition, precision, and taxonomy version metadata; and approved a distinct V2 checkpoint and analytical baseline. Never splice V2 values into the V1 historical series.
6. Test the write cutover in private preview. Follow the bulk prompt-import guide to build the dedicated write-key, two-idempotency-key validation, explicit bulk partitioning, asynchronous polling, and redacted-receipt paths behind a disabled client flag. You may exercise them in a preview-enabled workspace, but do not enable production use until Videntic announces that the production-readiness gate passed. The V1 prompt-import route remains operational today; after the gate it retires and is not a write fallback.
7. Cut over in your client. Move one controlled consumer at a time by changing its configured API version. Monitor your own results and retain the last known-good V1 configuration until the V2 preview is signed off for your integration.

​

Roll back safely

1. Restore the affected read consumer’s last known-good /public/v1 base URL, V1-specific parser, credentials, and cursor state. Do not feed a V2 cursor or opaque ID into a V1 request.
2. Resume reads from the last committed V1 checkpoint. For an accepted V2 prompt import, continue polling its receipt to a terminal state; do not retry the batch through V1 or assume that changing the read version cancels it.
3. Disable new V2 prompt submissions in your client if the write path is unhealthy, retain the original idempotency key for transport-uncertain retries, and contact support before creating a replacement operation.
4. Send the request IDs, import IDs, timestamps, and affected routes to [email protected]. Do not include API keys or prompt text.

​

Existing V1 reference