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

# Watchlists

> Monitor vessels by IMO number with configurable event notifications, categories, and bulk operations — building blocks for a programmatic watchlist.

Track vessels you care about and get notified when key events occur. Vessels on your watchlist are highlighted across alerts, positions, and risk views.

## `GET` `/api/v1/watchlist`

<Note>Requires API key.</Note>

List all vessels on your watchlist, including joined vessel details and category info.

**Response**

```json theme={null}
{
  "watchlist": [
    {
      "id": 1,
      "imo_number": "9622629",
      "label": "Meridian — Gulf fleet",
      "notify_on": ["port_entry", "port_departure", "dark_event", "sanctions_match"],
      "category_id": 5,
      "sort_order": 0,
      "created_at": "2026-04-18T12:00:00Z",
      "watchlist_categories": { "id": 5, "name": "Gulf fleet" },
      "vessels": {
        "name": "MV Meridian",
        "vessel_type": "Bulk Carrier",
        "flag": "MH",
        "risk_score": 42,
        "risk_tier": "medium"
      }
    }
  ],
  "count": 1,
  "tier": "pro"
}
```

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/watchlist
```

## `POST` `/api/v1/watchlist`

<Note>Requires API key.</Note>

Add a vessel to your watchlist. If the vessel is already watched, the existing entry is updated.

**Parameters**

| Name          | Type      | Required | Description                              |
| ------------- | --------- | -------- | ---------------------------------------- |
| `imo_number`  | string    | ✓        | 7-digit IMO number                       |
| `label`       | string    |          | Custom display label                     |
| `notify_on`   | string\[] |          | Event types to alert on (defaults below) |
| `category_id` | number    |          | Category to assign the vessel to         |
| `sort_order`  | number    |          | Display order within the list            |

If you set a `category_id` without providing `notify_on`, the vessel inherits the category's `default_notify_on` list.

**Default `notify_on` events**

| Event             | Description                           |
| ----------------- | ------------------------------------- |
| `port_entry`      | Vessel arrives at any monitored port  |
| `port_departure`  | Vessel departs a monitored port       |
| `dark_event`      | AIS signal gap detected               |
| `sanctions_match` | Vessel flagged by sanctions screening |

**Example**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/watchlist \
  -d '{
    "imo_number": "9622629",
    "label": "Meridian — Gulf fleet",
    "notify_on": ["port_entry", "dark_event", "sanctions_match"],
    "category_id": 5
  }'
```

## `PATCH` `/api/v1/watchlist`

<Note>Requires API key.</Note>

Update a watched vessel's label, notification events, or category.

**Parameters**

| Name          | Type      | Required | Description                        |
| ------------- | --------- | -------- | ---------------------------------- |
| `imo_number`  | string    | ✓        | IMO number of the vessel to update |
| `label`       | string    |          | New label                          |
| `notify_on`   | string\[] |          | Updated event list                 |
| `category_id` | number    |          | New category                       |
| `sort_order`  | number    |          | New sort order                     |

**Example**

```bash theme={null}
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/watchlist \
  -d '{"imo_number": "9622629", "notify_on": ["dark_event"]}'
```

## `DELETE` `/api/v1/watchlist`

<Note>Requires API key.</Note>

Remove a vessel from your watchlist.

**Parameters**

| Name  | Type   | Required | Description              |
| ----- | ------ | -------- | ------------------------ |
| `imo` | string | ✓        | IMO number (query param) |

**Example**

```bash theme={null}
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/watchlist?imo=9622629"
```

***

## Categories

Organize watched vessels into groups. Categories support nesting and carry default notification settings that propagate to any vessel added without an explicit `notify_on` list.

### `GET` `/api/v1/watchlist/categories`

<Note>Requires API key.</Note>

List all watchlist categories.

**Response**

```json theme={null}
{
  "categories": [
    {
      "id": 5,
      "name": "Gulf fleet",
      "parent_id": null,
      "sort_order": 0,
      "default_notify_on": ["port_entry", "port_departure", "dark_event", "sanctions_match"]
    }
  ],
  "count": 1
}
```

**Example**

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/watchlist/categories
```

### `POST` `/api/v1/watchlist/categories`

<Note>Requires API key.</Note>

Create a category.

**Parameters**

| Name                | Type      | Required | Description                                 |
| ------------------- | --------- | -------- | ------------------------------------------- |
| `name`              | string    | ✓        | Category name                               |
| `parent_id`         | number    |          | Parent category for nesting                 |
| `sort_order`        | number    |          | Display order                               |
| `default_notify_on` | string\[] |          | Default events for vessels in this category |

**Example**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/watchlist/categories \
  -d '{"name": "Gulf fleet", "default_notify_on": ["dark_event", "sanctions_match"]}'
```

### `PATCH` `/api/v1/watchlist/categories`

<Note>Requires API key.</Note>

Update a category. Pass the `id` in the request body.

**Example**

```bash theme={null}
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/watchlist/categories \
  -d '{"id": 5, "name": "Gulf fleet — priority"}'
```

### `DELETE` `/api/v1/watchlist/categories`

<Note>Requires API key.</Note>

Delete a category. Vessels in the category are kept but have their `category_id` cleared. Child categories are un-nested.

**Parameters**

| Name | Type   | Required | Description               |
| ---- | ------ | -------- | ------------------------- |
| `id` | number | ✓        | Category id (query param) |

**Example**

```bash theme={null}
curl -X DELETE -H "X-API-Key: YOUR_KEY" \
  "https://axiomoverwatch.io/api/v1/watchlist/categories?id=5"
```

***

## Bulk operations

Add or modify up to 100 vessels at once.

### `POST` `/api/v1/watchlist/bulk`

<Note>Requires API key.</Note>

Add multiple vessels in a single request.

**Parameters**

| Name          | Type      | Required | Description                       |
| ------------- | --------- | -------- | --------------------------------- |
| `imos`        | string\[] | ✓        | Array of IMO numbers (max 100)    |
| `label`       | string    |          | Label applied to all vessels      |
| `notify_on`   | string\[] |          | Event types for all vessels       |
| `category_id` | number    |          | Category to assign all vessels to |

**Example**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/watchlist/bulk \
  -d '{
    "imos": ["9622629", "9622630", "9622631"],
    "category_id": 5,
    "notify_on": ["dark_event", "sanctions_match"]
  }'
```

### `PATCH` `/api/v1/watchlist/bulk`

<Note>Requires API key.</Note>

Perform a bulk action on multiple watched vessels.

**Parameters**

| Name          | Type      | Required | Description                                               |
| ------------- | --------- | -------- | --------------------------------------------------------- |
| `imos`        | string\[] | ✓        | Array of IMO numbers (max 100)                            |
| `action`      | string    | ✓        | `remove`, `set_category`, `set_notify_on`, or `set_label` |
| `category_id` | number    |          | Required for `set_category`                               |
| `notify_on`   | string\[] |          | Required for `set_notify_on`                              |
| `label`       | string    |          | Required for `set_label`                                  |

**Example**

```bash theme={null}
curl -X PATCH -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  https://axiomoverwatch.io/api/v1/watchlist/bulk \
  -d '{
    "imos": ["9622629", "9622630"],
    "action": "set_category",
    "category_id": 5
  }'
```