@gpt-core/admin 0.9.39 → 0.10.1

package/README.md

@@ -129,6 +129,58 @@ export const admin = new GptAdmin({
 });
 ```
 
+## API Versioning
+
+The SDK uses Stripe-style API versioning. A default API version is sent with every request via the `Accept` header.
+
+### Default Behavior
+
+Every request automatically includes the SDK's built-in API version:
+
+```http
+Accept: application/vnd.api+json; version=2025-12-03
+```
+
+No configuration is needed -- the SDK sends `DEFAULT_API_VERSION` from `base-client.ts` automatically.
+
+### Pinning a Version (Recommended for Production)
+
+Pin a specific API version to protect your integration from breaking changes:
+
+```typescript
+const admin = new GptAdmin({
+  baseUrl: 'https://api.gpt-core.com',
+  token: process.env.ADMIN_JWT_TOKEN,
+  applicationId: process.env.APPLICATION_ID,
+  apiVersion: '2025-12-03',  // Pin to this version
+});
+```
+
+### Reading the Active Version
+
+```typescript
+// The version the SDK is configured to send
+console.log(admin.apiVersion);
+```
+
+### Response Header
+
+Every API response includes the version that was used to process the request:
+
+```
+x-api-version: 2025-12-03
+```
+
+### Discovering Available Versions
+
+List all supported API versions and their changelogs:
+
+```bash
+GET /api-versions
+```
+
+This returns the full list of versions with descriptions and deprecation status.
+
 ## API Reference
 
 ### Webhooks