Versioning

What we publish

This site documents V3 — the contract powering the new Handbid mobile apps and the surface we recommend for partner integrations. V1 still exists internally and is used by the manager web app, but it’s not what new integrations should build against.

Future major versions (V4, etc.) will be a deliberate decision tied to a breaking-change need. We don’t release a new major version per ticket.

What “backward compatible” means in V3

We make purely additive changes without bumping the version:

• ✅ Adding a new optional field to a response.
• ✅ Adding a new endpoint.
• ✅ Adding a new value to an enum where clients are documented to fall through to a default on unknown values.
• ✅ Relaxing validation (accepting input the server used to reject).

We don’t:

• ❌ Rename or remove a field without a version bump.
• ❌ Change a field’s type (string → int, etc.).
• ❌ Tighten validation in a way that rejects requests that used to succeed.
• ❌ Move an endpoint to a different URL.

If you’re scripting against V3, treat unknown fields as forward-compatibility extension points. Parse leniently; serialize strictly.

Enum extension

Some response fields carry enum-shaped strings — status, type, etc. The contract is: clients fall through to a documented default on any unknown value. This lets us add new enum members without breaking older clients.

Each endpoint that ships an enum documents:

• The current set of values.
• The default behavior on unknown values (typically: render as the catch-all variant, e.g., general for notification types).

If your client crashes on an unknown enum value, that’s an integration bug — file an issue and we’ll help.

Deprecation

When something needs to go away:

1. We add a @deprecated note in the API reference and on this site.
2. The endpoint continues to work for at least 6 months after the notice — longer if it’s heavily used.
3. We send a heads-up via the channel you’ve registered for engineering notifications (typically the partner’s engineering contact email).
4. After the deprecation window, the endpoint returns 410 Gone for at least 30 days before any 404 cleanup.

Currently deprecated:

• GET /v3/bidder/active-bids — superseded by /v3/bidder/my-activity (HAN-1849). Still functional, slated for removal in a future minor release.
• GET /v3/bidder/my-items — superseded by /v3/bidder/my-activity (HAN-1849). Same timeline.

Changelog

Every shipped change to the V3 surface lands in the Changelog. That’s the canonical source for “what’s new.” This site, the OpenAPI spec, and the Postman collection all derive from the same internal release process — if it’s in the changelog, it’s in all three.

V2

The older V2 surface is being phased out. New integrations: don’t. Existing V2 integrations: migrate at your pace; V2 will continue to work through the planned sunset window. Migration mappings live in our internal docs at docs/api/v3/v2-deprecation.md in the platform repo — ping us if you need a copy.