@gpt-core/client 0.9.39 → 0.10.1

package/README.md

@@ -97,6 +97,57 @@ const authenticatedClient = new GptClient({
 const workspaces = await authenticatedClient.platform.workspaces.mine();
 ```
 
+## 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 client = new GptClient({
+  baseUrl: 'https://api.gpt-core.com',
+  apiKey: 'sk_live_...',
+  apiVersion: '2025-12-03',  // Pin to this version
+});
+```
+
+### Reading the Active Version
+
+```typescript
+// The version the SDK is configured to send
+console.log(client.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.
+
 ## Configuration
 
 ```typescript