Versioning and stability

The Jelliu API evolves continuously. New endpoints, fields, events and enum values ship without a new API version, so the most important thing a client can do is tolerate additions. This page describes the stability contract and the signals Jelliu uses when something is on its way out.

The current version

Every request is served by the current v1 surface.

What counts as a compatible change

These changes are additive. They are made at any time, without a version bump:

• New endpoints.
• New optional request fields and query parameters.
• New fields in responses.
• New members in enumerations, such as a new call outcome, a new campaign category, a new error code or a new webhook event name.
• New webhook events being sent, including events already listed in the catalog as not yet sent.
• Changes to the wording of error message strings.

Build your client so that none of these can break it.

// Tolerant handling of an open enumeration and unknown fields.
function describeOutcome(call) {
  switch (call.outcome) {
    case 'sale_closed':
      return 'Won';
    case 'callback_scheduled':
      return 'Follow up';
    case 'rejected':
      return 'Lost';
    case null:
    case undefined:
      return 'Not analyzed yet';
    default:
      console.warn('Unrecognized outcome, treating as neutral:', call.outcome);
      return 'Other';
  }
}
// Only pick the fields you use; everything else is ignored.
const { id, status, outcome } = await (async () => {
  const res = await fetch('https://api.jelliu.co/api/calls?limit=1', {
    headers: { Authorization: `Bearer ${process.env.JELLIU_API_KEY}` },
  });
  const body = await res.json();
  return body.data?.calls?.[0] ?? {};
})();
console.log(id, status, describeOutcome({ outcome }));

Deprecations

When an interface is being retired, Jelliu marks responses from it with standard HTTP headers:

For example, the legacy inbound CRM webhook route POST /webhooks/integrations/{tenantId}/{integrationId} answers with all three, pointing to its replacement POST /webhooks/integrations/v2/{webhookUuid}:

HTTP/1.1 200 OK
Deprecation: @2026-06-01T00:00:00Z
Sunset: Mon, 01 Jun 2026 00:00:00 GMT
Link: </webhooks/integrations/v2/5f0c2a9e-1b7d-4e3a-9c6f-2d8e7a1b0c34>; rel="successor-version"

Some deprecations cannot be signalled with a response header, because the caller is Jelliu rather than you. The one currently in progress:

• Legacy webhook signatures. Outbound webhook deliveries still carry X-Webhook-Signature and X-Webhook-Signature-V1 (HMAC of the body alone) next to X-Webhook-Signature-V2. The legacy headers will be removed. Verify X-Webhook-Signature-V2 today. See Verifying signatures.

Detect deprecated calls automatically

Log a warning whenever a response carries a Deprecation or Sunset header, so a retirement shows up in your monitoring long before the sunset date.

curl -sS -D - -o /dev/null "https://api.jelliu.co/api/agents" \
  -H "Authorization: Bearer $JELLIU_API_KEY" | grep -iE '^(deprecation|sunset|link):'

Machine-readable reference

The OpenAPI document behind the API Reference is served by the API itself and regenerated on every deploy, so it always matches what is running:

All are public and cached for up to 5 minutes.

curl -sS https://api.jelliu.co/openapi.public.yaml -o jelliu-openapi.yaml

What to watch

• Changelog. Notable changes to the API and to this documentation.
• Response headers. Deprecation and Sunset, as above.
• Webhook event catalog. Events marked “Not yet” in Webhooks are accepted in subscriptions today and can start being delivered. Subscribe only to events you handle, or make your receiver ignore unknown ones.
• Error codes. New codes can appear. Map unknown 4xx codes to a generic, non-retryable failure and unknown 5xx codes to a retry with backoff. See Errors.

Related