S
Scholé
Integration API
Governance

Versioning & API Lifecycle

How Scholé versions its API, the lifecycle each version follows, and how your team will be notified of upcoming changes.

Current Version
API version
v1.0.0 Active
OpenAPI spec
/api/v1/schema/
Release date
March 2026
Versioning Strategy

Scholé uses URL path versioning. The version segment is the first path component after the domain, making it explicit in logs, proxies, and reverse-proxy rules.

text
https://app.schole.ai/api/v{major}/resource/
PrincipleDetail
Major version only Only breaking changes increment v. Minor and patch changes are backwards-compatible and deployed to the same URL.
Concurrent support When v2 is released, v1 stays live for a minimum of 12 months.
SemVer internally The info.version field in the OpenAPI spec uses full SemVer (e.g. 1.2.0), so integrators can track minor additions.

What constitutes a breaking change?

Breaking — triggers v bump
  • Removing an endpoint or HTTP method
  • Renaming or removing a request/response field
  • Changing a field's type (e.g. string → integer)
  • Making a previously optional field required
  • Changing authentication requirements
Non-breaking — same URL
  • Adding new optional fields to responses
  • Adding new endpoints
  • Adding optional request parameters
  • Performance improvements
  • New error codes for previously undefined behaviour
API Lifecycle Phases

Every API version passes through the following phases.

PhaseStatus badgeDescriptionSLA
Beta Beta Spec may change without notice. Not suitable for production integrations. —
Active Active Stable, supported, and covered by 99.9 % uptime SLA. Non-breaking changes only. 99.9 % monthly
Deprecated Deprecated Still functional and supported, but a newer version is available. Migration guide published. Breaking changes frozen. Best effort
Decommissioned Decommissioned Endpoint returns 410 Gone. Integration must be migrated. —
Deprecation & Decommission Timeline

When Scholé decides to deprecate a version, the following minimum notice periods apply.

Deprecation announced
Email notification sent to all registered integration contacts. The API response header Deprecation: true is added. Migration guide published in the developer portal. Minimum 12 months before decommission.
6-month reminder
Second notification to contacts with migration guide link and deadline. Usage telemetry report provided upon request.
30-day final notice
Final warning email. Response header Sunset: <RFC 7231 date> added to all responses.
Decommission day
Endpoint returns 410 Gone with a JSON body pointing to the migration guide and the active version's URL.
Emergency deprecations
Critical security vulnerabilities may require expedited deprecation with less than 30 days notice. Scholé will make best efforts to provide alternative endpoints and direct support in such cases.
Change Notifications

Scholé will proactively notify your registered API contacts through the following channels. To register or update contacts, email api-support@schole.ai.

Email

Deprecation announcements, reminders, and decommission dates sent to your registered integration contacts.

Changelog

Every release — breaking or not — is documented in the changelog below. An RSS feed is available for automated monitoring.

Response headers

Deprecation: true and Sunset: <date> headers are added to all responses once a version is deprecated.

Developer support

Dedicated support for integration questions via api-support@schole.ai. Enterprise SLA customers get a named integration engineer.

Changelog
v1.0.0
Active March 2026
Initial release. 44 endpoints across 10 domains: Users, Teams, Skills, Curricula, Assignments, Analytics, Subscriptions, Documents, Surveys, and HR Operations. OAuth2 Client Credentials and JWT Bearer authentication.

Future releases will be listed here with full diff links.