Changelog and versioning

The versioning model

The API has exactly one version axis. It is the path. Every endpoint lives under https://api.fightclub.pro/v1/..., and that /v1 is the whole contract. There is no Ringside-Version request header, no Stripe-style dated pin, no ?version= query parameter and no per-key version setting in the dashboard. If you have seen other API providers ask you to send a version date on every request, Ringside deliberately does not do that.

The trade is simple. You get continuous delivery of new fields, headers, endpoints and model refs with no migration step, and in return additive changes can appear under /v1 at any time. So you write tolerant clients. Ignore response fields you do not recognise, branch on documented enum values rather than asserting the full set is closed and never parse the human-readable message string in an error body. Branch on the machine code instead.

What is additive vs breaking

The line between the two is what makes the no-header model safe. Additive changes ship under /v1 whenever they are ready. Breaking changes do not ship under /v1 at all.

Additive (can appear under /v1 at any time)

• ·New endpoints (a new resource appears, existing ones are untouched).
• ·New optional request parameters and new request headers, all defaulting to the prior behaviour when omitted.
• ·New fields in a response body or new X-Ringside-* / FC-* response headers.
• ·New enum members: an extra error.type, a new webhook event type, a new run status, a new model in the catalog.
• ·New model-ref prefixes or @<region> residency suffixes.
• ·New providers behind the existing 19-provider routing layer.

Breaking (would never ship silently under /v1)

• ·Removing or renaming a request parameter, response field, header or error code.
• ·Changing the type or meaning of an existing field.
• ·Tightening validation so a request that used to succeed now 400s.
• ·Changing a default (for example, flipping stream or moderation defaults).
• ·Removing an endpoint or an ID prefix.

How to tell what changed at runtime

You do not poll a version endpoint to discover capabilities. The API tells you inline. A handful of signals are worth wiring into your client so you notice additive changes without reading release notes.

Capability milestones

Dates below are drawn from the repository record. Each row is a backward-compatible addition under /v1. Nothing here required a client change beyond opting into the new surface, with the single noted exception of the OpenAI-SDK migration, where the only change to existing code is the fc: model prefix.

Worked example: a forward-compatible error handler

The single most important rule for surviving additive change is to branch on error.code rather than error.message and to keep a default arm. The error envelope is stable in shape. Its enum members are not closed.

{
  "error": {
    "type": "rate_limit_error",
    "code": "customer_rate_limit_exceeded",
    "message": "Customer cus_42 exceeded its rpm limit",
    "retry_after_seconds": 12
  }
}

Edge cases and gotchas

No version header means no version pin

You cannot freeze behaviour to a past date. If a default ever changed it would be a breaking change and would not ship under /v1, so set the parameters you care about explicitly (for example send stream and moderation rather than relying on their defaults) to make your client self-documenting.

Cross-tenant access is a 404, not a 403

Reaching for an id you do not own returns not_found_error / 404 so ids are not enumerable. This has always been the behaviour and is not a versioned change, but it surprises people expecting a 403.

New enum members can appear mid-integration

A new webhook event type, a new run status or a new error.type can land under /v1 between your deploys. Subscribe to webhook events by explicit name and keep the default arm on every status switch.

The OpenAI SDK migration is the one diff

Pointing the OpenAI SDK at https://api.fightclub.pro/v1 is a drop-in, except every model ref needs the fc: (or match: / slot: / dyn:) prefix. A bare gpt-4o returns 400 invalid_model_ref. That is a routing requirement, not a version change.

Limits and defaults referenced here

See also