Skip to content
BloopBloopBloop Docs

Understanding API versioning and compatibility

Your integration should keep working while Bloop improves the API. These rules say which changes can happen at any time within a version, and which ones need a new version. They apply to the API (/v1) and to webhook payloads (api_version: v1) alike.

Compatibility rules

Section titled “Compatibility rules”

Within one major version (/v1, webhook api_version: v1), Bloop may:

  • add new fields to a response or payload;
  • add new values to an enum (for example reward.type, source, status);
  • add endpoints, optional query parameters, event types, scopes and new error codes.

Your client must ignore unknown fields, handle unknown enum values (treat them as “other”), and not rely on the order of fields. A webhook endpoint only receives the events it is subscribed to, so new event types never arrive on their own.

Within one major version, Bloop will not: remove or rename a field, change a data type, change the meaning of a field, remove an enum value that is in use, or add stricter validation to requests that are valid today. Changes like these require /v2.

Deprecation policy: Bloop announces the retirement of a version at least 12 months in advance, by email and in the changelog on this site. Automated contract tests block accidental breaks of these rules.

Write a tolerant client

Section titled “Write a tolerant client”
  • Parse JSON into a structure that ignores unknown keys. Don’t validate responses or webhook bodies against a schema that rejects extra fields.
  • Give every switch on an enum a default branch. A new source, status or join_source value then falls into “other” instead of crashing.
  • Read fields by name, never by position.
  • Store every id and cursor as an opaque string. Don’t parse it, don’t do math on it, don’t compare ids by size.
  • Expect a new event type only after you subscribe an endpoint to it.
  • Handle an unknown error code by its HTTP status.

How a webhook endpoint picks its version

Section titled “How a webhook endpoint picks its version”

Each endpoint is pinned to one payload version. The version appears in the X-Bloop-API-Version header and in api_version in the body. v1 is the only version today, and an endpoint keeps receiving the version it is pinned to.

Changelog

Section titled “Changelog”
Date Change
October 2026 Version 1: GET /v1/me, GET /v1/referrers, GET /v1/referrers/{id}, and the webhook events referrer.joined, referral.pending, referral.succeeded and webhook.test.

Common mistakes to avoid

Section titled “Common mistakes to avoid”
  • Validating responses with a strict schema. A new field breaks your integration although the change is allowed.
  • An enum switch without a default branch. A new value crashes the handler.
  • Treating ids as numbers. They are strings and may stop looking like numbers.
  • Assuming fields arrive in a fixed order. JSON objects have no guaranteed order.

Next steps

Section titled “Next steps”