{"openapi":"3.1.0","info":{"title":"Global Fishing Watch (BYOK) API","version":"0.1.0","description":"Global Fishing Watch (BYOK) lets an AI assistant read your own Global Fishing Watch data through the Global Fishing Watch API with a key you supply (Global Fishing Watch API access token). Read-only: 5 tools (search_vessels, get_vessel, list_events, get_event, get_fishing_effort_stats). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached;...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-globalfishingwatch.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-globalfishingwatch/docs"},"termsOfService":"https://connectorbay.com/byok-globalfishingwatch/terms"},"servers":[{"url":"https://byok-globalfishingwatch.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-globalfishingwatch/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_vessels":{"post":{"operationId":"search_vessels","summary":"Search vessels by free text (MMSI, IMO, call sign, name) or an advanced where expression; returns AIS and registry ident","description":"Search vessels by free text (MMSI, IMO, call sign, name) or an advanced where expression; returns AIS and registry identity records (flag, name, IDs, gear, length). Use for \"Find the vessel with MMSI 211307720 in Global Fishing Watch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset":{"description":"Dataset to search, for example public-global-vessel-identity:latest (vessel identity) or public-global-fishing-vessels:latest.","maxLength":80,"title":"Dataset","type":"string"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text search such as an MMSI, IMO, call sign or ship name (at least 3 characters); cannot be combined with `where`.","title":"Query"},"where":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Advanced filter on vessel fields with AND, OR, =, >=, < (LIKE not supported); cannot be combined with `query`.","title":"Where"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (1 to 50).","title":"Limit"},"since":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Continuation token from a previous answer to fetch the next page.","title":"Since"}},"required":["dataset"],"title":"search_vesselsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_vessel":{"post":{"operationId":"get_vessel","summary":"Get the identity of one vessel by its Global Fishing Watch vessel id: AIS self-reported and registry records, gear and o","description":"Get the identity of one vessel by its Global Fishing Watch vessel id: AIS self-reported and registry records, gear and ownership data where available. Use for \"Show the identity details of vessel 9e075a986-6162-fe6e-b25e-81188438a00c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vessel_id":{"description":"Global Fishing Watch vessel id from search_vessels.","maxLength":80,"title":"Vessel Id","type":"string"},"dataset":{"description":"Dataset to read from, for example public-global-vessel-identity:latest.","maxLength":80,"title":"Dataset","type":"string"},"registries_info_data":{"anyOf":[{"enum":["NONE","DELTA","ALL"],"type":"string"},{"type":"null"}],"default":"NONE","description":"Registry data detail: NONE (default), DELTA (changes over time) or ALL.","title":"Registries Info Data"}},"required":["vessel_id","dataset"],"title":"get_vesselArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_events":{"post":{"operationId":"list_events","summary":"List vessel events (fishing, encounters, loitering, port visits, AIS gaps) for a vessel and period from an events datase","description":"List vessel events (fishing, encounters, loitering, port visits, AIS gaps) for a vessel and period from an events dataset, paginated. Use for \"Show fishing events of vessel 9b3e9019d-d67f-005a-9593-b66b997559e5 in March 2017\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset":{"description":"Events dataset, for example public-global-fishing-events:latest or public-global-encounter-events:latest.","maxLength":80,"title":"Dataset","type":"string"},"limit":{"description":"Events per page (1 to 100).","maximum":100,"minimum":1,"title":"Limit","type":"integer"},"offset":{"description":"Events to skip, starting at 0.","minimum":0,"title":"Offset","type":"integer"},"vessel_id":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Global Fishing Watch vessel id to restrict events to.","title":"Vessel Id"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Event start date, YYYY-MM-DD (inclusive).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Event end date, YYYY-MM-DD (exclusive).","title":"End Date"}},"required":["dataset","limit","offset"],"title":"list_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_event":{"post":{"operationId":"get_event","summary":"Get one event by id with its position, time span, distances, regions and vessel details. Use for \"Show details of event ","description":"Get one event by id with its position, time span, distances, regions and vessel details. Use for \"Show details of event a6e00481737d3e2c9903e1f565c51143\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"Event id from list_events.","maxLength":80,"title":"Event Id","type":"string"},"dataset":{"description":"Events dataset, for example public-global-fishing-events:latest.","maxLength":80,"title":"Dataset","type":"string"}},"required":["event_id","dataset"],"title":"get_eventArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_fishing_effort_stats":{"post":{"operationId":"get_fishing_effort_stats","summary":"Get worldwide fishing-effort statistics for a date range: number of vessel ids, flags and activity hours with the boundi","description":"Get worldwide fishing-effort statistics for a date range: number of vessel ids, flags and activity hours with the bounding box. Use for \"How many fishing activity hours did Global Fishing Watch record from January to March 2021\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"fields":{"description":"Statistics to compute, comma-separated from VESSEL-IDS, FLAGS, ACTIVITYHOURS.","maxLength":60,"title":"Fields","type":"string"},"dataset":{"description":"Fishing-effort dataset, for example public-global-fishing-effort:latest.","maxLength":80,"title":"Dataset","type":"string"},"date_range":{"description":"Start and end date separated by a comma, YYYY-MM-DD,YYYY-MM-DD.","maxLength":21,"title":"Date Range","type":"string"},"filters":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Filter on the dataset, for example \"flag in ('ESP')\" or geartype filters.","title":"Filters"}},"required":["fields","dataset","date_range"],"title":"get_fishing_effort_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}