Skip to main content
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
NameTypeRequiredDescription
imo_numberstring✓7-digit IMO number
labelstringCustom display label
notify_onstring[]Event types to alert on (defaults below)
category_idnumberCategory to assign the vessel to
sort_ordernumberDisplay 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
EventDescription
port_entryVessel arrives at any monitored port
port_departureVessel departs a monitored port
dark_eventAIS signal gap detected
sanctions_matchVessel 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
NameTypeRequiredDescription
imo_numberstring✓IMO number of the vessel to update
labelstringNew label
notify_onstring[]Updated event list
category_idnumberNew category
sort_ordernumberNew 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
NameTypeRequiredDescription
imostring✓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
NameTypeRequiredDescription
namestring✓Category name
parent_idnumberParent category for nesting
sort_ordernumberDisplay order
default_notify_onstring[]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
NameTypeRequiredDescription
idnumber✓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
NameTypeRequiredDescription
imosstring[]✓Array of IMO numbers (max 100)
labelstringLabel applied to all vessels
notify_onstring[]Event types for all vessels
category_idnumberCategory 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
NameTypeRequiredDescription
imosstring[]✓Array of IMO numbers (max 100)
actionstring✓remove, set_category, set_notify_on, or set_label
category_idnumberRequired for set_category
notify_onstring[]Required for set_notify_on
labelstringRequired 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
  }'