Move new work to canonical `/v1/*` routes and treat compatibility paths as explicit debt.

Migration rules that prevent drift

• Point new tooling, generated clients, and partner examples at canonical `/v1/*` routes first.
• Keep compatibility aliases explicit in code, logs, partner communication, and sunset planning.
• Do not present migration-only routes as permanent product surface area.
• Keep the cutover packet on the same OpenAPI hash as the deployment you are validating.

Retire diligence-only tooling inputs

• Replace legacy diligence-only OpenAPI consumers with the raw partner contract at https://api.dutyclaims.com/v1/docs/openapi.
• Keep the generated broker compatibility notes in the cutover packet: broker-compatibility.md

Canonical diligence examples

Use the generated examples below as your migration rehearsal path, then move your app logic onto the downloaded starter files or your own typed client wrapper.

#!/usr/bin/env bash
set -euo pipefail

API_BASE_URL="${API_BASE_URL:-https://api.dutyclaims.com}"
TOKEN="${TOKEN:-dcp_live_replace_me}"
CSV_PATH="${CSV_PATH:-./sample-entries.csv}"

curl -X POST "${API_BASE_URL}/v1/diligence/submit" \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "seller_name=Acme Imports" \
  -F "requires_protest_documentation=false" \
  -F "file=@${CSV_PATH};type=text/csv"

#!/usr/bin/env bash
set -euo pipefail

API_BASE_URL="${API_BASE_URL:-https://api.dutyclaims.com}"
TOKEN="${TOKEN:-dcp_live_replace_me}"
JOB_ID="${JOB_ID:-00000000-0000-4000-8000-000000000000}"

curl "${API_BASE_URL}/v1/diligence/status/${JOB_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json"

#!/usr/bin/env bash
set -euo pipefail

API_BASE_URL="${API_BASE_URL:-https://api.dutyclaims.com}"
TOKEN="${TOKEN:-dcp_live_replace_me}"
JOB_ID="${JOB_ID:-00000000-0000-4000-8000-000000000000}"

curl -X POST "${API_BASE_URL}/v1/diligence/jobs/${JOB_ID}/resume" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/json"

Diligence cutover checks

• Compare auth success and failure behavior on the legacy and canonical surfaces before switching traffic.
• Keep report and dataset consumers pinned to the same job ID and contract version.
• Do not remove the legacy compatibility path until your comparison suite passes against live-like traffic.
• Keep RF8 interpretation on the public report contract only; source-lookup details remain internal.

Headers to log during alias traffic

When to stop using alias routes

• Stop once the canonical route delivers the same business outcome and your partner no longer depends on the alias namespace.
• Keep long-term aliases explicit in docs and code; they are compatibility aids, not proof that canonical migration is optional.
• Set an explicit sunset date for every migration-only alias that remains live.
• Use the production launch checklist before moving live traffic.

Long-term aliases

• /broker/v1/onboard -> /v1/partner-organizations/{partnerOrgId}
• /broker/v1/webhooks/register -> /v1/webhooks/endpoints
• /broker/v1/clients -> /v1/clients
• /broker/v1/portfolio/scan -> /v1/portfolio-scans
• /broker/v1/portfolio/scan/{scanId} -> /v1/portfolio-scans/{scanId}
• /broker/v1/notifications -> /v1/notifications
• /broker/v1/revenue/ledger -> /v1/revenue/ledger
• /broker/v1/revenue/dashboard -> /v1/revenue/dashboard
• /broker/v1/claims -> /v1/claims
• /broker/v1/offers -> /v1/offers
• /broker/v1/litigation/enroll -> /v1/litigation/enroll

Migration-only aliases

• /broker/onboard -> /v1/partner-organizations/{partnerOrgId}
• /broker/v1/portfolio/delta-scan -> /v1/portfolio-scans
• /broker/v1/portfolio/summary -> /v1/portfolio-scans/{scanId}/summary