Migrate to the People’s Court API

Start with the primary reference. Canonical operations are grouped by resource family; existing v2 operations appear under Compatibility alias. Existing operation IDs, URLs and signed artifacts remain valid. The preview does not establish complete canonical coverage or general availability. A missing replacement in the table means keep the existing route, not remove /v2 from its URL.

Requests, responses and credentials

Canonical filing routes use public principal kinds and procedure names, retaining the exact review packet, acceptance digest and opening journal. Published v2 preparation keeps claimantAcceptanceIdentity optional: omitting it retains partner consent and hosted respondent acceptance without creating a claimant packet or link. Canonical POST /api/filings requires the identity. Case adapters return data and requestId; errors use the documented problem envelope. Website aliases retain their existing envelopes. Handle these explicitly when moving a client. Canonical case views use individual, organization and autonomous_agent for principal kind, and standard or agent_only for procedure. No migration changes case-pinned Rules, accepted text, signature bytes or Award identity.

Use the existing case ID: partner IDs remain resolvable without rewriting stored references. Do not substitute a partner’s external principal string for an account identity. A selected side or principal is never proof of authority.

Browser callers retain account sessions, same-origin checks and private responses. Partner backend callers retain their tenant/environment-bound bearer credentials and membership grants. Account OAuth tokens act only for the approving account and scopes; existing-case delegation additionally binds the case. Client credentials are available to verified registered autonomous-agent accounts. OAuth does not grant administrator, reviewer or bilateral party powers. Consult each operation’s security alternatives: events support authorized sessions, OAuth, case capabilities and partner case authority. Representatives, processing-defect reports and procedural requests use explicit side-bound membership grants; internal processing resolution remains restricted. Account authority grants are not a drop-in replacement for v2 delegation registration.

Retries and operation identity

Idempotency-Key identifies a caller retry receipt; logical operation identity identifies the authorized business act, principal/side, tenant/environment, case and exact typed input. They are not interchangeable. Preserve the same key and semantic body when retrying an equivalent keyed alias. Never generate a new key merely because a response timed out, and never replay a different body under an old key.

Canonical Answer, invitation and record commands use their shared operation journals. Filing aliases preserve the same draft and opening journal. Existing unkeyed website behavior is unchanged. Do not assume every old/new pair has cross-route replay parity: complete an uncertain operation through the original route unless its documented shared journal covers the switch. Reconcile pending or unknown results before trying again; inspect fresh state after a conflict. Authority and deadlines are rechecked even on replay. A new invitation key explicitly requests rotation; secrets are not replayed. Signed evidence notifications deduplicate by signed event identity instead of a REST retry key.

Capability windows and headers

No retirement is scheduled by default. The live guide renders the currently configured family dates below the route inventory. The eligible method/path list is lib/api/compatibility-aliases.json; unlisted operations do not receive retirement treatment.

Each family (v2-filings, v2-cases, website-cases) has its own general-availability date. The durable family configuration takes precedence, followed by PEOPLES_COURT_API_V2_FILINGS_GA, PEOPLES_COURT_API_V2_CASES_GA, or PEOPLES_COURT_API_WEBSITE_CASES_GA; PEOPLES_COURT_API_COMPATIBILITY_START remains the fallback for a deliberately shared cohort. Dates use strict YYYY-MM-DD UTC form. Operators announce GA only after equivalent canonical operations, this guide, and the required coverage verification are available. Newly added capabilities must not inherit an elapsed window.

With a valid date and PEOPLES_COURT_API_CANONICAL_ROUTES=true, listed aliases emit Deprecation: @<Unix seconds> and Sunset at GA plus 180 days, or the integration’s approved later deadline, in HTTP-date format. Link identifies the exact successor and this guide. These follow RFC 9745 and RFC 8594. Invalid/unset dates, disabled canonical routes, unsupported methods, and unlisted paths do not announce a clock. Mutations are never redirected.

The partner console shows observed alias traffic by credential, first and last use, current windows, approved extensions, an export, and an acknowledgement control. Acknowledgement confirms receipt of the notice; it does not certify migration. Contact People’s Court before the deadline if an active integration needs an extension. An extension records the integration, reason, approver, and deadline and cannot be shortened through the administration controls.

Deprecation email milestones are the start, 90 days remaining, 30 days remaining, 7 days remaining, and actual permanent retirement. Contacts are the integration’s active tenant administrators, with the approved onboarding contact as a fallback. Each affected credential receives a separate notice identity; delivery is logged and duplicate scheduler runs do not resend it. A scheduler recovering after downtime sends the currently due milestone. No-contact integrations remain visible in usage and require operator follow-up.

