Documentation

API Lifecycle

The MakeFX REST API uses an explicit major-version contract without putting the version in the URL. Its production OpenAPI description is available at https://makefx.app/api/openapi.json.

Current version and negotiation

The current REST major version is 1. Existing /api/... paths remain stable; there is no /v1 path prefix.

Clients may send this request header on documented REST operations:

MakeFX-API-Version: 1

The header is optional. Omitting it selects v1 for backward compatibility, and sending exactly 1 has identical behavior. A present value is rejected when it is unsupported or malformed, including an empty value, surrounding-only whitespace, a repeated or comma-joined value, v1, or a dotted value such as 1.0.

Rejection happens before authentication, request validation, and operation side effects. The response is a bounded JSON error with HTTP status 400:

{
  "error": "unsupported_api_version",
  "error_description": "MakeFX-API-Version must be exactly 1 when provided.",
  "resolution_url": "https://makefx.app/docs/api-lifecycle"
}

This version header applies only to the documented external REST operations. OAuth protocol endpoints, the hosted MCP transport, webhooks, metadata endpoints, and public documents keep their separate contracts.

Compatibility

Additive changes that preserve existing request and response meaning remain in v1. Examples include a new optional request field, a new operation, or a new response field that clients are expected to ignore when unknown.

A change that breaks conforming v1 clients requires a newly supported major version. Examples include removing or renaming a field or operation, making an optional input required, changing a field's type or meaning, or changing established status-code semantics. The lifecycle document and OpenAPI document will identify supported majors before clients can select a new one.

Deprecation and sunset

No REST operation is currently deprecated. When an operation is deprecated, its responses will carry the standards-based lifecycle signals below rather than relying on an undocumented announcement:

  • Deprecation using RFC 9745;
  • Sunset using RFC 8594 when a removal date is scheduled;
  • Link: <policy-url>; rel="deprecation" pointing to migration guidance.

Deprecation does not itself remove v1 behavior. A scheduled sunset will be published with migration guidance, and a breaking replacement will use a new major version.

Enforced rate limits

Rate-limit headers describe only a limiter that actually evaluated the request. MakeFX does not attach them to authentication failures, static metadata, cacheable documents, or endpoints without an enforced limiter.

Generation admission for Variant regeneration and forced audio alignment has a fixed-window limiter. An admitted 202 response includes RateLimit-Policy and RateLimit. A denied 429 response also includes Retry-After, in seconds. The two RateLimit fields use IETF Structured Field syntax and report the enforced policy, quota, remaining allowance, window, and effective reset delay.

OAuth dynamic client registration at /api/oauth/register has a separate fixed-window policy. Evaluated registration responses include RateLimit-Policy and RateLimit; a limit denial also includes Retry-After. That OAuth boundary is independent from generation admission and is not part of REST version negotiation.

Clients should treat the returned policy and timing values as authoritative, wait at least Retry-After seconds after a 429, and avoid assuming a global or public unauthenticated API quota where no limiter is enforced.