---
title: "Versioning"
description: "The version is in the path. v1 is current, unversioned URLs still answer, and what changes without a version bump."
---

## The version is in the path

Every data endpoint on `gateway.apinoa.com` lives under a version segment. **`v1` is the current
version**, and the one a new integration should use:

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

## Unversioned URLs still work

The old `https://gateway.apinoa.com/{marketplace}/{op}` form keeps answering, with the same body it
always returned. It is deprecated, not removed: every response 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, so a client can find its own way forward.
After **20 October 2026** the unversioned paths may stop answering. Move before then.

## What we may change inside v1

- **We add.** New fields on a response, new optional parameters, new marketplaces and new operations
  arrive in `v1` without a version bump. Parse leniently and ignore what you don't recognise.
- **We do not break.** Removing a field, renaming one, changing its type or its 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 marketplace did not say", and still does. It is not a change.

## What v1 renamed

Three AliExpress endpoints belong to that marketplace's own dialect, which predates the normalized
schema. They have **no `v1` URL** — under `/v1` they return `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` and `/aliexpress/image-search` | [`/v1/aliexpress/image-search`](/docs/api-reference/aliexpress#image-search) |

> **Warning:** **`image-search` is the one to read twice.** The segment is the same on both sides, the body is not.
> Unversioned `/aliexpress/image-search` returns AliExpress's own legacy shape; `/v1/aliexpress/image-search`
> returns the normalized `SearchResult` that every other marketplace returns. Adding `/v1` to that URL
> changes the response, so port the parsing with it.

`/aliexpress/visual-search` was only ever the normalized visual search wearing a second-choice name,
because the dialect had taken `image-search`. Inside `v1` the dialect is not present, so the canonical
name is free and the override is gone.

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