Versioning

Stable v1. URL-segment versioning. Deprecation announced before the change ships; sunset announced before the change takes effect.

Where the version lives

The version is in the URL: https://api.prearrive.com/v1/properties. When we ship v2 it'll live at /v2/properties and v1 will continue serving for at least 18 months after v2 ships.

What's a breaking change

• Removing a field from a response.
• Renaming a field.
• Changing a field's type.
• Changing the meaning of a status code.
• Making an optional request field required.
• Changing the default value of an optional field.

None of these happen within v1. They go in v2.

What's additive (and lands without a version bump)

• New endpoints.
• New optional fields on a response (your parser must tolerate unknown fields).
• New optional request fields with a sensible default.
• New event types in webhook deliveries (subscribe via the explicit list, not ["*"], if you want stable membership).
• New error code values within an existing type.

Stability tiers

Tier	Promise
Stable	Covered by the v1 backward-compat promise. Default.
Beta	Usable, may change with 30 days' notice. Currently: the entire webhook surface (will promote to Stable after 90 days of clean operation).

The OpenAPI spec carries x-stability: beta on Beta endpoints; the rendered reference shows a Beta pill next to the operation.

Deprecation flow

Before we sunset an endpoint or field, you'll see:

• Docs: a "Deprecated" note in the rendered reference plus an entry in the changelog.
• Headers on every response from the deprecated endpoint:

  Deprecation: true
  Sunset: Wed, 19 May 2027 00:00:00 GMT

• Minimum 12 months between the Deprecation header appearing and the Sunset date. Often longer.

Rotating a stale API key

Same headers, different trigger — when you rotate an API key, the old key keeps working for 24 hours so you can swap it in production. Every response from the old key during that window carries Deprecation: true + a Sunset header at the rotation cutoff, so you can spot lingering use of the old key in your logs.

Monitoring deprecations programmatically

// Node — log a warning anywhere a Deprecation header shows up
const r = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (r.headers.get('deprecation') === 'true') {
  console.warn('PreArrive deprecated path', url,
    'sunset', r.headers.get('sunset'));
}

Related: Test mode · Idempotency · Full API reference