How does API versioning work?

The current API is version 1, which is implicit in the base URL (/api/...). When we introduce breaking changes, a new version will be created:

• Current: https://api.matcraft.ai/api/v1/materials
• Future v2: https://api.matcraft.ai/api/v1/v2/materials

Compatibility Promise

• The current version (v1) will remain available for at least 12 months after a new version is released
• Non-breaking changes (new fields, new endpoints) may be added to v1 without version bump
• Breaking changes (removed fields, changed response structure) always go to a new version

What Counts as Breaking

• Removing a response field
• Changing a field's type (string to number)
• Changing the structure of the response envelope
• Removing an endpoint

What Is Not Breaking

• Adding new optional query parameters
• Adding new fields to response objects
• Adding new endpoints
• Adding new enum values to existing fields