{"openapi":"3.1.0","info":{"title":"Protheus API","version":"0.1.0","description":"Maritime entities, the relationships between them, and the source record behind every statement."},"servers":[{"url":"https://protheus.si"}],"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"API key, px_..."}},"schemas":{"Entity":{"type":"object","properties":{"id":{"type":"string"},"kind":{"enum":["vessel","party","flag","port","list","detection"]},"name":{"type":"string"},"props":{"type":"object"}}}}},"security":[{"key":[]}],"paths":{"/v1/health":{"get":{"security":[],"summary":"Liveness","responses":{"200":{"description":"Engine and database reachable","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/stats":{"get":{"security":[],"summary":"Counts of entities, relationships and evidence","responses":{"200":{"description":"Counts","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/sources":{"get":{"security":[],"summary":"Every data source, its licence, and the hash of the bytes last ingested","responses":{"200":{"description":"Sources","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/search":{"get":{"summary":"Find entities by name, alias, IMO, MMSI or call sign","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"kind","in":"query","schema":{"enum":["vessel","party","flag","port","list","detection"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":20}}],"responses":{"200":{"description":"Ranked matches with the reason each one matched","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/entities/{id}":{"get":{"summary":"One entity with identifiers, aliases and evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Entity","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"enum":["vessel","party","flag","port","list","detection"]},"name":{"type":"string"},"props":{"type":"object"}}}}}}}}},"/v1/entities/{id}/neighbours":{"get":{"summary":"Direct relationships, each with its evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Neighbours","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/entities/{id}/graph":{"get":{"summary":"Link chart around an entity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"depth","in":"query","schema":{"type":"integer","minimum":1,"maximum":4,"default":2}},{"name":"max_nodes","in":"query","schema":{"type":"integer","maximum":1500,"default":300}}],"responses":{"200":{"description":"Nodes and edges; `truncated` is true when the node cap was hit","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/entities/{id}/timeline":{"get":{"summary":"Dated relationships and events for an entity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Timeline","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/vessels":{"get":{"summary":"List vessels","parameters":[{"name":"flag","in":"query","schema":{"type":"string","description":"ISO 3166 alpha-2"}},{"name":"sanctioned","in":"query","schema":{"type":"boolean"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":500,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Vessels","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/ports":{"get":{"summary":"Ports inside a bounding box","parameters":[{"name":"bbox","in":"query","schema":{"type":"string","description":"west,south,east,north"}}],"responses":{"200":{"description":"Ports","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/ais/live":{"get":{"summary":"Latest position of every AIS transmitter heard recently","parameters":[{"name":"bbox","in":"query","schema":{"type":"string","description":"west,south,east,north"}},{"name":"hours","in":"query","schema":{"type":"number","default":6,"maximum":72}}],"responses":{"200":{"description":"Vessels with position, speed, course and, when identified, the entity id","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/ais/track/{mmsi}":{"get":{"summary":"Stored track of one transmitter","parameters":[{"name":"mmsi","in":"path","required":true,"schema":{"type":"string"}},{"name":"hours","in":"query","schema":{"type":"integer","default":24,"maximum":720}}],"responses":{"200":{"description":"Points ordered by time","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/ais/vessel/{mmsi}/history":{"get":{"summary":"Voyage history: stops with verdicts, voyages between berths, events, broadcast changes","parameters":[{"name":"mmsi","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"History","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/events":{"get":{"summary":"Detected events: ais_gap, rendezvous, mmsi_conflict, identity_change, unusual_stop, destination_mismatch, zone_entry","parameters":[{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"hours","in":"query","schema":{"type":"integer","default":72}},{"name":"min_score","in":"query","schema":{"type":"number"}},{"name":"bbox","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Events, newest first, each with the inputs that produced it","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/zones":{"get":{"summary":"Zones of interest","responses":{"200":{"description":"Zones","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Create a zone from a ring of [lon, lat] points","responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/zones/{id}":{"delete":{"summary":"Delete a zone","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/watch":{"get":{"summary":"Watched vessels","responses":{"200":{"description":"Watch list","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Watch an entity or an MMSI","responses":{"200":{"description":"Added","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/watch/{id}":{"delete":{"summary":"Stop watching","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/notifications":{"get":{"summary":"Notifications raised by watched vessels, zones and high-scoring events","responses":{"200":{"description":"Notifications","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/notifications/read":{"post":{"summary":"Mark notifications read (all when no ids are given)","responses":{"200":{"description":"Marked","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/cases":{"get":{"summary":"Case files","responses":{"200":{"description":"Cases","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Open a case","responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/cases/{id}":{"get":{"summary":"One case with its pinned items","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Case","content":{"application/json":{"schema":{"type":"object"}}}}}},"patch":{"summary":"Edit title, summary or status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"summary":"Delete a case","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/cases/{id}/items":{"post":{"summary":"Pin an entity, an MMSI or an event to a case","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pinned","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/cases/{id}/report":{"get":{"summary":"Printable case report (HTML)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report","content":{"text/html":{}}}}}},"/v1/notes":{"get":{"summary":"Analyst notes on an entity or MMSI","responses":{"200":{"description":"Notes","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"Add a note","responses":{"200":{"description":"Added","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/recipes":{"get":{"summary":"Investigation recipes","responses":{"200":{"description":"Recipes","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/recipes/{name}/run":{"post":{"summary":"Run a recipe on an entity: vessel-profile, owner-fleet, port-activity","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Findings in sections","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/session":{"post":{"security":[],"summary":"Exchange an API key for a browser session cookie","responses":{"200":{"description":"Session opened","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"summary":"Close the session","responses":{"200":{"description":"Closed","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}