Compatibility promise¶

This is the contract behind the rest of these docs. Events, scopes, transports and cards describe what the platform does today; this page says which parts of that we have promised not to break, and what happens when we need to.

Applies to: everything reachable with a jjb_ bot token, published at GET /api/v1/schema/ and browsable at /api/v1/docs/.

Does not apply to: any other endpoint. If it is not in the published schema, it is internal, it is not part of this promise, and it may change or disappear without notice — even if you can reach it.

What is frozen¶

These do not change in a breaking way, ever, without the notice period below. Each row links to the page that documents the surface in full.

What may change without notice¶

• Anything not in the published schema.
• The order of items in a list where no ordering is documented.
• Wording of human-readable strings (detail messages, labels, help text).
• Performance characteristics, rate-limit values upward, and the addition of new optional query parameters, response fields, event types and scopes.
• Internal identifiers that were never documented as stable.

Notice period¶

90 days. A breaking change to any frozen surface is announced at least 90 days before it takes effect, on the changelog below and by email to the address on record for every workspace with an active bot. During the notice period the old behaviour keeps working.

Security fixes are the one exception: if a surface must change to close a vulnerability, we change it immediately and tell you why.

Delivery semantics¶

The event stream is at-least-once and unordered. These are the guarantees themselves; transports shows the code that satisfies them.

• Deduplicate on X-JuhJuh-Delivery-Id. It identifies one delivery to one subscription and is stable across every retry of that delivery — that is what makes it usable as a dedupe key. The attempt number travels separately in X-JuhJuh-Attempt, so you can tell a retry from a first try without the dedupe key changing under you.
• Correlate related deliveries with X-JuhJuh-Event-Id, which is shared by every delivery caused by one action, across subscriptions and across transports.
• Retry ladder: 8 attempts over roughly 4 hours. A webhook subscription failing for 24 hours straight is auto-disabled and surfaced in the workspace UI.
• Reconcile against the REST API, not the stream. Events tell you something happened; the API is the source of truth for what the current state is. An integration that treats the stream as authoritative will drift. See missed frames for what this looks like in practice after a reconnect.

Rate limits¶

Over the request limit returns 429 with a Retry-After header. These numbers may go up without notice; a reduction follows the 90-day notice period. The events-per-hour figure applies to an app holding the events scope, across both transports.

Support and changelog¶

• Changelog: /api/v1/docs/ carries the current schema version; breaking-change notices are published there and emailed.
• Support: developers@juhjuh.com — for contract questions, breakage reports, and to be added to the breaking-change notification list.
• Status: the workspace's Apps & Bots page shows per-bot delivery health, which is the first place to look when deliveries stop.

This promise is a technical commitment about interfaces. It is not the legal relationship — what you may build, how you must handle a customer's data, and how either side ends it. Those terms are being finalised; ask developers@juhjuh.com if you need them before they are published.

Versioning¶

v1 is the only version. A v2 would be a new prefix mounted alongside v1, not a replacement — v1 would enter the notice period before removal, never disappear under a running integration.