Skip to main content
The iBubbl API is versioned in the URL path. The current version is v1.

​
Stability guarantees

Within /v1/, iBubbl will never:
  • Remove an endpoint.
  • Remove a field from a response.
  • Change a field’s type or stop accepting it as input.
  • Rename an enum value (e.g., status: "queued").
  • Change the semantics of an error code.
  • Change the HMAC signature algorithm for webhooks.
iBubbl may:
  • Add new endpoints.
  • Add new optional request fields (existing requests keep working).
  • Add new response fields (treat unknown fields defensively in your parser).
  • Add new event types to the webhook catalog (filter by event_types if you only want a subset).
  • Add new error codes for new failure modes.
  • Add new values to an existing enum — for example a new message status or failed_reason. Handle values you don’t recognise (log them, treat them as “other”) instead of failing.
  • Tighten validation. We aim to keep previously-accepted requests passing, but we have broken that once: since 2026-11-05, the contacts endpoints (POST /v1/contacts, PATCH /v1/contacts/{contact_id}, POST /v1/contacts/{contact_id}/tags) reject unknown body fields with 422 validation_error instead of ignoring them. POST /v1/messages still ignores unknown fields. Any future tightening will be announced in these docs before it takes effect.
Treat unknown fields, enum values and event types as forward-compat. Your code should not error on an extra response field, status or event type it doesn’t recognize.

​
Breaking changes

Breaking changes ship behind a new version prefix — /v2/ will exist alongside /v1/, not replace it. When a major version ships, iBubbl will:
  1. Announce the /v1/ sunset date in these docs at least 12 months before /v1/ is sunset.
  2. Show a dashboard banner with the migration timeline.
  3. Publish a /v2/ migration guide enumerating every change.
  4. Keep /v1/ fully operational for the deprecation window.

​
Deprecation policy

A field, endpoint, or behavior is “deprecated” when iBubbl announces it will be removed in a future major version. Deprecated items continue to work in their original version. They’re marked in the docs with a deprecation notice and (where it makes sense) emit a Deprecation HTTP response header pointing at the migration path.

​
Today

The current state of v1:
  • Single stable version.
  • No deprecated endpoints or fields.
  • No announced sunset date.
Build against /v1/ with confidence. The contract you ship today is the contract you’ll have a year from now.