AlterLabAPI Versioning Policy
How AlterLab versions its API, handles breaking changes, and ensures your integrations remain stable.
Current Version
https://api.alterlab.io/api/v1/All current endpoints are served under the v1 prefix. This version is stable and actively maintained.
Versioning Strategy
AlterLab uses URL path versioning. The version number is part of the URL path, making it explicit in every request.
# All requests include the version in the URL path
curl https://api.alterlab.io/api/v1/scrape
curl https://api.alterlab.io/api/v1/crawl
curl https://api.alterlab.io/api/v1/usage| Aspect | Policy |
|---|---|
| Versioning scheme | URL path prefix (/api/v1/, /api/v2/, etc.) |
| Version lifecycle | Each major version is supported for at least 12 months after the next version launches |
| Deprecation notice | Minimum 90 days before any breaking change or endpoint removal |
| Frequency | New major versions are rare. Non-breaking additions happen continuously. |
What Is a Breaking Change
A breaking change is any modification that could cause existing integrations to fail. These are never introduced without prior notice.
Breaking Changes (require a new API version or 90-day notice)
- •Removing an existing endpoint
- •Removing or renaming a response field
- •Changing the type of an existing response field (e.g., string to number)
- •Making a previously optional parameter required
- •Changing authentication requirements for an endpoint
- •Changing the meaning of an existing error code
- •Reducing rate limits below documented thresholds
Non-Breaking Changes
These changes are deployed continuously without version bumps. Your code should handle these gracefully.
Non-Breaking Changes (no version bump needed)
- •Adding new API endpoints
- •Adding new optional request parameters to existing endpoints
- •Adding new fields to response objects
- •Adding new values to existing enums (e.g., new error codes, new scraping modes)
- •Adding new webhook event types
- •Improving error messages (the error code stays the same)
- •Increasing rate limits or improving performance
Best Practice
Deprecation Policy
When a feature or endpoint is scheduled for removal, AlterLab follows a structured deprecation process:
Announcement
Deprecation is announced in the changelog with a clear timeline. The endpoint or field is marked as deprecated in the API documentation.
Sunset Header (minimum 90 days)
Deprecated endpoints return a Sunset HTTP header indicating the removal date. The endpoint continues to work normally during this period.
Migration Period
Documentation is updated with migration guides. If a replacement endpoint exists, both old and new endpoints work side by side.
Removal
After the deprecation period, the endpoint is removed and returns 410 Gone. This date is always at least 90 days after the initial announcement.
Sunset Headers
When an endpoint is deprecated, every response includes standard deprecation headers per RFC 8594:
HTTP/1.1 200 OK
Content-Type: application/json
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Deprecation: true
Link: </docs/reference/changelog>; rel="sunset"
{
"data": { ... },
"warnings": [
{
"code": "DEPRECATED_ENDPOINT",
"message": "This endpoint is deprecated and will be removed on 2026-11-01. Use /api/v1/scrape instead.",
"documentation": "https://docs.alterlab.io/docs/reference/changelog"
}
]
}| Header | Description |
|---|---|
| Sunset | HTTP date when the endpoint will be removed |
| Deprecation | Set to true on deprecated endpoints |
| Link | Points to the changelog or migration guide with rel="sunset" |
SDK Compatibility
AlterLab maintains official SDKs for Python and Node.js. SDK versions follow Semantic Versioning:
| SDK Version | API Version | Meaning |
|---|---|---|
| 2.x.x | v1 | Patch and minor updates are backwards compatible |
| 3.0.0 | v2 (future) | Major SDK bump aligns with a new API version |
Keep SDKs Updated
alterlab~=2.0 in Python or "@alterlab/sdk": "^2.0" in Node.js) and updating regularly within that range.Staying Compatible
Follow these practices to ensure your integration remains stable:
Ignore unknown fields
New fields may appear in responses at any time. Configure your JSON parser to ignore unknown keys.
Handle new enum values
New error codes, scraping modes, and status values may be added. Use a default/fallback case in switch statements.
Check for Sunset headers
Log or alert when you receive a Sunset header so you have time to migrate before the endpoint is removed.
Pin SDK major versions
Use version ranges that allow minor and patch updates but not major bumps (e.g., ^2.0.0).
Follow the changelog
Check the changelog regularly to stay informed about new features and upcoming deprecations.