Skip to main content

API Versioning

The neuroflash API uses URL path versioning. All endpoints include a version prefix in their path.

Current Version​

The API is not versioned as a whole. Instead, each service manages its own version independently. Endpoints follow the pattern:

https://app.neuroflash.com/api/{service}/v1/{resource}

Each service may increment its version independently when introducing breaking changes, so one service could be on v2 while others remain on v1.

Backward Compatibility​

We consider the following changes non-breaking and may make them without a version bump:

  • Adding new API endpoints
  • Adding new optional request parameters
  • Adding new fields to response objects
  • Adding new enum values
  • Adding new error codes
  • Changing the order of fields in responses

We consider the following changes breaking and will introduce a new version:

  • Removing or renaming existing endpoints
  • Removing or renaming existing response fields
  • Changing the type of an existing field
  • Making a previously optional parameter required
  • Changing the meaning of an existing field or parameter
tip

Design your integration to handle unknown fields gracefully. Use permissive JSON parsing and avoid strict schema validation on responses, so your code continues to work when new fields are added.

How Breaking Changes Are Communicated​

If a breaking change is necessary, we will:

  1. Release the new version under a new path prefix (e.g., /v2/)
  2. Announce the change in our documentation and changelog
  3. Continue supporting the previous version for a reasonable migration period
  4. Provide a migration guide for the new version