API compatibility

API compatibility

Twelfth public APIs use stable, unversioned URL paths. A path describes a resource or capability, not a release number.

What Twelfth preserves

Once an operation is public, Twelfth does not:

• remove or rename its path, method, request field, response field or documented error code;
• make an optional input required;
• change a field to an incompatible type or narrow the values it accepts;
• silently change a write’s meaning, permission boundary or idempotency behaviour; or
• reuse an identifier for a different resource.

Deprecated contract elements remain supported. An exceptional security or legal requirement may make continued operation impossible; Twelfth will publish the impact and use HTTP Deprecation and Sunset headers where advance signalling is practical.

Additive changes

Twelfth may add:

• optional response fields;
• new resources and operations;
• new optional request fields; and
• new event types.

Clients should ignore response fields they do not understand. Values intended to grow are documented as extensible strings rather than closed enums, because adding a value to a closed enum can break generated clients.

If a capability needs genuinely different semantics, Twelfth publishes a new, clearly named resource or operation and keeps the existing one working. It does not create /v2, /v3 or other version-number paths.

Building a resilient client

• Read the machine-readable code on application/problem+json errors rather than matching message text.
• Ignore unknown response fields.
• Follow Retry-After and RateLimit-* headers.
• Deduplicate webhook deliveries by webhook-id and make mutation retries idempotent.
• Use the current OpenAPI document as the transport contract.

For help with a proposed integration, email hello@twelfth.ai.