---
title: "Versioning"
description: "The version is in the path. v1 is current; what v1 may add, and what the older unversioned URLs do."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

## The Version Is in the Path

Every endpoint lives under a version segment. **`v1` is the current version**, and the one to use:

```bash
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"
```

Every response carries the version that answered in the `x-api-version` header.

## What May Change Inside v1

- **We add.** New response fields, new optional parameters, new platforms and new operations arrive in `v1`
  without a version bump. Parse leniently and ignore what you do not recognise.
- **We do not break.** Removing or renaming a field, changing its type or units, or making an optional
  parameter required would be a **new version** with its own path segment, never an edit to `v1`.

An absent field has always meant "the platform did not say", and still does. It is not a change.

## Unversioned URLs

The older form without a version, `https://gateway.apinoa.com/{platform}/{operation}`, is **deprecated**.
Every response on it carries:

| Header | Value |
|---|---|
| `Deprecation` | `true` |
| `Sunset` | `Tue, 20 Oct 2026 00:00:00 GMT` |
| `Link` | `<https://gateway.apinoa.com/v1/…>; rel="successor-version"` |

`Link` names the exact URL that replaces the one you called. The sunset date has passed: these paths may
stop answering at any time, so move to `/v1`.

## What v1 Renamed

Three AliExpress endpoints belong to that marketplace's own older dialect. They have **no `v1` URL**: under
`/v1` they answer `404 NOT_IN_V1`, with a `Link` to the successor.

| Deprecated | v1 |
|---|---|
| `/aliexpress/keyword-search` | [`/v1/aliexpress/search`](/docs/api-reference/aliexpress/search) |
| `/aliexpress/product-details` | [`/v1/aliexpress/product`](/docs/api-reference/aliexpress/product) |
| `/aliexpress/visual-search`, `/aliexpress/image-search` | [`/v1/aliexpress/image-search`](/docs/api-reference/aliexpress/image-search) |

> **Warning:** **`image-search` changes shape.** Unversioned `/aliexpress/image-search` returns AliExpress's own legacy
> shape; `/v1/aliexpress/image-search` returns the shared `SearchResult` every marketplace returns. Moving that
> URL to `/v1` changes the response, so port the parsing with it.

Every other path is a straight prefix: `/walmart/search` becomes `/v1/walmart/search`, and nothing about
the request or the response changes.