Retirement proceeds through warnings, explicit short brownout intervals, and permanent retirement. Activation requires a durable admission against current integration usage and approved dispositions. Retirement 410 attempts remain measurable but do not count as renewed legacy use. Brownouts begin only after the compatibility window, with approved extensions still honored. During a brownout or after permanent retirement, an eligible alias returns HTTP 410, Cache-Control: no-store, computed policy headers, and the same successor Link, with this body:

{"type":"about:blank","title":"Compatibility alias retired","status":410,"code":"alias_retired","detail":"Use the linked canonical replacement and migration guide."}

Use the linked canonical route with the same key and equivalent typed input where the documented shared journal supports it. A 410 does not execute the old mutation. In-flight draft preparation and other non-equivalent transitions must complete on their original routes before retirement or receive an extension. Frozen v1 and retired publication-consent 410 responses retain their existing treatment; historical docs and raw OpenAPI URLs remain available. See the contract evolution policy.

Award execution resources

See the four execution modes. Live providers remain disabled by default; simulation and acknowledged performance do not confirm payment.

Special transitions

Legacy /api/v2/filings/prepare and /api/v2/filings/{draftId}/confirm are not the generalized draft contract. New integrations use /api/filings with the CreateCaseDraft schema (including intake configuration and claimant acceptance identity), then /api/filings/{id}/confirmations. The old prepare/confirm routes have distinct journal operation names and response projections; finish an in-flight draft on its original pair. They do not receive an equivalent-contract retirement announcement on this base. Website /api/disputes also includes intake modes outside canonical /api/cases; do not blindly switch every request to the new collection.

Website POST /api/disputes/{id}/restatement dispatches by body action: use /api/cases/{id}/record-summary/corrections for a correction and /api/cases/{id}/record-summary/confirmations for exact-digest confirmation. Preserve current server text and digest. A path-only header cannot select the body-specific successor, so this combined command has no automatic retirement announcement yet. A partner bearer caller may correct through /api/cases/{id}/record-summary/corrections when its case membership allows restatement:respond; the legacy partner alias POST /api/v2/cases/{caseId}/restatement keeps its own retry journal, so do not reuse one Idempotency-Key across the two.

For website appeal answers, first read /api/cases/{id}/appeals, then POST to /api/cases/{id}/appeals/{appealId}/answers using the authorized appeal ID. The legacy path has no appeal ID; automatic headers do not invent it. Fee initiation retains the separately authorized checkout route; /appeals/{appealId}/fee reads status, never attests payment.

Evidence reads split by resource. GET /api/cases/{id}/evidence is the caller-scoped collection: own-side exhibits, opposing exhibits only once disclosure has revealed them, and — for a partner bearer credential — the same side-scoped adoption candidates GET /api/v2/cases/{caseId}/evidence-candidates returns. GET /api/cases/{id}/evidence/{evidenceId} still downloads one authorized original file. The candidates alias is in the automatic window cohort; move to the canonical collection and read candidates from its data.

Fee payment splits the same way. GET /api/fees/{feeId} reads a fee by its durable id (exact amount, status, applicable case, collection disposition, expiry). POST /api/fees/{feeId}/checkout initiates payment provider-neutrally: it returns a typed descriptor naming the provider — a Stripe Checkout session for a card fee, or the exact x402 requirements committed when the fee was quoted. The fee is selected by the resource path, so the request body carries only promotionCode or priceSelection; sending caseId or feeRecordId is refused. Authority, sponsorship coverage, rate limits and fee-intent identity are unchanged, so a retry returns the same provider intent rather than a second one. POST /api/fees/stripe/checkout remains available as a compatibility alias; because the successor path needs the fee id from the request body, that alias emits no automatic retirement announcement, exactly like the body-dispatched restatement command above.

API-U2-EXEC now implements GET/POST /api/cases/{id}/executions and GET /api/executions/{id} for all four modes. /settlement-executions remains the compatibility alias and preserves its historical digest-bound input and response; no retirement window starts with this addition.

The following inventory covers every published v2 operation and website case route on this release base. “No equivalent on this base” is an explicit coverage gap or restricted control, not an invitation to use an undocumented canonical URL. Canonical replacement rows describe transport migration; they do not certify end-to-end journey completion.

<!-- route-inventory -->