At Moveworks, our APIs are designed as permanent external data contracts to ensure reliability, consistency, and seamless integration for developers building AI workflows. To support this, we follow a structured versioning policy inspired by industry best practices. This policy utilizes three version types: alpha, beta, and stable (base) to align API maturity with your development needs.

Versioning allows us to introduce new features, fix issues, and evolve our platform without disrupting existing integrations. We do not use minor or patch versions for non-breaking changes, simplifying endpoint updates. Instead, we focus on major versions for breaking changes, with alpha and beta as precursors to stable releases.

All versions appear in API URLs (e.g., /v1alpha1, /v1beta1, /v1). This documentation clarifies the expectations for each version type and our approach to deprecation, helping you plan integrations with confidence.

Version Types

We categorize versions as follows:

• Alpha Versions (e.g., /v1alpha1): Early-stage, experimental releases for testing new features or base versions. These are primarily for internal use but may be shared for feedback.
• Beta Versions (e.g., /v1beta1): Semi-stable releases for broader testing, including production use with caveats. These refined APIs are based on feedback received before stabilization.
• Stable (Base) Versions (e.g., /v1): Fully mature, production-ready releases with long-term support. These form the foundation for reliable, enterprise-grade integrations.

Versions increment sequentially within categories (e.g., /v1alpha1 to /v1alpha2 for iterative alpha changes). A new major version (e.g., /v2) indicates breaking changes.

Version Types Diagram

This diagrams models version types as classes, highlighting inheritance-like progression and key properties properties.

classDiagram
    class Version {
        <<abstract>>
        +URL Prefix
        +Stability
        +Recommended Use
    }
    class Alpha {
        +URL Prefix: /v1alpha1
        +Stability: Low
        +Use: Internal/Feedback
    }
    class Beta {
        +URL Prefix: /v1beta1
        +Stability: Medium
        +Use: Limited Production
    }
    class Stable {
        +URL Prefix: /v1
        +Stability: High
        +Use: Full Production
    }
    Version <|-- Alpha
    Version <|-- Beta
    Version <|-- Stable
    Alpha --> Beta : Evolves To
    Beta --> Stable : Stabilizes To

Expectations for Alpha, Beta, and Stable Versions

Each version type has specific guarantees, usage guidelines, and requirements to balance innovation with stability. The table below summarizes key expectations:

Key Principles Across All Versions

• Consistency: We follow precedents for naming, patterns (e.g., pagination, error handling), and structures to make learning new APIs intuitive.
• Authentication: Endpoints support standard auth methods (e.g., API Keys, OAuth 2.0), with specifics documented per API.
• Rate Limiting: Enforced via headers (e.g., following GitHub-style best practices) for predictable backoff handling.
• Error Handling: Standardized responses with codes and messages (e.g., {"code": "EVENT_NOT_FOUND", "message": "Could not find event by ID: 123"}).
• Non-Breaking Changes: Added via alpha/beta iterations before merging into stable without URL changes.

How Versioning Aligns with Product Stages

Our versioning ties into product rollout stages to match API maturity with availability:

• Limited Preview: Typically uses alpha or beta versions for early feedback. Expect potential iterations.
• Preview: Primarily beta versions, with rare alpha use. Focus on refinement and load testing.
• General Availability (GA): Always stable versions. No alpha or beta in GA.

For example, a new API might progress as follows (simplified):

• Start in alpha for internal testing (/v1alpha1).
• Move to beta for limited production feedback (/v1beta1).
• Stabilize as base for GA (/v1).

Non-breaking enhancements reuse the stable version; breaking changes trigger a new major version (e.g., /v2alpha1).

API Versioning Timeline

This Gantt diagram timelines a sample API's journey through stages and versions.

gantt
    title API Versioning Alignment with Product Stages
    dateFormat  YYYY-MM-DD
    axisFormat %b %d

    section Employee Rollout
    Alpha Testing          :a1, 2025-01-01, 30d

    section Limited Preview
    Alpha Feedback         :after a1, 30d
    Beta Iteration         :b1, after a1, 45d

    section Preview
    Beta Refinement        :c1, after b1, 45d

    section GA
    Stable Release         :ga, after c1, 30d

API Deprecation Policy

We minimize disruptions by handling deprecations transparently and with advance notice. Deprecation means an API (or feature) is still functional but discouraged for new use, with a migration path provided.

Deprecation by Version Type

• Alpha Versions: No formal deprecation—can be modified or removed without notice, as they are not for production.
• Beta Versions: Subject to short-term deprecation. We provide at least 30 days notice, depending on feedback and usage. Use betas cautiously in production.
• Stable (Base) Versions: Long-term support with a minimum 3-month deprecation period. We continue operating the deprecated version during this time to allow migration.

Deprecation Process

1. Announcement: We notify via:
   1. Community
   2. Changelog entries.
   3. Email to registered API users.
   4. Response headers (e.g., X-Deprecated: true with details).
2. Migration Guidance: Provide detailed docs, including:
   1. Reasons for deprecation.
   2. Recommended alternatives (e.g., new version endpoints).
   3. Code examples for transitioning.
3. Support Period: Maintain functionality for the notice period (minimum 3 months for stable).
4. Sunset: After the period, the API returns errors (e.g., 410 Gone) and is removed from docs.