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

# Trade Routes

> Trade flow analysis, route shifts, and destination deceptions — endpoints for per-corridor volume trends, anomalous reroutes, and dark-port detection signals.

Trade flow analysis, route shifts, and destination deceptions.

## `GET` `/api/v1/routes/flows`

Trade route flows between ports with tonnage and market share.

**Parameters**

| Name          | Type   | Required | Description           |
| ------------- | ------ | -------- | --------------------- |
| `origin`      | string |          | Origin port ID        |
| `destination` | string |          | Destination port ID   |
| `week`        | string |          | Week start date (ISO) |
| `commodity`   | string |          | Commodity filter      |
| `limit`       | number |          | Default 100, max 500  |

**Response**

```json theme={null}
{ "flows": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/routes/flows?origin=VALUE&destination=VALUE
```

## `GET` `/api/v1/routes/shifts`

Detected trade route shifts and deviations.

**Parameters**

| Name        | Type   | Required | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| `severity`  | string |          | 'moderate' \| 'high' \| 'critical' |
| `origin`    | string |          | Origin port ID                     |
| `commodity` | string |          | Commodity filter                   |
| `limit`     | number |          | Default 100, max 500               |

**Response**

```json theme={null}
{ "shifts": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/routes/shifts?severity=VALUE&origin=VALUE
```

## `GET` `/api/v1/routes/deceptions`

Vessels whose actual destination didn't match declared destination.

**Parameters**

| Name          | Type   | Required | Description          |
| ------------- | ------ | -------- | -------------------- |
| `vessel`      | string |          | IMO number           |
| `suspicious`  | string |          | 'true' \| 'false'    |
| `actual_port` | string |          | Actual port ID       |
| `limit`       | number |          | Default 100, max 500 |

**Response**

```json theme={null}
{ "deceptions": [...] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/routes/deceptions?vessel=VALUE&suspicious=VALUE
```