Versioning & Breaking Changes

This page describes how I'mBoard versions its public API and how breaking changes are communicated.

Versioning Scheme

The API is versioned via the URL path:

https://app.imboard.ai/api/v1/...
https://app.imboard.ai/api/v2/...   (future)

Each major version (v1, v2, ...) is a distinct, stable API surface. Within a major version, the API only receives backwards-compatible changes.

What Counts as a Breaking Change

A breaking change is any modification that could cause a working integration to fail:

• Removing an endpoint
• Removing or renaming a response field
• Changing the type of an existing response field
• Adding a new required request parameter
• Changing authentication or authorization behavior
• Changing the error envelope structure
• Changing the meaning of an existing enum value
• Reducing rate limits below previously documented values

What Is NOT a Breaking Change

These changes are considered backwards-compatible and may happen within a major version:

• Adding new endpoints
• Adding new optional query parameters
• Adding new fields to response objects
• Adding new enum values to existing fields
• Increasing rate limits
• Adding new error codes
• Improving error messages (text only, not structure)
• Adding new optional request body fields

Recommendation: Design your integrations to tolerate unknown fields in responses. Do not fail on unexpected properties — ignore them.

Deprecation Policy

When an endpoint or field is scheduled for removal in the next major version:

1. Deprecation notice — The endpoint or field is marked as deprecated in the OpenAPI spec and documentation. The response may include a Deprecation header.
2. Migration guide — A migration guide is published explaining the replacement and how to update.
3. Sunset period — The deprecated feature remains available for at least 90 days after the deprecation notice.
4. Removal — The feature is removed in the next major version only. It will not be removed within the current major version.

Changelog

V1.0.0 (2026-03)

• Initial public release
• Read endpoints for all core resources (boards, members, meetings, documents, reports, dashboards)
• Write endpoints for meetings (create, update)
• Personal access token authentication
• Cursor-based pagination
• MCP server integration