Skip to main content
Zenrows versions its API in the URL path. Every endpoint you call carries the version you are pinned to, so an integration written today keeps behaving the way it did on the day you wrote it. v1 is the only version that has ever existed, and no version has ever been retired.

​
What Changes Inside a Version

A version is a compatibility promise, not a freeze. Inside v1 we add, and we do not take away. You can expect, without notice:
  • New endpoints.
  • New optional request parameters, with the previous behavior as their default.
  • New fields in a response body.
  • New response headers.
Write your integration so an unrecognized field or header is ignored rather than treated as an error. That is the one thing we ask of you in return, and it is what lets us ship improvements without moving anyone to a new version. You will never see inside a version:
  • A parameter removed, or its default changed.
  • A field removed from a response, or its type changed.
  • An endpoint removed, or its path changed.
  • An error code reused for a different condition.
Error codes are part of the contract. AUTH008 will always mean a rate limit was reached. See API Error Codes for the catalog.

​
How a Version Is Retired

If we ever need to retire a version, this is what happens, in this order.
1

Announcement

We publish the deprecation here and on the changelog, and email every account with traffic on the affected version.
2

Twelve months of notice

The version keeps working, unchanged, for at least twelve months from the announcement. Not twelve months from when you read about it: twelve months from the day it is announced.
3

Machine-readable warning

Every response from the deprecated version carries the standard HTTP fields, so your code can detect the deadline without anyone reading an email:
Deprecation (RFC 9745) is when the version became deprecated, given as a Unix timestamp in seconds (the @ prefix). Sunset (RFC 8594) is when it stops answering. Both are present from the announcement onward, and both point to the same instant twelve months apart.
4

Migration guide

We publish a guide covering every breaking difference with the announcement, not at the end of the window.

​
What This Means if You Are an Agent

Read Sunset on any response. If it is present, the version you are calling has a deadline, and the Link header points at this page. Nothing else about the response changes: a deprecated version answers exactly as it always did, right up to its sunset date. If you build integrations that run unattended, treat the presence of a Sunset header as a condition worth surfacing to a human, the same way you would surface a payment failure.

​
Machine-Readable Description

The full API surface is described in OpenAPI 3.1 at www.zenrows.com/openapi.json, and listed in the RFC 9727 catalog at app.zenrows.com/.well-known/api-catalog.