> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning and Deprecation

> How Zenrows versions its API, how a version is retired, and the twelve-month notice you get before anything you depend on stops working.

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.

| Surface           | Base URL                           | Version |
| ----------------- | ---------------------------------- | ------- |
| Fetch and Extract | `https://api.zenrows.com/v1/`      | `v1`    |
| Batch             | `https://async.api.zenrows.com/v1` | `v1`    |

`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.

<Note>
  Error codes are part of the contract. `AUTH008` will always mean a rate limit was reached. See [API Error Codes](/api-error-codes) for the catalog.
</Note>

## How a Version Is Retired

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

<Steps>
  <Step title="Announcement">
    We publish the deprecation here and on the <a href="https://eu.intercom.news/zenrows" rel="nofollow">changelog</a>, and email every account with traffic on the affected version.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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:

    ```http theme={"dark"}
    Deprecation: @1789603200
    Sunset: Fri, 17 Sep 2027 00:00:00 GMT
    Link: <https://docs.zenrows.com/api-versioning>; rel="deprecation"
    ```

    `Deprecation` (<a href="https://www.rfc-editor.org/rfc/rfc9745.html" rel="nofollow">RFC 9745</a>) is when the version became deprecated, given as a Unix timestamp in seconds (the `@` prefix). `Sunset` (<a href="https://www.rfc-editor.org/rfc/rfc8594.html" rel="nofollow">RFC 8594</a>) is when it stops answering. Both are present from the announcement onward, and both point to the same instant twelve months apart.
  </Step>

  <Step title="Migration guide">
    We publish a guide covering every breaking difference with the announcement, not at the end of the window.
  </Step>
</Steps>

## 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](https://www.zenrows.com/openapi.json), and listed in the RFC 9727 catalog at [app.zenrows.com/.well-known/api-catalog](https://app.zenrows.com/.well-known/api-catalog).