Watchlists

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`

Requires API key.

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

{
  "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

curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/watchlist

`POST` `/api/v1/watchlist`

Requires API key.

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

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`

Requires API key.

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

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`

Requires API key.

Remove a vessel from your watchlist. Parameters

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

Example

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`

Requires API key.

List all watchlist categories. Response

{
  "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

curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/watchlist/categories

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

Requires API key.

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

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`

Requires API key.

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

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`

Requires API key.

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

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`

Requires API key.

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

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`

Requires API key.

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

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
  }'

Overview

Vessels & ports

Risk & anomaly

Operations & throughput

Sustainability & fleet

Satellite & geo

Commodities

Insurance

Trade & market

Platform

`GET` `/api/v1/watchlist`

`POST` `/api/v1/watchlist`

`PATCH` `/api/v1/watchlist`

`DELETE` `/api/v1/watchlist`

Categories

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

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

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

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

Bulk operations

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

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

​GET /api/v1/watchlist

​POST /api/v1/watchlist

​PATCH /api/v1/watchlist

​DELETE /api/v1/watchlist

​Categories

​GET /api/v1/watchlist/categories

​POST /api/v1/watchlist/categories

​PATCH /api/v1/watchlist/categories

​DELETE /api/v1/watchlist/categories

​Bulk operations

​POST /api/v1/watchlist/bulk

​PATCH /api/v1/watchlist/bulk

`GET` `/api/v1/watchlist`

`POST` `/api/v1/watchlist`

`PATCH` `/api/v1/watchlist`

`DELETE` `/api/v1/watchlist`

Categories

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

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

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

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

Bulk operations

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

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