Writing Sample
Release Notes

Release Notes

Platform Release Notes

This sample demonstrates how I structure release notes: clear version headers, categorized changes, migration guidance for breaking changes, and deprecation timelines.

v2.4.0 — September 2024

Released: September 18, 2024

New Features

  • Batch processing endpoint — Submit up to 100 requests in a single API call. See POST /v1/batch in the API reference.
  • Webhook retry configuration — Customize retry intervals and maximum attempts per endpoint in the dashboard.
  • Export to Parquet — Data exports now support Parquet format in addition to CSV and JSON.

Improvements

  • Reduced p95 latency for /v1/search by 40% through query optimization.
  • Dashboard now displays real-time webhook delivery status.
  • Improved error messages for validation failures (now include field path and constraint).

Bug Fixes

  • Fixed: Pagination cursor expired prematurely when filtering by date range.
  • Fixed: Webhook signatures failed verification when payload contained Unicode characters.
  • Fixed: Rate limit headers missing from 429 responses in certain edge cases.

Deprecations

  • GET /v1/users/{id}/activity is deprecated. Use GET /v1/activity?user_id={id} instead. Removal scheduled for v3.0 (Q2 2025).

v2.3.0 — June 2024

Released: June 5, 2024

Breaking Changes

This release contains breaking changes. Review the migration guide below before upgrading.

  • Authentication header change — API now requires Authorization: Bearer {token} format. The legacy X-API-Key header is no longer accepted.
  • Timestamp format — All timestamps now use RFC 3339 format (2025-12-10T14:30:00Z). Unix timestamps are no longer returned.
  • Removed endpoints — GET /v1/legacy/reports has been removed. Use GET /v1/reports with the format=legacy parameter if needed.

Migration Guide

1. Update authentication headers

# Before (no longer works)
curl -H "X-API-Key: sk_live_xxx" https://api.example.com/v1/account

# After
curl -H "Authorization: Bearer sk_live_xxx" https://api.example.com/v1/account

2. Update timestamp parsing

# Before: Unix timestamp
{"created_at": 1717596600}

# After: RFC 3339
{"created_at": "2024-06-05T14:30:00Z"}

Most modern JSON libraries handle RFC 3339 automatically. If you were manually parsing Unix timestamps, update your code to use a date parsing library.

New Features

  • Team workspaces — Organize projects and API keys by team with role-based access control.
  • Audit logs — Track all API key usage and configuration changes. Available on Business plans and above.

Improvements

  • SDK updates: Python SDK v3.0, Node.js SDK v4.0, Go SDK v2.0 released with full v2.3 support.
  • OpenAPI specification now available at /v1/openapi.json.

v2.2.1 — March 2024

Released: March 15, 2024 (Patch Release)

Security

  • CVE-2024-XXXX — Fixed authentication bypass in webhook signature verification when using Ed25519 keys. All customers using webhook signatures should upgrade immediately.

Bug Fixes

  • Fixed: Memory leak in connection pooling under sustained high load.
  • Fixed: Incorrect Content-Length header for compressed responses.

v2.2.0 — January 2024

Released: January 22, 2024

New Features

  • GraphQL API (Beta) — Query multiple resources in a single request. See the GraphQL documentation to get started.
  • Idempotency keys — Prevent duplicate operations by including an Idempotency-Key header with POST/PUT/PATCH requests.

Improvements

  • Increased default rate limit from 100 to 200 requests per minute for all plans.
  • Added request_id to all error responses for easier debugging.

Known Issues

  • GraphQL subscriptions are not yet available. Expected in v2.5.
  • Batch endpoint does not support file uploads. Use individual requests for file operations.

Versioning Policy

We follow semantic versioning (SemVer):

  • Major (X.0.0) — Breaking changes that require code updates
  • Minor (X.Y.0) — New features, backwards compatible
  • Patch (X.Y.Z) — Bug fixes and security patches

We provide at least 6 months notice before removing deprecated features. Subscribe to our changelog feed for updates.

Related Samples

This is a sample article to demonstrate how I write.